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

PUT Object - Copy

Description

This implementation of the PUT operation creates a copy of an object that is already stored in Amazon S3. A PUT copy operation is the same as performing a GET and then a PUT. Adding the request header, x-amz-copy-source, makes the PUT operation copy the source object into the destination bucket.

Note

You can store individual objects of up to 5 TB in Amazon S3. You create a copy of your object up to 5 GB in size in a single atomic operation using this API. However, for copying an object greater than 5 GB, you must use the multipart upload Upload Part - Copy API. For conceptual information, see Copy Object Using the REST Multipart Upload API in the Amazon Simple Storage Service Developer Guide.

When copying an object, you can preserve most of the metadata (default) or specify new metadata. However, the ACL is not preserved and is set to private for the user making the request.

Important

Amazon S3 Transfer Acceleration does not support cross region copies. You will get a 400 Bad Request error if you request a cross region copy using a Transfer Acceleration endpoint. For more information about transfer acceleration, see Transfer Acceleration in the Amazon Simple Storage Service Developer Guide.

All copy requests must be authenticated and cannot contain a message body. Additionally, you must have READ access to the source object and WRITE access to the destination bucket. For more information, see REST Authentication.

To copy an object only under certain conditions, such as whether the ETag matches or whether the object was modified before or after a specified date, use the request headers x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, or x-amz-copy-source-if-modified-since.

Note

All headers prefixed with x-amz- must be signed, including x-amz-copy-source.

You can use this operation to change the storage class of an object that is already stored in Amazon S3 using the x-amz-storage-class request header. For more information, go to Storage Classes in the Amazon Simple Storage Service Developer Guide.

The source object that you are copying can be encrypted or unencrypted. If the source object is encrypted, it can be encrypted by server-side encryption using AWS-managed encryption keys or by using a customer-provided encryption key. When copying an object, you can request that Amazon S3 encrypt the target object by using either the AWS-managed encryption keys or by using your own encryption key, regardless of what form of server-side encryption was used to encrypt the source or if the source object was not encrypted. For more information about server-side encryption, go to Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.

There are two opportunities for a copy request to return an error. One can occur when Amazon S3 receives the copy request and the other can occur while Amazon S3 is copying the files. If the error occurs before the copy operation starts, you receive a standard Amazon S3 error. If the error occurs during the copy operation, the error response is embedded in the 200 OK response. This means that a 200 OK response can contain either a success or an error. Make sure to design your application to parse the contents of the response and handle it appropriately.

If the copy is successful, you receive a response that contains the information about the copied object.

Note

If the request is an HTTP 1.1 request, the response is chunk encoded. Otherwise, it will not contain the content-length and you will need to read the entire body.

Access Permissions

When copying an object, you can optionally specify the accounts or groups that should be granted specific permissions on the new object. There are two ways to grant the permissions using the request headers:

• Specify a canned ACL using the x-amz-acl request header. For more information, see Canned ACL in the Amazon Simple Storage Service Developer Guide.

• Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-read-acp, x-amz-grant-write-acp, and x-amz-grant-full-control headers. These headers map to the set of permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL) Overview in the Amazon Simple Storage Service Developer Guide.

Note

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

Requests

Syntax

PUT /destinationObject HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
x-amz-copy-source: /source_bucket/sourceObject
x-amz-metadata-directive: metadata_directive
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
<request metadata>
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
		4))
Date: date

Note

The syntax shows only some of the request headers. For a complete list, see the Request Headers section.

Request Parameters

This implementation of the 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 key name of the source object, separated by a slash (/). Type: String Default: None Constraints: This string must be URL-encoded. Additionally, the source bucket must be valid and you must have READ access to the valid source object. If the source object is archived in Amazon Glacier (storage class of the object is GLACIER), you must first restore a temporary copy using the POST Object restore. Otherwise, Amazon S3 returns the 403 ObjectNotInActiveTierError error response.	Yes
x-amz-metadata-directive	Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request. If copied, the metadata, except for the version ID, remains unchanged. In addition, the server-side-encryption, storage-class, and website-redirect-location metadata from the source is not copied. If you specify this metadata explicitly in the copy request, Amazon S3 adds this metadata to the resulting object. If you specify headers in the request specifying any user-defined metadata, Amazon S3 ignores these headers. If replaced, all original metadata is replaced by the metadata you specify. Type: String Default: COPY Valid values: COPY | REPLACE Constraints: Values other than COPY or REPLACE result in an immediate 400-based error response. You cannot copy an object to itself unless the MetadataDirective header is specified and its value set to REPLACE. For information on supported metadata, see Common Request Headers	No
x-amz-copy-source-if-match	Copies the object if its entity tag (ETag) matches the specified tag; otherwise, the request returns a 412 HTTP status code error (failed precondition). See Consideration 1 after the table. Type: String Default: None Constraints: This header can be used with x-amz-copy-source-if-unmodified-since, but cannot be used with other conditional copy headers.	No
x-amz-copy-source-if-none-match	Copies the object if its entity tag (ETag) is different than the specified ETag; otherwise, the request returns a 412 HTTP status code error (failed precondition). See Consideration 2 after the table. Type: String Default: None Constraints: This header can be used with x-amz-copy-source-if-modified-since, but cannot be used with other conditional copy headers.	No
x-amz-copy-source-if-unmodified-since	Copies the object if it hasn't been modified since the specified time; otherwise, the request returns a 412 HTTP status code error (failed precondition). See Consideration 1 after the table. Type: String Default: None Constraints: This must be a valid HTTP date. This header can be used with x-amz-copy-source-if-match, but cannot be used with other conditional copy headers.	No
x-amz-copy-source-if-modified-since	Copies the object if it has been modified since the specified time; otherwise, the request returns a 412 HTTP status code error (failed condition). See Consideration 2 after the table. Type: String Default: None Constraints: This must be a valid HTTP date. This header can be used with x-amz-copy-source-if-none-match, but cannot be used with other conditional copy headers.	No
x-amz-storage-class	If you don't specify, Standard is the default storage class. Amazon S3 supports other storage classes. For more information, go to Storage Classes in the Amazon Simple Storage Service Developer Guide. Type: Enum Default: STANDARD Valid Values: STANDARD | STANDARD_IA | REDUCED_REDUNDANCY Constraints: You cannot specify GLACIER as the storage class. To transition objects to the GLACIER storage class, you can use lifecycle configuration. For more information, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.	No
x-amz-tagging-directive	Specifies whether the object tags are copied from the source object or replaced with tags provided in the request. If copied, the tagset remains unchanged. If replaced, all original tagset is replaced by the tags you specify. S3 copies tags by default if you don't specify tagging directive. If tagging directive is REPLACE, you specify any tags in url format in the x-amz-tagging header similar to PUT object with tags. If tagging directive is REPLACE, but you don't specify the x-amz-tagging in the request, the destination object will not have any tags. Type: String Default: COPY Valid values: COPY | REPLACE Constraints: Values other than COPY or REPLACE result in an immediate 400-based error response.	No
x-amz-website​-redirect-location	If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata. For information about object metadata, go to Object Key and Metadata. In the following example, the request header sets the redirect to an object (anotherPage.html) in the same bucket: x-amz-website-redirect-location: /anotherPage.html In the following example, the request header sets the object redirect to another website: x-amz-website-redirect-location: http://www.example.com/ For more information about website hosting in Amazon S3, go to sections Hosting Websites on Amazon S3 and How to Configure Website Page Redirects in the Amazon Simple Storage Service Developer Guide. Type: String Default: None Constraints: The value must be prefixed by, "/", "http://" or "https://". The length of the value is limited to 2 K.	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 want your target object encrypted, you will need to provide appropriate encryption related request headers depending on whether you want to use AWS-managed encryption keys or provide your own encryption key:

• If you want the target object encrypted using server-side encryption with an AWS-managed encryption key, you provide the following request header.

  Name	Description	Required
  x-amz-server-side​-encryption	Specifies a server-side encryption algorithm to use when Amazon S3 creates an object. Type: String Valid Value: aws:kms, AES256	Yes
  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	Yes, if the value of x-amz-server-side-encryption is aws:kms
  x-amz-server-side-encryption-context	If x-amz-server-side-encryption is present, and if its value is aws:kms, this header specifies the encryption context for the object. The value of this header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs. Type: String	No

  Note

  If you specify x-amz-server-side-encryption:aws:kms, but do not provide x-amz-server-side- encryption-aws-kms-key-id, the default AWS KMS key will be used to protected the data.

  Important

  All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or by using SigV4.

  For more information on Server-Side Encryption with Amazon KMS-Managed Keys (SSE-KMS), go to Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys in the Amazon Simple Storage Service Developer Guide.

• If you want the target object encrypted using server-side encryption with an encryption key you provide, you must provide encryption information 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 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 value is used to store the object and then is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header. Type: String Default: None Constraints: Must be accompanied by 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 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 customer-provided encryption keys, 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 the algorithm to use when decrypting the source object. Type: String Default: None Valid Value: AES256 Constraints: Must be accompanied by 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 base64-encoded encryption key for Amazon S3 to use to decrypt the source object. After the copy operation, Amazon S3 will discard this key. 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 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 valid x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side​-encryption-customer-key headers.	Yes

  For more information on Server-Side Encryption with Customer-Provided Encryption Keys (SSE-C), go to Protecting Data Using Server-Side Encryption with Customer-Provided Encryption Keys (SSE-C) in the Amazon Simple Storage Service Developer Guide.

Access Control List (ACL) Specific Request Headers

Additionally, you can use the following access control–related headers with this operation. By default, all objects are private; only the owner has full access control. When adding a new object, you can grant permissions to individual AWS accounts or predefined groups defined by Amazon S3. These permissions are then added to the Access Control List (ACL) on the object. For more information, go to Using ACLs. This operation enables you to grant access permissions using one of the following two methods:

• Specify a canned ACL — Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more information, go to Canned ACL.

  Name	Description	Required
  x-amz-acl	The canned ACL to apply to the object. Type: String Default: private Valid Values: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control Constraints: None	No

• Specify access permissions explicitly — If you want to explicitly grant access permissions to specific AWS accounts or groups, you can use the following headers. Each of these headers maps to specific permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL) Overview. In the header, you specify a list of grantees who get the specific permission.

  Name	Description	Required
  x-amz-grant-read	Allows grantee to read the object data and its metadata. Type: String Default: None Constraints: None	No
  x-amz-grant-write	Not applicable. This applies only when granting access permissions on a bucket. Type: String Default: None Constraints: None	No
  x-amz-grant-read-acp	Allows grantee to read the object ACL. Type: String Default: None Constraints: None	No
  x-amz-grant-write-acp	Allows grantee to write the ACL for the applicable object. Type: String Default: None Constraints: None	No
  x-amz-grant-full-control	Allows grantee the READ, READ_ACP, and WRITE_ACP permissions on the object. Type: String Default: None Constraints: None	No

You specify each grantee as a type=value pair, where the type can be one of the following:

• emailAddress – if value specified is the email address of an AWS account

• id – if value specified is the canonical user ID of an AWS account

• uri – if granting permission to a predefined group.

For example, the following x-amz-grant-read header grants read object data and its metadata permission to the AWS accounts identified by their email addresses.

x-amz-grant-read: emailAddress="[e-mail]", emailAddress="[e-mail]"

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

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

Name	Description
x-amz-expiration	Amazon S3 will return this header if an Expiration action is configured for the object as part of the bucket's lifecycle configuration.  The header value includes an "expiry-date" component and a URL-encoded "rule-id" component.  Note that for version-enabled buckets, this header applies only to current versions; Amazon S3 does not provide a header to infer when a noncurrent version will be eligible for permanent deletion. For more information, see PUT Bucket lifecycle. Type: String
x-amz-copy-source-version-id	Version of the source object that was copied. 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 copy 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 (SSE-C) encryption was requested, the response will include this header confirming the encryption algorithm used for the destination object. Type: String Valid Values: AES256
x-amz-server-side​-encryption​-customer-key-MD5	If SSE-C encryption was requested, the response includes this header to provide roundtrip message integrity verification of the customer-provided encryption key used to encrypt the destination object. Type: String
x-amz-version-id	Version of the copied object in the destination bucket. Type: String

Response Elements

Name	Description
CopyObjectResult	Container for all response elements. Type: Container Ancestor: None
ETag	Returns the ETag of the new object. The ETag reflects changes only to the contents of an object, not its metadata. The source and destination ETag will be identical for a successfully copied object. Type: String Ancestor: CopyObjectResult
LastModified	Returns the date the object was last modified. Type: String Ancestor: CopyObjectResult

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Request

This example copies my-image.jpg into the bucket, bucket, with the key name my-second-image.jpg.

PUT /my-second-image.jpg HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

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

x-amz-version-id returns the version ID of the object in the destination bucket, and x-amz-copy-source-version-id returns the version ID of the source object.

Sample Request: Copying a specified version of an object

The following request copies the key my-image.jpg with the specified version ID and copies it into the bucket bucket and gives it the key my-second-image.jpg.

PUT /my-second-image.jpg HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Authorization: authorization string

Success Response: Copying a versioned object into a version enabled bucket

The following response shows that an object was copied into a target bucket where Versioning is enabled.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
 x-amz-copy-source-version-id: 09df8234529fjs0dfi0w52935029wefdj
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3
 
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
   <LastModified>2009-10-28T22:32:00</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

Success Response: Copying a versioned object into a version-suspended bucket

The following response shows that an object was copied into a target bucket where versioning is suspended. Note that the parameter <VersionId> does not appear.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <LastModified>2009-10-28T22:32:00</LastModified>
  <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

Sample: Copy from unencrypted object to an object encrypted with server-side encryption with customer-provided encryption keys

The following example specifies the HTTP PUT header to copy an unencrypted object to an object encrypted with server-side encryption with customer-provided encryption keys (SSE-C).

PUT /exampleDestinationObject HTTP/1.1
Host: example-destination-bucket.s3.amazonaws.com	
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: Base64(YourKey)
x-amz-server-side-encryption-customer-key-MD5 : Base64(MD5(YourKey))
x-amz-metadata-directive: metadata_directive
x-amz-copy-source: /example_source_bucket/exampleSourceObject
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
<request metadata>	
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
		4))
Date: date

Sample: Copy from an object encrypted with SSE-C to an object encrypted with SSE-C

The following example specifies the HTTP PUT header to copy an object encrypted with server-side encryption with customer-provided encryption keys to an object encrypted with server-side encryption with customer-provided encryption keys for key rotation.

PUT /exampleDestinationObject HTTP/1.1
Host: example-destination-bucket.s3.amazonaws.com	
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: Base64(NewKey)
x-amz-server-side-encryption-customer-key-MD5: Base64(MD5(NewKey))
x-amz-metadata-directive: metadata_directive
x-amz-copy-source: /source_bucket/sourceObject
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
x-amz-copy-source-server-side-encryption-customer-algorithm: AES256
x-amz-copy-source-server-side-encryption-customer-key: Base64(OldKey)
x-amz-copy-source-server-side-encryption-customer-key-MD5: Base64(MD5(OldKey))
<request metadata>	
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
		4))
Date: date

Related Resources

• Copying Objects

• PUT Object

• GET Object