CopyObject

Versioning

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, 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 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 original version whose ID is null.

Limits

• CopyObject can be used to copy only objects smaller than 1 GB in size. To copy objects larger than 1 GB in size, we recommend that you call the UploadPartCopy operation.

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

• If you use 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 when you call the CopyObject operation, fees are incurred for a GET request to the source bucket and a PUT request to the destination bucket.
• Storage usage of the destination bucket is increased 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 incurred. 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. For more information about storage fees, see Storage fees.

Request structure

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

Examples

• Copy an object in an unversioned bucket.
  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 ID of the copied 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 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 ID of copied version 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