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.
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.
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 COPY object response body.
Copying an object to itself
If the target object you specify in a copy request identifies an existing object and versioning is enabled, HCP creates a new version of the existing object.
If the target object you specify in a copy request identifies an existing object and versioning is disabled:
•If the value of the x-amz-metadata-directive header is REPLACE, HCP replaces all custom metadata for the existing object with the custom metadata specified in the copy request. If the request doesn’t specify any custom metadata, HCP removes all custom metadata from the existing object.
When you replace or remove the custom metadata for an object in this way, the version ID of the object does not change.
•If the value of the x-amz-metadata-directive header is COPY or if the request does not include the x-amz-metadata-directive header, HCP returns a 400 (Bad Request) status code and does not replace the custom metadata for the object.
In no case does HCP replace the content of an existing object.
Conditionally copying an object
You can use the x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-modified-since, and x-amz-copy-source-if-unmodified-since request headers to make copy requests conditional:
•The x-amz-copy-source-if-match and x-amz-copy-source-if-none-match headers compare the ETag of the source object or object version to one or more values that you specify. Typically, each value is the ETag for an object or object version of interest.
•The x-amz-copy-source-if-modified-since and x-amz-copy-source-if-unmodified-since headers compare the date and time the source object or object version was last modified to a date and time that you specify.
If the source object or object version:
•Meets all the conditions specified by the conditional headers included in the request, HCP performs the copy operation
•Does not meet all the conditions specified by the conditional headers included in the request, HCP returns a 412 (Precondition Failed) status code
If a request includes multiple different conditional headers, HCP processes any x-amz-copy-source-if-match and x-amz-copy-source-if-none-match headers before any x-amz-copy-source-if-modified-since or x-amz-copy-source-if-unmodified-since headers. If a request includes more than one of any given header, HCP processes only the first one of those headers and ignores the others.
© 2016 Hitachi Data Systems Corporation. All rights reserved.