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 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
andx-amz-copy-source-if-unmodified-since
headers are present in the request as follows:x-amz-copy-source-if-match
condition evaluates totrue
, and;x-amz-copy-source-if-unmodified-since
condition evaluates tofalse
;then, S3 returns
200 OK
and copies the data. -
Consideration 2 – If both of the
x-amz-copy-source-if-none-match
andx-amz-copy-source-if-modified-since
headers are present in the request as follows:x-amz-copy-source-if-none-match
condition evaluates tofalse
, and;x-amz-copy-source-if-modified-since
condition evaluates totrue
;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: Constraints: Must be accompanied by a valid
|
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
|
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
|
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: Constraints: Must be accompanied by a valid
|
Yes |
|
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
|
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
|
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 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: |
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 Type: String Ancestor: |
LastModified
|
Returns the date the part was last modified. Type: String Ancestor: |
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>