AWS Documentation » Amazon Simple Storage Service (S3) » API Reference » Operations on Objects » Upload Part - Copy

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.

The minimum allowable part size for a multipart upload is 5 MB. For more information about multipart upload limits, go to Quick Facts in the Amazon Simple Storage Service Developer Guide.

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 more information on using the upload part - copy operation, see the following topics:

• For conceptual information on multipart uploads, go to Uploading Objects Using Multipart Upload in the Amazon Simple Storage Service Developer Guide.

• For information on permissions required to use the multipart upload API, go to Multipart Upload API and Permissions in the Amazon Simple Storage Service Developer Guide.

• For information about copying objects using a single atomic operation vs. the multipart upload, go to Operations on Objects in the Amazon Simple Storage Service Developer Guide.

• For information about using server-side encryption with customer-provided encryption keys with the upload part - copy operation, see PUT Object - Copy and Upload Part.

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: authorization string

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. Request headers are limited to 8 KB in size. 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. 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. See Consideration 1 after the table. 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. See Consideration 2 after the table. 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. See Consideration 1 after the table. 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. See Consideration 2 after the table. Type: String Default: None	No

Note the following additional considerations about the preceding request headers:

• Consideration 1 – If both of the x-amz-copy-source-if-match and x-amz-copy-source-if-unmodified-since headers are present in the request as follows:

  x-amz-copy-source-if-match condition evaluates to true, and;

  x-amz-copy-source-if-unmodified-since condition evaluates to false;

  then, S3 returns 200 OK and copies the data.

   

• Consideration 2 – If both of the x-amz-copy-source-if-none-match and x-amz-copy-source-if-modified-since headers are present in the request as follows:

  x-amz-copy-source-if-none-match condition evaluates to false, and;

  x-amz-copy-source-if-modified-since condition evaluates to true;

  then, S3 returns 412 Precondition Failed response code.

Server-Side Encryption Specific Request Headers

If you requested server-side encryption using a customer-provided encryption key in your initiate multipart upload request, you must provide identical encryption information in each part upload using the following headers.

Name	Description	Required
x-amz-server-side​-encryption​-customer-algorithm	Specifies the algorithm to use to when encrypting the object. Type: String Default: None Valid Value: AES256 Constraints: Must be accompanied by a valid x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5 headers.	Yes
x-amz-server-side​-encryption​-customer-key	Specifies the customer provided base64-encoded encryption key for Amazon S3 to use in encrypting data. This must be the same encryption key specified in the initiate multipart upload request. Type: String Default: None Constraints: Must be accompanied by a valid x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5 headers.	Yes
x-amz-server-side​-encryption​-customer-key-MD5	Specifies the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header as a message integrity check to ensure the encryption key was transmitted without error. Type: String Default: None Constraints: Must be accompanied by a valid x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key headers.	Yes

If the source object is encrypted using server-side encryption with a customer-provided encryption key, you must use the following headers providing encryption information so that Amazon S3 can decrypt the object for copying.

Name	Description	Required
x-amz-copy-source​-server-side​-encryption​-customer-algorithm	Specifies algorithm to use when decrypting the source object. Type: String Default: None Valid Value: AES256 Constraints: Must be accompanied by a valid x-amz-copy-source-server-side-encryption-customer-key and x-amz-copy-source-server-side-encryption-customer-key-MD5 headers.	Yes
x-amz-copy-source​-server-side​-encryption​-customer-key	Specifies the customer provided base-64 encoded encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created. Type: String Default: None Constraints: Must be accompanied by a valid x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side-encryption-customer-key-MD5 headers.	Yes
x-amz-copy-source-​server-side​-encryption​-customer-key-MD5	Specifies the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Type: String Default: None Constraints: Must be accompanied by a valid x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side​-encryption-customer-key headers.	Yes

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 current version of the object to copy. If the current 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 responses. 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 either with an AWS KMS or Amazon S3-managed encryption key in your initiate multipart upload request, the response includes this header. It confirms the encryption algorithm that Amazon S3 used to encrypt the object. Type: String
x-amz-server-side-encryption-aws-kms-key-id	If the x-amz-server-side-encryption is present and has the value of aws:kms, this header specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object. Type: String
x-amz-server-side​-encryption​-customer-algorithm	If server-side encryption with customer-provided encryption keys encryption was requested, the response will include this header confirming the encryption algorithm used. Type: String Valid Values: AES256
x-amz-server-side​-encryption​-customer-key-MD5	If server-side encryption with customer-provided encryption keys encryption was requested, the response includes this header to provide roundtrip message integrity verification of the customer-provided encryption key. 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

Important

Part boundaries are factored into ETag calculations, so if the part boundary on the source is different than on the destination, then the ETag data will not match between the two. However, data integrity checks are performed with each copy to ensure that the data written to the destination matches the data at the source.

Special Errors

Error Code	Description	HTTP Status Code
NoSuchUpload	The 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
InvalidRequest	The 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: authorization string

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>2011-04-11T20:34:56.000Z</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: authorization string
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: authorization string

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>2011-04-11T20:34:56.000Z</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyPartResult>

Related Actions

• Initiate Multipart Upload

• Upload Part

• Complete Multipart Upload

• Abort Multipart Upload

• List Parts

• List Multipart Uploads