Object Storage Service:CopyObject

Versioning

By default, x-oss-copy-source copies the current version of an object. To copy a specific version, include the version ID in x-oss-copy-source. If the specified source version is a delete marker, OSS returns a 404 error, indicating the object does not exist.

To restore a previous version of an object, copy that version to the same bucket. This action makes the copied version the new current version.

If versioning is enabled for the destination bucket, OSS automatically generates a unique version ID for the newly copied object. This version ID is returned in the x-oss-version-id response header. If versioning is disabled or suspended for the destination bucket, OSS generates a version with a null version ID for the new object. This new version overwrites any existing version that has a null version ID.

Limitations

• Object size limits

  • Objects larger than 5 GB can be copied within the same bucket if you do not change the encryption method or storage class.

  • If the source and destination buckets are different, and you do not change the encryption method or storage class of the object during the copy operation, the object cannot be larger than 5 GB.

  • If you change the object's encryption method or storage class during the copy, the object size is limited to 1 GB. For larger objects, you must use the UploadPartCopy operation.

• Permission

  Both the CopyObject and UploadPartCopy operations require read permission on the source object.

• If you use the CopyObject operation in a bucket where versioning is disabled and the source and destination objects are the same:

  • If the encryption method or storage class is not changed, OSS modifies only the metadata of the object and does not copy its content.

  • If the encryption method or storage class is changed, OSS modifies the metadata and also copies the content of the object.

• Source object is a symbolic link

  If you use the CopyObject operation on a symbolic link, only the symbolic link is copied. The content of the object to which the symbolic link points is not copied.

• Hierarchical namespace is enabled for the bucket

  You cannot copy directories within a bucket for which hierarchical namespace is enabled.

• Preventing object overwrite conflicts

  If you enable Prevent File Overwrite, you cannot use CopyObject to change an object's storage class, such as from Standard to Archive Storage. Instead, use a lifecycle rule to automatically transition the storage class.

• ObjectWorm limitations

  When you copy an appendable object, you cannot include ObjectWorm-related parameters in the request.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

Billing

• Each call to the CopyObject operation counts as one PUT request for the destination bucket.

• The CopyObject operation increases the storage usage of the destination bucket.

• Using CopyObject to change an object's storage class is a data overwrite operation. For example, if an Infrequent Access (IA) object is overwritten and its storage class is changed to Standard within 10 days of its creation, a fee is charged for 20 days of IA storage because the minimum storage duration was not met. For more information about storage fees, see Storage fees.

• Calling the CopyObject operation on an Infrequent Access (IA) object incurs a data retrieval fee for IA storage. If the source object is an unrestored Archive Storage object in a bucket with real-time access enabled, a data retrieval fee for real-time access is incurred. These fees are charged to the account that owns the source bucket. For more information about billing, see Data processing 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 request headers for a copy operation start with x-oss- and must be included in the signature string.

This operation also uses common request headers, such as Host and Date. For more information, see Common Request Headers.

Response headers

This operation uses only common response headers. For more information, see Common Response Headers.

Response elements

Examples

• Versioning is disabled

  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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  Content-Length: 0

  Sample response

  The x-oss-hash-crc64ecma header indicates the 64-bit CRC value of the object. This value is calculated based on the CRC-64/XZ standard. The CopyObject operation does not guarantee that the generated object has a 64-bit CRC 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 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  x-oss-copy-source: /versioning-copy-source/source-object

  Sample response

  In this example, x-oss-copy-source-version-id is the version ID of the source object, which is the current version. The x-oss-version-id header contains the version ID of the newly copied 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 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  x-oss-copy-source: /versioning-copy-source/source-object?versionId=CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****

  Sample response

  In this example, x-oss-copy-source-version-id is the version ID of the source object, which is the version specified in the x-oss-copy-source request header. The x-oss-version-id header contains the version ID of the newly copied 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 the SDKs for the following languages to call this operation:

• Java

• Python V2

• PHP V2

• Go V2

• Harmony

• C

• .NET

• Android

• iOS

• Node.js

• Ruby

• Browser.js

• C++

ossutil CLI

For the ossutil command that corresponds to the CopyObject operation, see copy-object.

Error codes

FAQ

Does CopyObject support copying multiple objects at once?

The CopyObject operation copies only a single object. To copy multiple objects in a batch, use the ossutil command-line tool.