# Copying Objects

#### 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.

The target object size range is [0, 5 GB]. If the source object size exceeds 5 GB, you can only copy some objects using the Range API.

#### Versioning

By default, x-obs-copy-source specifies the latest version of the source object. If the latest version of the source object has a deletion marker, the object is considered to have been 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.

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.

#### OBS Cold Objects

If source objects are OBS Cold objects, check the restore status of the objects. You can copy these objects only after they are restored. If the source object is not retrieved or is being retrieved, the copying 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

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10

    PUT /destinationObjectName HTTP/1.1
    Host: bucketname.obs.region.example.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 parameter.

#### 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 | Description | Mandatory
--- | --- | ---
x-obs-acl | This header can be added to set access control policies for objects when copying the objects. The access control policies are the predefined common policies, including private, public-read, public-read-write. Type: string Example: x-obs-acl: acl | No
x-obs-grant-read | When creating an object, you can use this header to authorize all users in an account the permission to read objects and obtain object metadata. Type: string | No
x-obs-grant-read-acp | When creating an object, you can use this header to authorize all users in an account the permission to obtain the object ACL. Type: string | No
x-obs-grant-write-acp | When creating an object, you can use this header to authorize all users in an account the permission to write the object ACL. Type: string | No
x-obs-grant-full-control | When creating an object, you can use this header to authorize all users in an account the permission to read the object, obtain the object metadata, obtain the object ACL, and write the object ACL. Type: string | No
x-obs-copy-source | 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. Type: string Constraint: URL encoding is required for handling Chinese characters. Example: x-obs-copy-source: /source_bucket/sourceObject | Yes

x-obs-metadata- directive

Indicates whether the metadata of the target object is copied from the source object or replaced with the metadata contained in the request.

Type: string

Valid values: COPY and REPLACE

Default value: COPY

Example: x-obs-metadata-directive: metadata_directive

Constraints: 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 be used to change an encrypted object to a non-encrypted object (the same for both the source and target objects). If you use this parameter to change the encrypted object, the system returns 400.

No

x-obs-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-obs-copy-source-if-match: etag Constraint: This parameter can be used with x-obs-copy-source-if-unmodified-since but not other conditional copy parameters. | No
x-obs-copy-source-if-none-match | Copies the object only if its ETag does not match the one specified in this header. Otherwise, a 412 HTTP status code error (failed precondition) is returned. Type: string Example: x-obs-copy-source-if-none-match: etag Constraint: This parameter can be used with x-obs-copy-source-if-modified-since but not other conditional copy parameters. | No

x-obs-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. This header can be used with x-obs-copy-source-if-match, but cannot be used with other conditional copy headers.

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

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

No

x-obs-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. This header can be used with x-obs-copy-source-if-none-match, but cannot be used with other conditional copy headers

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

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

No

x-obs-storage-class

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.

Type: string

Note: There are three storage classes: STANDARD (Standard storage class), WARM (Warm storage class), and COLD (Cold storage class). Therefore, this parameter value can be STANDARD, WARM, or COLD. These values are case sensitive.

Example: x-obs-storage-class: STANDARD

No

x-obs-website-redirect-location

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.

Type: string

Default value: none

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

No

x-obs-server-side-encryption | Indicates that SSE-KMS is used. Objects are encrypted using SSE-KMS. Type: string Example: x-obs-server-side-encryption: kms | No. This header is required when SSE-KMS is used.

x-obs-server-side-encryption-kms-key-id

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

Type: string

The following two formats are supported:

1. regionID:domainID:key/key_id

2. key_id

regionID is the ID of the region to which the key belongs. domainID is the account ID of the tenant to which the key belongs. key_id is the key ID created in KMS.

Example:

1. x-obs-server-side-encryption-kms-key-id: region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

2. x-obs-server-side-encryption-kms-key-id: 4f1cd4de-ab64-4807-920a-47fc42e7f0d0

No

x-obs-server-side-encryption-customer-algorithm | Encryption algorithm. The header is used in SSE-C mode. Type: string Example: x-obs-server-side-encryption-customer-algorithm: AES256 Constraint: This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5. | No. This header is required when SSE-C is used.

x-obs-server-side-encryption-customer-key

Indicates the key used to encrypt an object. The header is used in SSE-C mode.

Type: string

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

Constraint: 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.

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

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

Indicates the MD5 value of a key used to encrypt a destination 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-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraint: 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.

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

x-obs-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-obs-copy-source-server-side-encryption-customer-algorithm: AES256

Constraint: 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.

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

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

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

Type: string

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

Constraint: 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.

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

x-obs-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-obs-copy-source-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraint: 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.

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

success_action_redirect

Indicates the address (URL) to which a successfully responded request is redirected.

- 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 is invalid, OBS ignores this parameter. The response code is 204, and the Location is the object address.

Type: string

No

For details about other headers, see Table 3.

#### Request Elements

This request contains no elements.

#### Response Syntax

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10

    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.example.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 following message headers may also be used. For details, see Table 2.

Table 2 Additional response header parameters
Header | Description
--- | ---
x-obs-copy-source-version-id | Version ID of the source object Type: string
x-obs-version-id | Version ID of the target object Type: string
x-obs-server-side-encryption | This header is included in a response if SSE-KMS is used. Type: string Example: x-obs-server-side-encryption: kms

x-obs-server-side-encryption-kms-key-id

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

Type: string

Format: regionID:domainID:key/key_id

regionID is the ID of the region to which the key belongs. domainID is the account ID of the tenant to which the key belongs. key_id is the key ID used in this encryption.

Example: x-obs-server-side-encryption-kms-key-id: region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-obs-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-obs-server-side-encryption-customer-algorithm: AES256
x-obs-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-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==
x-obs-storage-class | This header is returned when the storage class of an object is not Standard. The value can be WARM or COLD. Type: string

#### Response Elements

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

Table 3 Response elements
Element | Description
--- | ---
CopyObjectResult | Container for the copy result Type: XML
LastModified | Latest time when the object was modified Type: string
ETag | 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 identify whether the object content is changed. For example, if ETag value is A when an object is uploaded and the ETag value has changed to B when the object is downloaded, it indicates that the object content is changed. Type: string

#### Error Responses

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

#### Sample Request 1

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

    1
    2
    3
    4
    5
    6
    7

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

#### Sample Response 1

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12

    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.example.com/doc/2015-06-30/">
      <LastModified>2015-07-01T00:48:07.706Z</LastModified>
      <ETag>"507e3fff69b69bf57d303e807448560b"</ETag>
    </CopyObjectResult>

#### Sample Request 2

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.

    1
    2
    3
    4
    5
    6
    7

    PUT /destobject HTTP/1.1
    User-Agent: curl/7.29.0
    Host: examplebucket.obs.region.example.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 2

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15

    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.example.com/doc/2015-06-30/">
      <LastModified>2015-07-01T01:48:07.706Z</LastModified>
      <ETag>"507e3fff69b69bf57d303e807448560b"</ETag>
    </CopyObjectResult>

Parent topic: Operations on Objects