< Previous | Contents | Next >

Copying an object

You use the HTTP PUT method with the x-amz-copy-source header to copy an object from one location to another. The source and target locations can be two different buckets within the same tenant, or they can be the same bucket. The source object is the object you’re copying. The target object is the object that results from the copy operation.

To copy an object, you need read permission for the bucket containing the source object or for the source object itself and write permission for the target bucket.

When copying an object, you can specify a name for the target object that’s different from the name of the source object.

By default, a copy operation copies the current version of the source object specified in the request. However, while versioning is enabled for the source bucket, you can use the versionId query parameter with the source object specification to copy a specific version of the object. If the version identified by the versionId parameter does not exist or is a deleted version, HCP returns a 404 (Not Found) status code.

HCP does not copy version IDs with objects. The object created by a copy operation has its own version ID.

By default, HCP copies any custom metadata for the source object to the target object. However, in the copy request, you can specify replacement custom metadata to be used for the target object. To apply this custom metadata to the target object, you need to include the

x-amz-metadata-directive header with a value of REPLACE in the copy request.

HCP does not copy ACLs with objects. However, in the copy request, you can specify an ACL for the target object. To do this, you need to use ACL headers. You cannot use an ACL request body when copying an object. For information on ACLs, see “Access control lists” on page 25.

158 Chapter 6: Working with objects

Copying an object

If the ACL you specify in a request to copy an object is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not copy the object.

If you’re an authenticated user, when you copy an object, you become the owner of the target object. If you’re accessing the bucket anonymously, the target object has no owner. For information on object ownership, see “Object owners” on page 24.

In response to a request to copy an object, HCP returns an XML response body containing the ETag and last modification date of the target object. For the format of this response body, see “Response body” on page 167.


Copying an object to itselfConditionally copying an objectRequest headersResponse headersResponse bodyHTTP status codesExamplesExample 1: Conditionally copying an object from one bucket to anotherExample 2: Recovering an old version of an objectExample 3: Replacing custom metadata for an existing object