Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.

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 API. For conceptual information on multipart upload, go to Uploading Objects Using Multipart Upload 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.

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 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 Changing the Storage Class of an Object in Amazon S3 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. 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).

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).

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).

Type: String

Default: None

Constraints: This must be a valid HTTP date. For more information, go to http://www.ietf.org/rfc/rfc2616.txt. 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).

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

RRS enables customers to reduce their costs by storing noncritical, reproducible data at lower levels of redundancy than Amazon S3's standard storage.

Type: Enum

Default: STANDARD

Valid Values: STANDARD | REDUCED_REDUNDANCY

Constraints: You cannot specify GLACIER as the storage class. To transition objects to the GLACIER storage class you can use lifecycle configuration.

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

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 specifices 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

    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 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 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

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 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 | 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="xyz@amazon.com", emailAddress="abc@amazon.com"

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 request server-side encryption, the response includes this header confirming the encryption algorithm used for the target 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.

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