CopyObject

For buckets that have versioning enabled

By default, the value of the x-oss-copy-source header in a CopyObject request specifies the current version of the object to copy. You can add a version ID to the value of 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. 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.

Usage notes

• Take note of the following limits on the size of an object when you call the CopyObject operation:
  • If the source bucket and the destination bucket are the same, no limit is imposed on the size of the object that CopyObject can be called to copy.
  • If the source bucket and the destination bucket are two different buckets, we recommend that you call this operation to copy objects smaller than 1 GB in size. To copy objects larger than 1 GB in size, you can call the UploadPartCopy operation.

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

• If you call CopyObject to copy an object to the same unversioned bucket in which the object is stored, only the metadata of the object is updated. The content of the object is not copied.
• Append objects stored in versioned buckets 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.

Billable items

• Each time you call the CopyObject operation, you are charged fees for a GET request to the source bucket and a PUT request to the destination bucket.
• The storage usage of the destination bucket increases when you call the CopyObject operation.
• If you call the CopyObject operation to modify the storage class of an object by overwriting the object, corresponding fees are charged. For example, if you call CopyObject to convert an IA object to a Standard object by overwriting the IA object 10 days after the IA object is created, you are charged for the entire minimum storage period of 30 days of the IA object. 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.

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

Response headers

The response headers involved in this API operation contain only common response headers. For more information, see Common response headers.

Response elements

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 bucket that has versioning enabled 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 ID of the version 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 bucket that has versioning enabled 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>

SDK

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

• Java
• Python
• PHP
• Go
• C
• .NET
• Android
• iOS
• Node.js
• Ruby

Error codes