Copying an Object_Object Storage Service

Functions

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

Users can determine whether to copy the metadata of the source object to the target object (by default) or replace the metadata of the target object with the metadata contained in the request. The ACL of the source object is not copied to the target object. By default, the ACL of the target object is private. You can set an ACL for the target object by sending an API request.

The request for copying an object needs to carry the information about the bucket and object to be copied in the header field. The message body cannot be carried.

This operation supports server-side encryption.

An object copy can be up to 5 GB in size. If the source object size exceeds 5 GB, you can only copy part of the object.

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 copy succeeds. If the body contains ETag, the copy succeeds. Otherwise, the copy failed.

Versioning

By default, x-obs-copy-source specifies the latest version of the source object. If the latest version of the source object is a delete marker, the object is considered deleted. You can add versionId to request header x-obs-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-obs-version-id. If versioning is suspended for the bucket, the object version ID is null.

When the bucket versioning status is disabled, if you make a copy of object_A and save it as object_B, and an object named as object_B already exists, the new object_B will overwrite the existing one. After the copying is executed successfully, only new object_B can be downloaded because old object_B has been deleted. Therefore, before copying an object, ensure that there is no object with the same name as the object copy to prevent data from being deleted mistakenly. During the copying, object_A has no changes.

WORM

If a bucket has WORM enabled, you can configure retention policies for objects in the bucket. You can specify the x-obs-object-lock-mode and x-obs-object-lock-retain-until-date headers to configure a retention policy when you copy an object. If you do not specify these two headers but have configured a default bucket-level WORM policy, this default policy automatically applies to the object newly copied. You can also configure or update a WORM retention policy after an object is copied to the bucket.

In a copy operation, the object protection status is not copied, so the protection status of an object copy is independent of that of the source object. After the copy is complete, WORM retention changes made on the source object does not affect the object copy.

Archive or Deep Archive Objects

If source objects are in the Archive or Deep Archive storage class, ensure that these objects have been restored before you copy them. If a source object is not restored or is being restored, its copy will fail and error 403 Forbidden will be 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.region.myhuaweicloud.com 
x-obs-copy-source: /sourceBucket/sourceObject 
x-obs-metadata-directive: metadata_directive
x-obs-copy-source-if-match: etag
x-obs-copy-source-if-none-match: etag
x-obs-copy-source-if-unmodified-since: time_stamp
x-obs-copy-source-if-modified-since: time_stamp
Authorization: signature
Date: date

Request Parameters

This request contains no parameters.

Request Headers

You can add optional headers to specify the object to be copied. Table 3 describes the optional headers.

**Table 1** Request headers
Header	Type	Mandatory (Yes/No)	Description
x-obs-acl	String	No	Explanation: When copying an object, you can use this parameter to set a pre-defined ACL. Example: x-obs-acl: acl Restrictions: Use character strings. Value range: private public-read public-read-write For details about each policy, see the "Configuring an ACL Using Header Fields" section in ACLs. Default value: private
x-obs-grant-read	String	No	Explanation: When copying an object, you can use this header to grant all users in a domain the permissions to read the object and obtain the object metadata. Restrictions: None Value range: None Default value: None
x-obs-grant-read-acp	String	No	Explanation: When copying an object, you can use this header to grant all users in a domain the permissions to obtain the object ACL. Restrictions: None Value range: None Default value: None
x-obs-grant-write-acp	String	No	Explanation: When copying an object, you can use this header to grant all users in a domain the permissions to write the object ACL. Restrictions: None Value range: None Default value: None
x-obs-grant-full-control	String	No	Explanation: When copying an object, you can use this header to grant the following permissions to all users in a domain: Permissions to read objects, obtain object metadata, obtain object ACLs, and write object ACLs. Restrictions: None Value range: None Default value: None
x-obs-copy-source	String	Yes	Explanation: Indicates names of the source bucket and the source object. If the source object has multiple versions, the versionId parameter can be used to specify the desired version. Example: x-obs-copy-source: /source_bucket/sourceObject Restrictions: Full-width characters and percent signs (%) must be URL-encoded. Value range: None Default value: None
x-obs-metadata-directive	String	No	Explanation: Indicates whether the metadata of the target object is copied from the source object or replaced with the metadata contained in the request. Example: x-obs-metadata-directive: metadata_directive Restrictions: Values other than COPY or REPLACE result in an immediate 400-based error response. If you need to modify the metadata (the same for both the source and target objects), this parameter must be set to REPLACE. Otherwise, the request is invalid and the server returns a 400 HTTP status code error. This parameter cannot change an encrypted object to a non-encrypted one (for both the source and target objects). If you use this parameter to change the encryption of an object, OBS returns a 400 error. Value range: COPY REPLACE Default value: COPY
x-obs-copy-source-if-match	String	No	Explanation: Indicates that the source object is copied only if its ETag matches the one specified in this header. Otherwise, a 412 status code (failed precondition) is returned. Example: x-obs-copy-source-if-match: etag Restrictions: This parameter can be used with x-obs-copy-source-if-unmodified-since but cannot with other conditional copy headers. Value range: None Default value: None
x-obs-copy-source-if-none-match	String	No	Explanation: Indicates that the source object is copied only if its ETag does not match the one specified in this header. Otherwise, a 412 status code (failed precondition) is returned. Example: x-obs-copy-source-if-none-match: etag Restrictions: This parameter can be used with x-obs-copy-source-if-modified-since but cannot with other conditional copy headers. Value range: None Default value: None
x-obs-copy-source-if-unmodified-since	String	No	Explanation: The source object is copied only if the source object has not been modified since the time specified by this parameter. Otherwise, a 412 status code (precondition failed) is returned. Restrictions: The time specified by this parameter cannot be later than the current server time (GMT time), or this parameter does not take effect. This parameter can be used with x-obs-copy-source-if-match but cannot with other conditional copy parameters. Format: HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt, which can be any of the following: EEE, dd MMM yyyy HH:mm:ss z EEEE, dd-MMM-yy HH:mm:ss z EEE MMM dd HH:mm:ss yyyy Examples: x-obs-copy-source-if-unmodified-since: Sun, 06 Nov 1994 08:49:37 GMT x-obs-copy-source-if-unmodified-since: Sunday, 06-Nov-94 08:49:37 GMT x-obs-copy-source-if-unmodified-since: Sun Nov 6 08:49:37 1994 Value range: None Default value: None
x-obs-copy-source-if-modified-since	String	No	Explanation: The source object is copied only if the source object has been modified since the time specified by this parameter. Otherwise, a 412 status code (precondition failed) is returned. Restrictions: The time specified by this parameter cannot be later than the current server time (GMT time), or this parameter does not take effect. This parameter can be used with x-obs-copy-source-if-none-match but cannot with other conditional copy parameters. Format: HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt, which can be any of the following: EEE, dd MMM yyyy HH:mm:ss z EEEE, dd-MMM-yy HH:mm:ss z EEE MMM dd HH:mm:ss yyyy Examples: x-obs-copy-source-if-unmodified-since: Sun, 06 Nov 1994 08:49:37 GMT x-obs-copy-source-if-unmodified-since: Sunday, 06-Nov-94 08:49:37 GMT x-obs-copy-source-if-unmodified-since: Sun Nov 6 08:49:37 1994 Value range: None Default value: None
x-obs-storage-class	String	No	Explanation: When copying an object, you can use this header to specify the storage class for the object. If you do not use this header, the object storage class is the default storage class of the destination bucket where the object is copied to. Example: x-obs-storage-class: STANDARD Restrictions: The value is case-sensitive. Value range: STANDARD WARM COLD DEEP_ARCHIVE Default value: By default, the storage class of the bucket is inherited.
x-obs-persistent-headers	String	No	Explanation: When copying an object, you can add the x-obs-persistent-headers header in an HTTP request to specify one or more user-defined response headers. User-defined response headers will be returned in the response header when you retrieve the target object or query the metadata of the target object. Restrictions: Response headers customized in this way cannot be prefixed with x-obs-. For example, you should use key1 instead of x-obs-key1. Standard HTTP headers, such as host, content-md5, origin, range, and Content-Disposition, cannot be specified as user-defined headers. The total length of this header and the custom metadata cannot exceed 8 KB. If multiple values are passed for the same key, they are separated by commas (,) and returned all at once for that key. If the source object already has a user-defined response header, this header will not be copied to the target object. If the decoded value contains non-US-ASCII or unrecognizable characters, the server processes the value as a string and encapsulates it using ?UTF-8?B?<(str)>?=, but does not decode the value. For instance, value key1:abbc will be returned as key1: =?UTF-8?B?abbc?= in the response. The values cannot contain spaces, equal signs (=), commas (,), semicolons (;), colons (:), or periods (.). If such characters are required, use URL or Base64 encoding. Format: x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2)... Note: Items, such as key1 and key2, are user-defined headers. If they contain non-ASCII or unrecognizable characters, they can be encoded using URL or Base64. The server processes these headers as character strings, but does not decode them. Items, such as value1 and value2 are the values of the corresponding headers. base64_encode indicates that the value is encoded using Base64. A user-defined header and its Base64-encoded value are connected using a colon (:) to form a key-value pair. All key-value pairs are separated with a comma (,) and are placed in the x-obs-persistent-headers header. The server then decodes the uploaded value. Example: x-obs-persistent-headers: key1:dmFsdWUx,key2:dmFsdWUy The returned header for downloading the target object or obtaining the metadata of the target object is key1:value1 or key2:value2 respectively. Value range: None Default value: None
x-obs-website-redirect-location	String	No	Explanation: If a bucket is configured with the static website hosting function, it will redirect 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. Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2K. Value range: None Default value: None
x-obs-server-side-encryption	String	No. This header is required when SSE-KMS is used.	Explanation: Indicates that SSE-KMS is used for server-side encryption. Objects are encrypted using SSE-KMS. Example: x-obs-server-side-encryption: kms Restrictions: None Value range: kms AES256 Default value: None
x-obs-server-side-encryption-kms-key-id	String	No	Explanation: ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key. Restrictions: This header can only be used when you specify kms for the x-obs-server-side-encryption header. Default value: If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.
x-obs-server-side-encryption-customer-algorithm	String	No. This header is required when SSE-C is used.	Explanation: The algorithm used to encrypt a target object. Example: x-obs-server-side-encryption-customer-algorithm: AES256 Restrictions: This header is used only when SSE-C is used. This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5. Value range: AES256 Default value: None
x-obs-server-side-encryption-customer-key	String	No. This header is required when SSE-C is used.	Explanation: The key used to encrypt a target object. Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= Restrictions: This header is used only when SSE-C is used. This header is a Base64-encoded 256-bit key and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key-MD5. Value range: None Default value: None
x-obs-server-side-encryption-customer-key-MD5	String	No. This header is required when SSE-C is used.	Explanation: The MD5 value of the key used to encrypt a target object. The MD5 value is used to check whether any error occurs during the transmission of the key. Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restrictions: This header is used only when SSE-C is used. This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key. Value range: MD5 value of the key. Default value: None
x-obs-copy-source-server-side-encryption-customer-algorithm	String	No. This header is required when SSE-C is used to copy a source object.	Explanation: Indicates the algorithm used to decrypt a source object. Example: x-obs-copy-source-server-side-encryption-customer-algorithm: AES256 Restrictions: This header is used only when SSE-C is used. This header must be used together with x-obs-copy-source-server-side-encryption-customer-key and x-obs-copy-source-server-side-encryption-customer-key-MD5. Value range: AES256 Default value: None
x-obs-copy-source-server-side-encryption-customer-key	String	No. This header is required when SSE-C is used to copy a source object.	Explanation: Indicates the key used to decrypt a source object. Example: x-obs-copy-source-server-side-encryption-customer-key: K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= Restrictions: This header is used only when SSE-C is used. This header is a Base64-encoded 256-bit key and must be used together with x-obs-copy-source-server-side-encryption-customer-algorithm and x-obs-copy-source-server-side-encryption-customer-key-MD5. Value range: None Default value: None
x-obs-copy-source-server-side-encryption-customer-key-MD5	String	No. This header is required when SSE-C is used to copy a source object.	Explanation: Indicates the MD5 value of the key used to decrypt a source object. The MD5 value is used to check whether any error occurs during the transmission of the key. Example: x-obs-copy-source-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restrictions: This header is used only when SSE-C is used. This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-copy-source-server-side-encryption-customer-algorithm and x-obs-copy-source-server-side-encryption-customer-key. Value range: MD5 value of the key. Default value: None
success-action-redirect	String	No	Explanation: The redirection address used when requests were successfully responded to. If the value is valid and the request is successful, OBS returns status code 303. Location contains success_action_redirect as well as the bucket name, object name, and object ETag. If this parameter value is invalid, OBS ignores this parameter. In such case, the Location header is the object address, and OBS returns the response code based on whether the operation succeeds or fails. Restrictions: The value must be a valid URL, for example, http://domainname or https://domainname. Value range: URL Default value: None
x-obs-object-lock-mode	String	No, but required when x-obs-object-lock-retain-until-date is present	Explanation: WORM mode applied to the object. Example: x-obs-object-lock-mode:COMPLIANCE Restrictions: This parameter must be used together with x-obs-object-lock-retain-until-date. Value range: COMPLIANCE Default value: None
x-obs-object-lock-retain-until-date	String	No, but required when x-obs-object-lock-mode is present.	Explanation: When the WORM policy of the object expires. Example: x-obs-object-lock-retain-until-date:2015-07-01T04:11:15Z Restrictions: The value must be a UTC time that complies with the ISO 8601 standard. Example: 2015-07-01T04:11:15Z This parameter must be used together with x-obs-object-lock-mode. Value range: The time must be later than the current time. Default value: None

For details about other headers, see Table 3.

Request Elements

This request contains no elements.

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.region.myhuaweicloud.com/doc/2015-06-30/">
    <LastModified>modifiedDate</LastModified> 
    <ETag>etagValue</ETag> 
</CopyObjectResult>

Response Headers

The response to the request uses common headers. For details, see Table 1.

In addition to the common response headers, the headers listed in Table 2 may be used.

**Table 2** Additional response headers
Header	Type	Description
x-obs-copy-source-version-id	String	Explanation: Version ID of the source object Restrictions: None Value range: None Default value: None
x-obs-version-id	String	Explanation: Version ID of the target object Restrictions: None Value range: None Default value: None
x-obs-server-side-encryption	String	Explanation: The encryption method used by the server. Example: x-obs-server-side-encryption: kms Restrictions: This header is included in a response if SSE-KMS is used. Value range: kms AES256 Default value: None
x-obs-server-side-encryption-kms-key-id	String	Explanation: ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key. Restrictions: This header can only be used when you specify kms for the x-obs-server-side-encryption header. Default value: If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.
x-obs-server-side-encryption-customer-algorithm	String	Explanation: The algorithm used for encryption. Example: x-obs-server-side-encryption-customer-algorithm: AES256 Restrictions: This header is included in a response if SSE-C is used for server-side encryption. Value range: AES256 Default value: None
x-obs-server-side-encryption-customer-key-MD5	String	Explanation: The MD5 value of the key used for encryption. Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restrictions: This header is included in a response if SSE-C is used for server-side encryption. Value range: Base64-encoded MD5 value of the key ID. Default value: None
x-obs-storage-class	String	Explanation: Storage class of an object. Restrictions: This header is returned when the storage class of an object is not Standard. Value range: WARM COLD DEEP_ARCHIVE Default value: Storage class of an object.

Response Elements

This response contains elements of a copy result. Table 3 describes the elements.

**Table 3** Response elements
Element	Type	Description
CopyObjectResult	XML	Explanation: The copy results Restrictions: None Value range: None Default value: None
LastModified	String	Explanation: Time (UTC) when an object was last modified Restrictions: The date is in the ISO8601 format. Example: 2018-01-01T00:00:00.000Z Value range: None Default value: None
ETag	String	Explanation: 128-bit MD5 digest of the Base64 code of a new object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object. Value range: The value must contain 32 characters. Default value: None

Error Responses

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

Sample Request: Copying an Object

Copy the object srcobject in bucket bucket to the destobject object in bucket examplebucket.

    
         PUT /destobject HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 04:19:21 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:2rZR+iaH8xUewvUKuicLhLHpNoU=
x-obs-copy-source: /bucket/srcobject

Sample Response: Copying an Object

    
         HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 001B21A61C6C00000134031BE8005293
x-obs-id-2: MDAxQjIxQTYxQzZDMDAwMDAxMzQwMzFCRTgwMDUyOTNBQUFBQUFBQWJiYmJiYmJi
Date: WED, 01 Jul 2015 04:19:21 GMT
Content-Length: 249

<?xml version="1.0" encoding="utf-8"?>
<CopyObjectResult xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
  <LastModified>2015-07-01T00:48:07.706Z</LastModified>  
  <ETag>"507e3fff69b69bf57d303e807448560b"</ETag> 
</CopyObjectResult>

Sample Request: Copying an Object Version

Copy a multi-version object and copy the object srcobject whose version number is AAABQ4uBLdLc0vycq3gAAAAEVURTRkha in bucket bucket to the destobject object in bucket examplebucket.

    
         PUT /destobject HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 04:20:29 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:4BLYv+1UxfRSHBMvrhVLDszxvcY=
x-obs-copy-source: /bucket/srcobject?versionId=AAABQ4uBLdLc0vycq3gAAAAEVURTRkha

Sample Response: Copying an Object Version

    
         HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: DCD2FC9CAB78000001438B8A9C898B79
x-obs-id-2: DB/qBZmbN6AIoX9mrrSNYdLxwvbO0tLR/l6/XKTT4NmZspzharwp5Z74ybAYVOgr
Content-Type: application/xml
x-obs-version-id: AAABQ4uKnOrc0vycq3gAAAAFVURTRkha
x-obs-copy-source-version-id: AAABQ4uBLdLc0vycq3gAAAAEVURTRkha
Date: WED, 01 Jul 2015 04:20:29 GMT
Transfer-Encoding: chunked

<?xml version="1.0" encoding="utf-8"?>
<CopyObjectResult xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
  <LastModified>2015-07-01T01:48:07.706Z</LastModified>  
  <ETag>"507e3fff69b69bf57d303e807448560b"</ETag> 
</CopyObjectResult>

Copying an Object