PUT Object - Copy

You can perform this operation to create a copy of an existing object in OBS.

By default, a PUT Object - Copy operation copies object metadata together with the object. If you want to update the metadata, provide new metadata in the PUT Object - Copy request. The object ACL is not copied together with the object and the ACL of a copy object is set to private by default. You can send a PUT Object acl request to modify the object ACL.

The PUT Object - Copy request must contain authentication information and cannot contain a request body.

This operation supports server-side encryption.

Versioning

By default, x-amz-copy-source specifies the latest version of the source object. If the latest version of the source object is a deletion marker, the object is considered to have been deleted. You can add versionId to request header x-amz-copy-source to copy an object with the specified version ID.

If a bucket has versioning enabled, the system automatically generates a unique version ID for the requested object in this bucket and returns the version ID in response header x-amz-version-id. If a bucket has versioning suspended, the version ID of the requested object in this bucket is null.

NOTICE:

If versioning is not enabled for a bucket, you can replace source object objecta with target object objectb by replication. If objectb already exists before you perform replication, the new objectb will overwrite the old objectb after you perform replication.

After replication is performed successfully, only the new objectb can be downloaded. The old objectb will be deleted. Before using the copy interface, ensure that the target object does not exist or is useless to avoid incorrect data deletion. During the replication, the source object objecta is not changed.

You cannot determine whether a request is executed successfully only using status_code in the header returned by HTTP. If 200 in status_code is returned, the server has received the request and starts to process the request. The body in the response shows whether the replication operation succeeds. The replication operation succeeds only when the body has ETags. Otherwise, the replication operation fails.

OBS Archive Objects

If source objects are OBS Archive objects, check the restore status of the objects. You can copy the OBS Archive objects only after the objects are restored. If the objects are not restored or are being restored, the copy fails, and error "403 Forbidden" is returned. The fault is described as follows:

ErrorCode: InvalidObjectState

ErrorMessage: Operation is not valid for the source object's storage class

Request Syntax

PUT /destinationObjectName HTTP/1.1
Host: bucketname.obs.cn-north-1.myhwclouds.com
x-amz-copy-source: /sourceBucket/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
Authorization: signature
Date: date

Request Parameters

This request contains no parameter.

Request Headers

You can add optional headers to specify the object to be copied. Common Request Headers describes the optional headers.

Table 1 Additional request headers

Header

Description

Required or Optional

x-amz-acl

Indicates the ACL applied to the copied object. Possible values are private, public-read, public-read-write, authenticated-read, bucket-owner-read, and bucket-owner-full-control. For details, see Table 3.

Type: string

Example:

x-amz-acl: acl

Optional

x-amz-copy-source

Indicates the name of the source bucket and the key of the source object. If the source object has multiple version IDs, versionId is used to specify the required version ID.

Type: string

Example: x-amz-copy-source: /source_bucket/sourceObject

Required

x-amz-metadata- directive

Indicates whether the metadata is copied from the source object or replaced with the metadata provided in the request.

Type: string

Valid values: COPY or REPLACE

Default: COPY

Example: x-amz-metadata-directive: metadata_directive

Constraints:

  • If the value is neither COPY nor REPLACE, OBS returns status code 400.
  • If you want to copy an object to itself, set the value to REPLACE. Otherwise, OBS considers the request invalid and returns status code 400. This parameter cannot change an encrypted object to a non-encrypted one (source and target objects are the same). If a user uses this parameter to change an encrypted object to a non-encrypted one, the system returns status code 400.

Optional

x-amz-copy-source-if-match

Copies the source object only if its ETag matches the one specified by this header. Otherwise, a 412 HTTP status code error (failed precondition) is returned.

Type: string

Example: x-amz-copy-source-if-match: etag

Constraints: This header can be used with x-amz-copy-source-if-unmodified-since but cannot be used with other conditional copy headers.

Optional

x-amz-copy-source-if-none-match

Copies the object if its entity tag (ETag) matches the specified tag. Otherwise, the request returns a 412 HTTP status code error (failed precondition).

Type: string

Example:

x-amz-copy-source-if-none-match: etag

Constraints: This header can be used with x-amz-copy-source-if-modified-since but cannot be used with other conditional copy headers.

Optional

x-amz-copy-source-if-unmodified- since

Copies the source object only if it has not been modified since the time specified by this header. Otherwise, a 412 HTTP status code error (failed precondition) is returned.

Type: HTTP time string complying with the format specified in http://www.ietf.org/rfc/rfc2616.txt.

Example: x-amz-copy-source-if-unmodified-since: time-stamp

Constraints: This header can be used with x-amz-copy-source-if-match but cannot be used with other conditional copy headers.

Optional

x-amz-copy-source-if-modified-since

Copies the source object only if it has not been modified since the time specified by this header. Otherwise, a 412 HTTP status code error (failed precondition) is returned.

Type: HTTP time string complying with the format specified in http://www.ietf.org/rfc/rfc2616.txt.

Example: x-amz-copy-source-if-modified-since: time-stamp

Constraints: This header can be used with x-amz-copy-source-if-none-match but cannot be used with other conditional copy headers.

Optional

x-amz-website-redirect-location

If a bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. OBS stores the value of this header in the object metadata.

Type: string

Default: none

Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 KB.

Optional

x-amz-server-side-encryption

Indicates the SSE-KMS mode. The destination object uses SSE-KMS for encryption.

Type: string

Example: x-amz-server-side-encryption:aws:kms

Optional. This header is required when SSE-KMS is used.

x-amz-server-side-encryption-aws-kms-key-id

Indicates the master key ID. This header is used in SSE-KMS mode. If the customer does not provide the master key, the default master key will be used.

Type: string

Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

Optional

x-amz-server-side-encryption-customer-algorithm

Indicates an encryption algorithm. The header is used in SSE-C mode.

Type: string

Example: x-amz-server-side-encryption-customer-algorithm:AES256

Constraints: This header must be used together with x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5.

Optional. This parameter is required when SSE-C is used.

x-amz-server-side-encryption-customer-key

Indicates a key used to encrypt destination objects. The header is used in SSE-C mode.

Type: string

Example: x-amz-server-side-encryption-customer-key:K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw=

Constraints: This header is a base64-encoded 256-bit key and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5.

Optional. This header is required when SSE-C is used.

x-amz-server-side-encryption-customer-key-MD5

Indicates the MD5 value of a key used to encrypt objects. The header is used in SSE-C mode. The MD5 value is used to check whether any error occurs during the transmission of the key.

Type: string

Example: x-amz-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraints: This header is a base64-encoded 128-bit MD5 value and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key.

Optional. This header is required when SSE-C is used.

x-amz-copy-source-server-side-encryption-customer-algorithm

Indicates the algorithm used to decrypt a source object. The header is used in SSE-C mode.

Type: string

Example: x-amz-copy-source-server-side-encryption-customer-algorithm:AES256

Constraints: This header must be used together with x-amz-copy-source-server-side-encryption-customer-key and x-amz-copy-source-server-side-encryption-customer-key-MD5.

Optional. This header is required when SSE-C is used to copy a source object.

x-amz-copy-source-server-side-encryption-customer-key

Indicates the key used to decrypt a source object. The header is used in SSE-C mode.

Type: string

Example: x-amz-copy-source-server-side-encryption-customer-key:K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw=

Constraints: This header is a base64-encoded 256-bit key and must be used together with x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side-encryption-customer-key-MD5.

Optional. This header is required when SSE-C is used to copy a source object.

x-amz-copy-source-server-side-encryption-customer-key-MD5

Indicates the MD5 value of the key used to decrypt a source object. The header is used in SSE-C mode. The MD5 value is used to check whether any error occurs during the transmission of the key.

Type: string

Example: x-amz-copy-source-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraints: This header is a base64-encoded 128-bit MD5 value and must be used together with x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side-encryption-customer-key.

Optional. This header is required when SSE-C is used to copy a source object.

For details about other headers, see Common Request Headers.

Request Elements

This request contains no element.

Response Syntax

HTTP/1.1 status_code
Content-Type: application/xml
Date: date
Content-Length: length

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CopyObjectResult xmlns="http://obs.cn-north-1.myhwclouds.com/doc/2015-06-30/">
    <LastModified>modifiedDate</LastModified>
    <ETag>etagValue</ETag>
</CopyObjectResult>

Response Headers

This response uses common headers. For details, see Common Response Headers.

This response also uses optional headers, as described in Table 2.

Table 2 Additional response header

Header

Description

x-amz-copy-source-version-id

Indicates the version ID of the source object.

Type: string

x-amz-version-id

Indicates the version ID of the target object.

Type: string

x-amz-server-side-encryption

This header is included in a response if SSE-KMS is used.

Type: string

Example: x-amz-server-side-encryption:aws:kms

x-amz-server-side-encryption-aws-kms-key-id

Indicates the master key ID. This header is included in a response if SSE-KMS is used.

Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-amz-server-side-encryption-customer-algorithm

Indicates an encryption algorithm. This header is included in a response if SSE-C is used.

Type: string

Example: x-amz-server-side-encryption-customer-algorithm:AES256

x-amz-server-side-encryption-customer-key-MD5

Indicates the MD5 value of a key used to encrypt objects. This header is included in a response if SSE-C is used.

Type: string

Example: x-amz-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Response Elements

This response contains elements to indicate the copy results. Table 3 describes the elements.

Table 3 Response elements

Element

Description

CopyObjectResult

Indicates the container for copy results.

Type: XML

LastModified

Indicates the date when the object was last modified.

Type: string

ETag

Indicates the ETag of the new object.

Type: string

Error Responses

No special error responses are returned. For details about error responses, see Table 1.

Registration