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, which indicates that the object does not exist.

You can restore an earlier version of an object as the current version by copying the earlier version to the same bucket. OSS then sets that earlier version as the 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.

Limits

• Object size limits

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

  • 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 encryption method or storage class of the object during the copy operation, the object cannot be larger than 1 GB. If the object is larger than 1 GB, you must use the UploadPartCopy operation.

• Permissions

  Both the CopyObject and UploadPartCopy operations require read permissions 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 file to which the symbolic link points is not copied.

• Hierarchical namespace is enabled for the bucket

  If hierarchical namespace is enabled for the bucket, you cannot copy directories.

• Preventing file overwrite conflicts

  If you enable Prevent File Overwrite, you cannot use CopyObject to change a file's storage class, such as from Standard to Archive Storage. Instead, use automatic lifecycle conversion.

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.

• Changing the storage class of an object using the CopyObject operation involves data overwrites. 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.

• When you call the CopyObject operation, if the source object is an IA object, a data retrieval fee for IA storage is incurred. If the source object is an Archive Storage object that has not been restored using RestoreObject and real-time access of Archive objects is enabled for the bucket, 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-. Therefore, you must add all these request headers to 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

  x-oss-hash-crc64ecma indicates the 64-bit CRC value of the object. This 64-bit CRC 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 in this case is the current version. x-oss-version-id is 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. x-oss-version-id is 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 software development kits (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 command-line tool

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

Error codes

FAQ

Does CopyObject support batch copying of files?

No, it does not. The CopyObject operation is used to copy a single file. To copy multiple files in a batch, you can use ossutil. For more information, see cp (copy files).