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 is a delete marker, HCP returns a 503 (Service Unavailable) status code. If the current version of the source object is a delete marker and you don't specify a version ID, HCP returns a 404 (Not Found) status code. Fo r information on delete markers, see Deleting an object or folder.

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 about 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 about 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 Response body (PUT object copy).

Note: Depending on the replication configuration, copy operations may be slow and, for large objects, may time out.

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 and does not copy the object

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.

Note: The x-amz-copy-source-if-modified-since and x-amz-copy-source-if-unmodified-since request headers are not compatible with s3curl.

Object encryption

When you copy an object, you can use the x-amz-server-side-encryption request header to determine whether objects stored in HCP are encrypted. If stored objects are encrypted, the response headers include x-amz-server-side-encryption with a value representing the encryption algorithm and key length HCP is using. If stored objects are not encrypted, the value of the x-amz-server-side-encryption response header is None.

Client timeouts

Copying a large object can take some time. If a client times out because a copy operation is taking too long, HCP continues the operation in the background.

Because the connection to the client is broken, HCP cannot report the completion of the copy operation to the client. Until the operation is complete, HCP returns a 404 Not Found status code in response to HEAD requests for the object being created by the copy operation.

After a copy operation finishes successfully, HCP returns information about the new object in response to HEAD requests for the object. If the operation does not succeed, HCP continues to return a 404 Not Found status code in response to HEAD requests for the object.

If copy operations are causing a client to time out, consider increasing the client timeout interval.

© 2015, 2020 Hitachi Vantara LLC. All rights reserved.