COPY Object

Description

The copy operation creates a copy of an object that is already storedin Amazon S3.

When copying an object, you can preserve all metadata (default) or specify new metadata. However, the ACL is not preserved and is set to private for the user making the request. To override the default ACL setting, specify a new ACL when generating a copy request. For more information, see Access Control Lists.

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 Authenticating REST Requests.

To only copy an object 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 must have write access to the destination bucket and read access on the source bucket.

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

Date: date

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.	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, it remains unchanged. Otherwise, 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 Headers	No
`x-amz-copy-source-if-match`	Copies the object if its entity tag (ETag) matches the specified tag; otherwise return a 412 (precondition failed). 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 returns a 412 (failed condition). 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 returns a 412 (precondition failed). Type: String Default: None Constraints: This must be a valid HTTP date (go to http://rfc.net/rfc2616.html#s3.3). 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 returns a 412 (failed condition). Type: String Default: None Constraints: This must be a valid HTTP date (go to http://rfc.net/rfc2616.html#s3.3). This header can be used with `x-amz-copy-source-if-none-match`, but cannot be used with other conditional copy headers.	No

Responses

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

This means that a 200 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.

Success Response

Syntax


HTTP/1.1 200 OK

x-amz-id-2: id

x-amz-request-id: request_id

Date: date

Content-Length: 0

Content-Type: application/xml

Server: AmazonS3



<?xml version="1.0" encoding="UTF-8"?>



...some amount of whitespace...



<CopyObjectResult>

   <LastModified>timestamp</LastModified>

   <ETag>"etag"</ETag>

</CopyObjectResult>

Elements

Name Description

Name	Description
`LastModified`	Returns the date the object was last modified. Type: String Ancestor: CopyObjectResult
`Etag`	Returns the Etag of the new object. Type: String Ancestor: CopyObjectResult

LastModified

Returns the date the object was last modified.

Type: String

Ancestor: CopyObjectResult

Etag

Returns the Etag of the new object.

Type: String

Ancestor: CopyObjectResult

If the copy was not successful, you receive an error XML document.

Error Response

Syntax


HTTP/1.1 200 OK

x-amz-id-2: id

x-amz-request-id: request_id

Date: date

Content-Type: content_type

Server: AmazonS3



<?xml version="1.0" encoding="UTF-8"?>



...some amount of whitespace...



<Error>

  <Code>error_code</Code>

  <Message>error_message</Message>

  <RequestId>request_id</RequestId>

  <HostId>host_id</HostId>

</Error>

Elements

Name	Description
`Code`	Error code associated with the error. Type: String Ancestor: Error
`Message`	Error message associated with the error. Type: String Ancestor: Error
`RequestId`	ID of the request associated with the error. Type: String Ancestor: Error
`HostId`	ID of the host that returned the error. Type: String Ancestor: Error

For information about general response elements, see Response Headers.

Special Errors

There are no special errors for this operation. For information about general Amazon S3 errors, see List of Error Codes.

Examples

This example copies the flotsam object from the pacific bucket to the jetsam object of the atlantic bucket, preserving its metadata.

Sample Request

PUT /jetsam HTTP/1.1

Host: atlantic.s3.amazonaws.com

x-amz-copy-source: /pacific/flotsam

Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Date: Wed, 20 Feb 2008 22:12:21 +0000

Sample Response


HTTP/1.1 200 OK

x-amz-id-2: Vyaxt7qEbzv34BnSu5hctyyNSlHTYZFMWK4FtzO+iX8JQNyaLdTshL0KxatbaOZt

x-amz-request-id: 6B13C3C5B34AF333

Date: Date: Wed, 20 Feb 2008 22:13:01 +0000

Content-Type: application/xml

Transfer-Encoding: chunked

Connection: close

Server: AmazonS3



<?xml version="1.0" encoding="UTF-8"?>



<CopyObjectResult>

   <LastModified>2008-02-20T22:13:01</LastModified>

   <ETag>"7e9c608af58950deeb370c98608ed097"</ETag>

</CopyObjectResult>

This example copies the "tweedledee" object from the wonderland bucket to the "tweedledum" object of the wonderland bucket, replacing its metadata.

Sample Request

PUT /tweedledum HTTP/1.1

Host: wonderland.s3.amazonaws.com

x-amz-copy-source: /wonderland/tweedledee

x-amz-metadata-directive: REPLACE

x-amz-meta-relationship: twins

Content-Type: text/plain

Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Date: Wed, 20 Feb 2008 22:12:21 +0000

Sample Response


HTTP/1.1 200 OK

x-amz-id-2: Vyaxt7qEbzv34BnSu5hctyyNSlHTYZFMWK4FtzO+iX8JQNyaLdTshL0KxatbaOZt

x-amz-request-id: 6B13C3C5B34AF334

Date: Date: Wed, 20 Feb 2008 22:13:01 +0000

Content-Type: application/xml

Transfer-Encoding: chunked

Connection: close

Server: AmazonS3



<?xml version="1.0" encoding="UTF-8"?>



<CopyObjectResult>

   <LastModified>2008-02-20T22:13:01</LastModified>

   <ETag>"7e9c608af58950deeb370c98608ed097"</ETag>

</CopyObjectResult>

COPY Object

Description

Requests

Syntax

Headers

Responses

Success Response

Syntax

Elements

Error Response

Syntax

Elements

Special Errors

Examples

Sample Request

Sample Response

Sample Request

Sample Response

Related Resources