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

Versioning

If you do not specify a version ID in the x-oss-copy-source header of the CopyObject request, the current version of the object is copied. You can add a version ID 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, you can copy the previous version of the object to the bucket in which the object is stored. Then, the previous version of the object is stored as the current version.

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

Limits

  • The following limits on the size of an object apply when you call the CopyObject operation:
    • If you copy objects within a bucket, no limit is imposed on the size of the object that is copied by calling the CopyObject operation.
    • If you copy objects between buckets in the same region, we recommend that you call this operation to copy objects smaller than 1 GB. To copy objects larger than 1 GB, you can call the UploadPartCopy operation.

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

  • The following limits apply when you call CopyObject to copy an object within an unversioned bucket and 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 objects and copies the content of the object.
  • In versioned buckets, objects generated by using append upload cannot be copied.
  • If the source object is a symbolic link, only the symbolic link is copied. The object to which the symbolic link points is not copied.
  • Directories in buckets for which the hierarchical namespace feature is enabled 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 you call the CopyObject operation to modify the storage class of an object by overwriting the object. For example, if you call the CopyObject operation to convert an 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 period 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-. Therefore, these headers must be added to the signature string.

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 that of the object you want to copy.
  • If x-oss-forbid-overwrite is not specified or x-oss-forbid-overwrite is set to false, an existing object with the same name as the object to copy is overwritten.
  • If x-oss-forbid-overwrite is set to true, an existing object with the same name as the object to copy cannot be overwritten.

If you specify the x-oss-forbid-overwrite request 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.

Default value: null.

x-oss-copy-source-if-match STRING No 5B3C1A2E053D763E1B002CC607C5**** 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.

Default value: null.

x-oss-copy-source-if-none-match STRING No 5B3C1A2E053D763E1B002CC607C5**** 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.

Default value: null.

x-oss-copy-source-if-unmodified-since STRING No Mon, 11 May 2020 08:16:23 GMT If the time that is specified in the request is the same as or later than the modified time of the object, OSS copies the object and returns 200 OK.

Default value: null.

x-oss-copy-source-if-modified-since STRING No Mon, 11 May 2020 08:16:23 GMT If the time that is specified in the request is earlier than the actual modified time of the object, OSS copies the object and returns 200 OK.

Default value: null.

x-oss-metadata-directive STRING No COPY The method used to configure the metadata of the destination object. Default value: COPY.
  • COPY: The metadata of the source object is copied to the destination object.

    The x-oss-server-side-encryption attribute of the source object is not copied to the destination object. The x-oss-server-side-encryption parameter in the CopyObject request specifies the method used to encrypt the destination object.

  • REPLACE: The metadata specified in the request instead of the metadata of the source object is used as the metadata of the destination object.
Notice 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 x-oss-metadata-directive.
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 enable 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, the value of which is set to the algorithm used to encrypt the destination object.

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

x-oss-server-side-encryption-key-id STRING No 9468da86-3509-4f8d-a61e-6eab1eac**** The ID of the customer master key (CMK) 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 ACL of the destination object when the object is created. Default value: default.
Valid values:
  • 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 have read and write permissions on the object.
  • public-read: The ACL of the object is public read. Only the owner of the object and authorized users have read and write permissions on the object. Other users have only read permissions on 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 have read and write permissions on the object. Exercise caution when you set the object ACL to this value.

For more information about object ACLs, see Object ACL.

x-oss-storage-class STRING No Standard The storage class of the object that you want to upload. Default value: Standard.

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
  • IA
  • Archive
  • ColdArchive

For more information about storage classes, see Overview.

x-oss-tagging STRING No a:1 The tags 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 used to configure tags for the destination object. Default value: Copy. Valid values:
  • Copy: The tags of the source object are copied to the destination object.
  • Replace: The tags specified in the request instead of the tags of the source object are configured for the destination object.

For more information about the common request headers included in CopyObject requests 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 response headers.

Response elements

Element Type Example Description
CopyObjectResult STRING N/A The result of the CopyObject operation.

Default value: null.

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 in a bucket that does not have versioning enabled.
    Sample requests
    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 responses

    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 requests
    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 responses

    x-oss-copy-source-version-id in the sample response indicates the version ID of the source object. In this example, x-oss-copy-source-version-id indicates 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 requests
    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 responses

    x-oss-copy-source-version-id in the sample response indicates the version ID of the source object. In this example, x-oss-copy-source-version-id indicates the version ID specified by x-oss-copy-source in the request. 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>

SDKs

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

Error codes

Error code HTTP status code Description
InvalidArgument 400 The error message returned because the values of parameters such as x-oss-storage-class are invalid.
Precondition Failed 412 The error message returned due to the following possible causes:
  • 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 error message returned due to the following possible causes:
  • 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 after the time specified in the request.
KmsServiceNotEnabled 403 The error message returned because the x-oss-server-side-encryption header is set to KMS, but KMS is not activated in advance.
FileAlreadyExists 409 The error message returned due to the following possible causes:
  • The request contains the x-oss-forbid-overwrite=true header, but an object that has the same name as the object that you want to upload already exists.
  • The object that you want to copy is a directory within a bucket for which the hierarchical namespace feature is enabled.
FileImmutable 409 The error message returned because the data you want to delete or modify is protected by a retention policy.