All Products
Search
Document Center

Object Storage Service:CopyObject

Last Updated:Sep 21, 2023

Copies objects within a bucket or between buckets in the same region.

Versioning

By default, the x-oss-copy-source header in a CopyObject request specifies that the current version of the object is copied. You can add versionId to x-oss-copy-source to copy a specified version of the object. If the specified version of the object to copy is a delete marker, Object Storage Service (OSS) returns 404 Not Found, which indicates that the object does not exist.

To recover a previous version of an object to the current version, you can copy the previous version of the object to the bucket in which the object is stored. OSS then stores the previous version of the object as the current version.

If versioning is enabled for the destination bucket, OSS automatically generates a unique version ID for the destination object. The version ID is the value of x-oss-version-id in the response. If versioning is not enabled or suspended for the destination bucket, OSS generates a version whose ID is null for the destination object, and overwrites the existing version whose ID is null.

Limits

  • The following limits in object size apply when you call the CopyObject operation:

    • If the source bucket is also the destination bucket and storage class conversion is not involved in the CopyObject operation, the object to copy can be larger than 5 GB.

    • If the source bucket is also the destination bucket and storage class conversion is involved in the CopyObject operation, the object to copy cannot be larger than 5 GB. To copy an object that is larger than 5 GB, call the UploadPartCopy operation.

    • If you copy an object between buckets in the same region, we recommend that you call the CopyObject operation if the object is smaller than 1 GB. To copy an object that is larger than 1 GB in size, call the UploadPartCopy operation.

  • Read permissions are required.

    To call the CopyObject or UploadPartCopy operation, you must have read permissions on the object that you want to copy.

  • The following limits apply when you call the CopyObject operation to copy an object within an unversioned bucket:

    The source and destination objects are the same:

    • If the copy operation does not involve modifying the encryption method or storage class of the source object, OSS only modifies the metadata of the source object and does not copy the content of the object.

    • If the copy operation involves modifying the encryption method or storage class of the source object, OSS modifies the metadata of the source object and copies the content of the object.

  • The following limits apply when you call the CopyObject operation to copy an object within a versioned bucket:

    • Appendable objects cannot be copied by using CopyObject.

    • The server-side encryption method for an appendable object cannot be modified by using CopyObject.

  • The following limit applies when you call the CopyObject operation to copy a symbolic link:

    Only the symbolic link is copied. The object to which the symbolic link points is not copied.

  • The following limit applies when you call the CopyObject operation to copy objects in a bucket for which the hierarchical namespace feature is enabled:

    Directories in the bucket cannot be copied.

Billing

  • Each time you call the CopyObject operation, you are charged for a PUT request to the destination bucket.

  • The storage usage of the destination bucket increases when you call the CopyObject operation.

  • You are also charged if the CopyObject operation overwrites an object to modify the storage class of an object. For example, if you call the CopyObject operation to convert an Infrequent Access (IA) object to a Standard object by overwriting the IA object less than 10 days after the IA object is created, you are charged for the entire minimum storage duration of 30 days. For more information about storage fees, see Storage fees.

Request syntax

PUT /DestObjectName HTTP/1.1
Host: DestBucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
x-oss-copy-source: /SourceBucketName/SourceObjectName

Request headers

All headers in a CopyObject request start with x-oss-. These headers must be added to the signature string. The following table describes the headers.

Header

Type

Required

Example

Description

x-oss-forbid-overwrite

String

No

true

Specifies whether the CopyObject operation overwrites objects with the same name. The x-oss-forbid-overwrite request header does not take effect when versioning is enabled or suspended for the destination bucket. In this case, the CopyObject operation overwrites the existing object that has the same name as the destination object.

  • If the x-oss-forbid-overwrite header is not specified or is set to false, an existing object that has the same name as the object that you want to copy is overwritten.

  • If the x-oss-forbid-overwrite header is set to true, an existing object that has the same name as the object that you want to copy cannot be overwritten.

If you specify the x-oss-forbid-overwrite header, the queries per second (QPS) performance of OSS may be degraded. If you want to specify the x-oss-forbid-overwrite header in a large number of requests (QPS greater than 1,000), contact technical support.

Default value: false.

x-oss-copy-source

String

Yes

/oss-example/oss.jpg

The path of the source object.

By default, this header is left empty.

x-oss-copy-source-if-match

String

No

5B3C1A2E053D763E1B002CC607C5****

The object copy condition. If the ETag value of the source object is the same as the ETag value specified in the request, OSS copies the object and returns 200 OK.

By default, this header is left empty.

x-oss-copy-source-if-none-match

String

No

5B3C1A2E053D763E1B002CC607C5****

The object copy condition. If the ETag value of the source object is different from the ETag value specified in the request, OSS copies the object and returns 200 OK.

By default, this header is left empty.

x-oss-copy-source-if-unmodified-since

String

No

Mon, 11 May 2020 08:16:23 GMT

The object copy condition. If the time specified in the request is the same as or later than the modification time of the object, OSS copies the object and returns 200 OK.

By default, this header is left empty.

x-oss-copy-source-if-modified-since

String

No

Mon, 11 May 2020 08:16:23 GMT

The object copy condition. If the time specified in the request is earlier than the modification time of the object, OSS copies the object and returns 200 OK.

By default, this header is left empty.

x-oss-metadata-directive

String

No

COPY

The method that is used to configure the metadata of the destination object.

  • COPY (default): The metadata of the source object is copied to the destination object.

    The configurations of the x-oss-server-side-encryption header of the source object are not copied to the destination object. The x-oss-server-side-encryption header in the CopyObject request specifies the method used to encrypt the destination object.

  • REPLACE: The metadata specified in the request is used as the metadata of the destination object.

Important

If the path of the source object is the same as that of the destination object and versioning is not enabled for the bucket in which the source and destination objects are stored, metadata specified in the CopyObject request is used as the metadata of the destination object regardless of the value of the x-oss-metadata-directive header.

x-oss-server-side-encryption

String

No

AES256

The entropy coding-based encryption algorithm that OSS uses to encrypt an object when you create the object.

Valid values: AES256 and KMS.

You must activate Key Management Service (KMS) in the OSS console before you can use the KMS encryption algorithm. Otherwise, KmsServiceNotEnabled is returned.

  • If the x-oss-server-side-encryption header is not specified in the CopyObject request, the destination object is not encrypted on the server, regardless of whether the source object is encrypted on the server.

  • If the x-oss-server-side-encryption header is specified in the CopyObject request, the destination object is encrypted on the server after the CopyObject operation is performed, regardless of whether the source object is encrypted on the server. In addition, the response to a CopyObject request contains the x-oss-server-side-encryption header whose value is the encryption algorithm of the destination object.

    When the destination object is downloaded, the x-oss-server-side-encryption header is included in the response. The value of the header is the encryption algorithm of the destination object.

x-oss-server-side-encryption-key-id

String

No

9468da86-3509-4f8d-a61e-6eab1eac****

The ID of the CMK that is managed by KMS.

This parameter is valid only when x-oss-server-side-encryption is set to KMS.

x-oss-object-acl

String

No

private

The access control list (ACL) that is specified for the destination object when the object is created.

Valid values:

  • default (default): The ACL of the object is the same as the ACL of the bucket in which the object is stored.

  • private: The ACL of the object is private. Only the owner of the object and authorized users can read and write this object.

  • public-read: The ACL of the object is public-read. Only the owner of the object and authorized users can read and write this object. Other users can only read the object. Exercise caution when you set the object ACL to this value.

  • public-read-write: The ACL of the object is public-read-write. All users can read and write this object. Exercise caution when you set the object ACL to this value.

For more information about ACLs, see Object ACL.

x-oss-storage-class

String

No

Standard

The storage class of the object that you want to upload.

If you specify the storage class when you upload the object, the specified storage class applies regardless of the storage class of the bucket to which the object is uploaded. For example, if you set x-oss-storage-class to Standard when you upload an object to an IA bucket, the storage class of the uploaded object is Standard.

Valid values:

  • Standard (default)

  • IA

  • Archive

  • ColdArchive

  • DeepColdArchive

    Important

    If you copy a large number of objects and specify the storage class of the destination objects as Deep Cold Archive, high PUT request fees are generated. We recommend that you configure lifecycle rules to convert the storage class of the objects to Deep Cold Archive. This helps reduce PUT request fees. For more information about lifecycle rules, see Lifecycle rules based on the last modified time.

For more information about storage classes, see Overview.

x-oss-tagging

String

No

a:1

The tag of the destination object. You can configure multiple tags for the destination object. Example: TagA=A&TagB=B.

Note

The tag key and value must be URL-encoded. If a key-value pair does not contain an equal sign (=), the tag value is considered an empty string.

x-oss-tagging-directive

String

No

Copy

The method that is used to configure tags for the destination object. Valid values:

  • Copy (default): The tags of the source object are copied to the destination object.

  • Replace: The tags specified in the request are configured for the destination object.

For more information about the common request headers included in a CopyObject request, such as Host and Date, see Common request headers.

Response headers

The response to a CopyObject request contains only common response headers. For more information, see Common HTTP headers.

Response elements

Element

Type

Example

Description

CopyObjectResult

Container

N/A

The results of the CopyObject operation.

ETag

String

5B3C1A2E053D763E1B002CC607C5****

The ETag value of the destination object.

Parent nodes: CopyObjectResult

LastModified

String

Fri, 24 Feb 2012 07:18:48 GMT

The time when the destination object was last modified.

Parent nodes: CopyObjectResult

Examples

  • Copy an object within an unversioned bucket

    Sample request

    PUT /test%2FAK.txt HTTP/1.1
    Host: tesx.oss-cn-zhangjiakou.aliyuncs.com
    Accept-Encoding: identity
    User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
    Accept: text/html
    Connection: keep-alive
    x-oss-copy-source: /test/AK.txt
    date: Fri, 28 Dec 2018 09:41:55 GMT
    authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A****
    Content-Length: 0

    Sample response

    x-oss-hash-crc64ecma indicates the 64-bit CRC value of the object. This value is calculated based on the ECMA-182 standard. An object generated by the CopyObject operation may not have this value.

    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Fri, 28 Dec 2018 09:41:56 GMT
    Content-Type: application/xml
    Content-Length: 184
    Connection: keep-alive
    x-oss-request-id: 5C25EFE4462CE00EC6D87156
    ETag: "F2064A169EE92E9775EE5324D0B1****"
    x-oss-hash-crc64ecma: 12753002859196105360
    x-oss-server-time: 150
    <?xml version="1.0" encoding="UTF-8"?>
    <CopyObjectResult>
      <ETag>"F2064A169EE92E9775EE5324D0B1****"</ETag>
      <LastModified>2018-12-28T09:41:56.000Z</LastModified>
    </CopyObjectResult>
  • Copy an object in a versioned bucket without specifying a version ID

    Sample request

    PUT /dest-object-example HTTP/1.1
    Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Authorization: OSS qeyxjc9arppwa0t:QqwOjq7U7j04NVpPqdfcVk0I****
    x-oss-copy-source: /versioning-copy-source/source-object

    Sample response

    x-oss-copy-source-version-id in the response indicates the version ID of the source object. In this example, the version ID is the current version of the source object. x-oss-version-id indicates the version ID of the destination object.

    HTTP/1.1 200 OK
    x-oss-copy-source-version-id: CAEQNRiBgIC28uaA0BYiIDY5OGIwNmNlNjYyMTRjNTc4N2M2OGNiMjZkZTQ2****
    x-oss-version-id: CAEQNxiBgIDG8uaA0BYiIGZhZDRkZTk5Zjg3YzRhNzdiMWEwZGViNDM1NTFh****
    x-oss-request-id: 5CAC155CB7AEADE01700****
    Content-Type: application/xml
    Content-Length: 184
    Connection: keep-alive
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <CopyObjectResult>
      <ETag>"C81E728D9D4C2F636F067F89CC14****"</ETag>
      <LastModified>2019-04-09T03:45:32.000Z</LastModified>
    </CopyObjectResult>
  • Copy an object in a versioned bucket by specifying a version ID

    Sample request

    PUT /dest-object-example HTTP/1.1
    Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Authorization: OSS qeyxjc9arppwa0t:5qG4DLaHjxDPtpLlf2e8fBfX****
    x-oss-copy-source: /versioning-copy-source/source-object?versionId=CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****

    Sample response

    x-oss-copy-source-version-id in the response indicates the version ID of the source object. In this example, the version ID of the source object is specified by versionId in x-oss-copy-source. x-oss-version-id indicates the version ID of the destination object.

    HTTP/1.1 200 OK
    x-oss-copy-source-version-id: CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****
    x-oss-version-id: CAEQNxiBgMDP8uaA0BYiIDIyNGNhZDQ1M2M3NzRkZThiNzE0N2I3ZDkxOWY4****
    x-oss-request-id: 5CAC155CB7AEADE01700****
    Content-Type: application/xml
    Content-Length: 184
    Connection: keep-alive
    Date: Tue, 09 Apr 2019 03:45:32 GMT
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <CopyObjectResult>
      <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
      <LastModified>2019-04-09T03:45:32.000Z</LastModified>
    </CopyObjectResult>

SDK

You can use OSS SDKs for the following programming languages to call the CopyObject operation:

Error codes

Error code

HTTP status code

Description

InvalidArgument

400

The values of parameters, such as x-oss-storage-class, are invalid.

Precondition Failed

412

  • The x-oss-copy-source-if-match header is specified in the request, but the ETag value of the source object is different from the ETag value in the request.

  • The x-oss-copy-source-if-unmodified-since header is specified in the request, but the time specified in the request is earlier than the last modified time of the object.

Not Modified

304

  • The x-oss-copy-source-if-none-match header is specified in the request, but the ETag value of the source object is the same as the ETag value in the request.

  • The x-oss-copy-source-if-modified-since header is specified in the request, but the source object has not been modified since the time specified in the request.

KmsServiceNotEnabled

403

The x-oss-server-side-encryption header is set to KMS, but KMS is not activated in advance.

FileAlreadyExists

409

  • The request contains the x-oss-forbid-overwrite=true header, and the bucket contains an object that has the same name as the object specified in the request.

  • The source object or the destination object is a directory within a bucket for which the hierarchical namespace feature is enabled.

FileImmutable

409

The data that you want to delete or modify is protected by a retention policy.

FAQ

Can I call the CopyObject operation to copy multiple objects at a time?

No, you cannot. CopyObject is used to copy one object at a time. If you want to copy multiple objects at a time, you can use ossutil. For more information, see Copy objects.