Copy an object

Edit online

A PUT given a path to a new object creates a new copy of another object specified by the x-amz-copy-source header. Unless otherwise altered the metadata remains the same, although any ACL is reset to private for the account creating the copy. This operation does not make use of operation specific query parameters (besides versioning) or payload elements.

Syntax


PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style

Optional headers

Header Type Description
x-amz-metadata-directive string (COPY or REPLACE) REPLACE will overwrite original metadata with new metadata that is provided.
x-amz-tagging-directive string (COPY or REPLACE) REPLACE will overwrite original tagging with new tagging that is provided.
x-amz-copy-source-if-match string (ETag) Creates a copy if the specified ETag matches the source object.
x-amz-copy-source-if-none-match string (ETag) Creates a copy if the specified ETag is different from the source object.
x-amz-copy-source-if-unmodified-since string (timestamp) Creates a copy if the source object has not been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).
x-amz-copy-source-if-modified-since string (timestamp) Creates a copy if the source object has been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).
x-amz-checksum-algorithm string - one of CRC32, CRC32C, CRC64NVME, SHA1, or SHA256 Indicates which checksum algorithm will be used to create the checksum for the destination object.

Specific headers for SSE-C

Common SSE-C headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C) enabled.

The specific SSE-C headers used to initially upload objects are required if the copy operation will encrypt the copy of the data at the target destination. If the original/source object was encrypted using SSE-C, the specific headers used for copying objects will need to be present to decrypt the object source. Copies of objects do not need to be encrypted with the same key.

Attention: SSE-C headers can be used to write or write objects from a protected bucket. However, it should be noted that SSE-C keys cannot be rotated for objects in a protected bucket.

Other headers

Copy an object with tagging by adding the x-amz-tagging header to an object copy request. For more information, see: Other headers.

Note: Release 3.19.5 and later: Prevents the overwrite of an existing object with a forbid overwrite precondition. For more information, see: Forbid Overwrite Header .

Object Lock headers

Copy an object to an Object Lock enabled bucket and configure Object Lock on the object with the following headers.

Note: Non-bucket owners uploading objects to an Object Lock enabled bucket will have default retention of the bucket applied , if configured on the bucket. Otherwise no retention will be applied to the object.
Table 1. Object Lock headers
Name Description Required
x-amz-object-lock-mode

The object lock mode to be applied to the uploaded object.

Type
String
Valid Values
COMPLIANCE, GOVERNANCE
Default
None
Note: Objects uploaded to an Object Lock enabled bucket with a default configuration rule OR uploaded with Object Lock specific headers require a Content-MD5 header (or use of V4 signature with content signing) or with a x-am-checksum- header included as a confirmation of request payload integrity.
 Required if RetainUntilDate header is used; otherwise, no.
x-amz-object-lock-retain-until-date

The date and time when the uploaded object’s Object Lock is to expire.

Type
String
Valid Values
ISO8601 Date and Time
Default
None
Note: Objects uploaded to an Object Lock enabled bucket with a default configuration rule OR uploaded with Object Lock specific headers require a Content-MD5 header (or use of V4 signature with content signing) or with a x-am-checksum- header included as a confirmation of request payload integrity.
 Required if Mode header is used; otherwise, no.
x-amz-object-lock-legal-hold

The Legal Hold state to be applied to the object.

Type
String
Valid Values
ON | OFF
Default
None
Note: Objects uploaded to an Object Lock enabled bucket with a default configuration rule OR uploaded with Object Lock specific headers require a Content-MD5 header (or use of V4 signature with content signing) or with a x-am-checksum- header included as a confirmation of request payload integrity.
 No

Sample request

This basic example takes the bee object from the garden bucket, and creates a copy in the example bucket with the new key wild-bee.


PUT /example-bucket/wild-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161130T195251Z
x-amz-copy-source: /garden/bee
x-amz-tagging: tag1=value1&tag2=value2
Host: 67.228.254.193

Sample response


HTTP/1.1 200 OK
Date: Wed, 30 Nov 2016 19:52:52 GMT
X-Clv-Request-Id: 72992a90-8f86-433f-b1a4-7b1b33714bed
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: 72992a90-8f86-433f-b1a4-7b1b33714bed
ETag: "853aab195ce770b0dfb294a4e9467e62"
Content-Type: application/xml
Content-Length: 240
<CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LastModified>2016-11-30T19:52:53.125Z</LastModified>
  <ETag>"853aab195ce770b0dfb294a4e9467e62"</ETag>
</CopyObjectResult>

Sample Object Lock Copy object request 


PUT /example-bucket/wild-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161130T195251Z
x-amz-copy-source: /garden/bee
x-amz-tagging: tag1=value1&tag2=value2
x-amz-object-lock-mode:COMPLIANCE 
x-amz-object-lock-retain-until-date : <ISO8601 date and time> 
x-amz-object-lock-legal-hold: ON 
Content-MD5: <MD5 of Contents>
Host: 67.228.254.193