Object Storage Service:CopyObject

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 specific version of the object. If the specified version of the object that you want to copy is a delete marker, Object Storage Service (OSS) returns 404 Not Found, which indicates that the object does not exist.

To restore 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 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 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 that you want to copy can be larger than 5 GB.

  • If the source bucket is not the destination bucket and storage class conversion is not involved in the CopyObject operation, the object that you want to copy cannot be greater than 5 GB.

  • If storage class conversion is involved in the CopyObject operation, the object that you want to copy cannot be greater than 5 GB. If the object that you want to copy exceeds 1 GB, you must call the UploadPartCopy operation.

• Read permissions are required.

  To call the CopyObject or UploadPartCopy operation, you must have the 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:

  • If the copy operation does not modify 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 modifies 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 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.

Metering and billing rules

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

• When you call the CopyObject operation, the storage usage of the destination bucket increases.

• You are also charged when the CopyObject operation overwrites an object to change the storage class of an object. For example, if you call the CopyObject operation to convert an Infrequent Access (IA) object into a Standard object by overwriting the IA object less than 10 days after the IA object is created, you are charged for the storage usage of IA objects that are stored for less than the minimum storage duration of 10 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-. 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 elements

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 success 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 qn6q**************:77Dv****************
  x-oss-copy-source: /versioning-copy-source/source-object

  Sample success 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 qn6q**************:77Dv****************
  x-oss-copy-source: /versioning-copy-source/source-object?versionId=CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****

  Sample success 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:

• 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, you cannot call the CopyObject operation to copy multiple objects at a time. The CopyObject operation 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.