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 » PUT Object - Copy
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

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.

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: signatureValue
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-server-side​-encryption

Specifies the server-side encryption algorithm to use when Amazon S3 creates the target object.

Type: String

Valid Value: AES256

 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

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. For more information, go to REST Access Policy in the Amazon Simple Storage Service Developer Guide.

    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

If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key-value pairs providing object expiration information. The value of the rule-id is URL encoded.

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-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 only reflects changes 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: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

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: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

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>

Related Resources

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...