Object Storage Service:CopyObject

Versioning

You can specify a version ID to the x-oss-copy-source header to copy a specified version of the object. 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. 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 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 existing version whose ID is null.

Limits

• The following limits in object size apply when you call the CopyObject operation:
  • If you copy objects within a bucket, we recommend that you call the CopyObject operation to copy objects smaller than 5 GB.
  • If you copy objects between buckets in the same region, we recommend that you call the CopyObject operation to copy objects smaller than 1 GB. To copy objects larger than 1 GB, you can 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

  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 object and copies the content of the object.
• The following limits apply when you call the CopyObject operation to copy an object within a versioning-enabled 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.

Billable rules

• 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 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-. These headers must be added to the signature string. The following table describes the headers.

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 response headers.

Response parameters

Examples

• Copy an object within 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 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 indicates the ID of the version of the source object. In this example, the value of x-oss-copy-source-version-id is the current version of the source object. The value of x-oss-version-id is 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 is the ID of version of the source object. In this example, the value of x-oss-copy-source-version-id is the version ID specified by x-oss-copy-source in the request. The value of x-oss-version-id is 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>

OSS SDKs

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

FAQ

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

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