Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
AWS Documentation » Amazon Simple Storage Service (S3) » API Reference » REST API » Operations on Objects » Upload Part - Copy
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

Upload Part - Copy

Description

Uploads a part by copying data from an existing object as data source. You specify the data source by adding the request header x-amz-copy-source in your request and a byte range by adding the request header x-amz-copy-source-range in your request.

[Note]Note

Instead of using an existing object as part data, you might use the Upload Part operation and provide data in your request. For more information, see Upload Part.

You must initiate a multipart upload before you can upload any part. In response to your initiate request. Amazon S3 returns a unique identifier, the upload ID, that you must include in your upload part request.

For conceptual information on multipart uploads, go to Uploading Objects Using Multipart Upload in the Amazon S3 Developer guide. For information on permissions required to use the multipart upload API, go to Multipart Upload API and Permissions in the Amazon S3 Developer guide. To more information about copying objects using a single atomic operation vs. the multipart upload, go to Operations On Objects in the Amazon S3 Developer guide.

Requests

Syntax

PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: BucketName.s3.amazonaws.com
x-amz-copy-source: /source_bucket/sourceObject
x-amz-copy-source-range:bytes=first-last
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
Date: date
Authorization: Signature

Request Parameters

This operation does not use request parameters.

Request Headers

This implementation of the operation can use the following request headers in addition to the request headers common to all operations. For more information, see Common Request Headers.

Name Description Required
x-amz-copy-source

The name of the source bucket and the source object key name separated by a slash ('/').

Type: String

Default: None

 Yes
x-amz-copy-source-range

The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first ten bytes of the source.

You can copy a range only if the source object is greater than 5 GB.

This request header is not required when copying an entire source object.

Type: Integer

Default: None

 No

The following conditional headers are based on the object that the x-amz-copy-source header specifies.

Name Description Required
x-amz-copy-source-if-match

Perform a copy if the source object entity tag (ETag) matches the specified value. If the value does not match, Amazon S3 returns an HTTP status code 412 precondition failed error.

Type: String

Default: None

 No
x-amz-copy-source-if-none-match

Perform a copy if the source object entity tag (ETag) is different than the value specified using this header. If the values match, Amazon S3 returns an HTTP status code 412 precondition failed error.

Type: String

Default: None

 No
x-amz-copy-source-if-unmodified-since

Perform a copy if the source object is not modified after the time specified using this header. If the source object is modified, Amazon S3 returns an HTTP status code 412 precondition failed error.

Type: String

Default: None

 No
x-amz-copy-source-if-modified-since

Perform a copy if the source object is modified after the time specified using this header. If the source object is not modified, Amazon S3 returns an HTTP status code 412 precondition failed error.

Type: String

Default: None

 No

Request Elements

This operation does not use request elements.

Versioning

If your bucket has versioning enabled, you could have multiple versions of the same object. By default, x-amz-copy-source identifies the latest version of the object to copy. If the latest version is a delete marker and you don't specify a versionId in the x-amz-copy-source, Amazon S3 returns a 404 error, because the object does not exist. If you specify versionId in the x-amz-copy-source and the versionId is a delete marker, Amazon S3 returns an HTTP 400 error, because you are not allowed to specify a delete marker as a version for the x-amz-copy-source.

You can optionally specify a specific version of the source object to copy by adding the versionId subresource as shown in the following example:

x-amz-copy-source: /bucket/object?versionId=version id

Responses

Response Headers

This implementation of the operation can include the following headers in addition to the response headers common to all response. For more information, see Common Response Headers.

Name Description
x-amz-copy-source-version-id

The version of the source object that was copied, if you have enabled versioning on the source bucket.

Type: String

x-amz-server-side-encryption

If you specified server-side encryption in your initiate multipart upload request, the response includes this header. It confirms the encryption algorithm that Amazon S3 used to encrypt the part that you uploaded.

Type: String

Response Elements

Name Description
CopyPartResult

Container for all response elements.

Type: Container

Ancestor: None

ETag

Returns the ETag of the new part.

Type: String

Ancestor: CopyPartResult

LastModified

Returns the date the part was last modified.

Type: String

Ancestor: CopyPartResult

Special Errors

Error CodeDescriptionHTTP Status Code
NoSuchUploadThe specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed.404 Not Found
InvalidRequestThe specified copy source is not supported as a byte-range copy source.400 Bad Request

For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

As the following examples illustrate, when a request succeeds, Amazon S3 returns <CopyPartResult> in the body. If you included versionId in the request, Amazon S3 returns the version ID in the x-amz-copy-source-version-id response header.

Sample Request

The following PUT request uploads a part (part number 2) in a multipart upload. The request specifies a byte range from an existing object as the source of this upload. The request includes the upload ID that you get in response to your Initiate Multipart Upload request. 

PUT /newobject?partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.amazonaws.com
Date:  Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
x-amz-copy-source-range:bytes=500-6291456
Authorization: AWS AKIAIOSFODNN7EXAMPLE:VGhpcyBtZXNzYWdlIHNpZ25lZGGieSRlbHZpbmc=

Sample Response

The response includes the ETag value. You need to retain this value to use when you send the Complete Multipart Upload request.

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date:  Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3 

<CopyPartResult>
   <LastModified>2009-10-28T22:32:00</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyPartResult>

Sample Request

The following PUT request uploads a part (part number 2) in a multipart upload. The request does not specify the optional byte range header, but requests the entire source object copy as part 2. The request includes the upload ID that you got in response to your Initiate Multipart Upload request. 

PUT /newobject?partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.amazonaws.com
Date:  Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
Authorization: AWS AKIAIOSFODNN7EXAMPLE:VGhpcyBtZXNzYWdlIHNpZ25lZGGieSRlbHZpbmc=
Sample Response

The response structure is similar to the one specified in the preceding example.

Sample Request

The following PUT request uploads a part (part number 2) in a multipart upload. The request specifies a specific version of the source object to copy by adding the versionId subresource. The byte range requests 6 MB of data, starting with byte 500, as the part to be uploaded. 

PUT /newobject?partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.amazonaws.com
Date:  Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-copy-source-range:bytes=500-6291456
Authorization: AWS AKIAIOSFODNN7EXAMPLE:VGhpcyBtZXNzYWdlIHNpZ25lZGGieSRlbHZpbmc=

Sample Response

The response includes the ETag value. You need to retain this value to use when you send the Complete Multipart Upload request.

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Date:  Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3 

<CopyPartResult>
   <LastModified>2009-10-28T22:32:00</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyPartResult>
Document Conventions
Terms of Use		Did this page help you?  Yes  No   Tell us about it...