You can call this operation to copy objects within a bucket or between buckets in the same region. When you send a PUT request to OSS by calling the CopyObject operation, OSS identifies the request as a copy operation and performs the operation on the server.

Versioning

By default, x-oss-copy-source copies the current version of the object. If the current version of the object is a delete marker, OSS returns 404, indicating that the object does not exist. You can add a version ID to x-oss-copy-source to copy the specified object version. Delete markers cannot be copied.

You can copy a previous version of an object to the same bucket. The copied previous version becomes the new version of the object. This way, the previous version of the object is restored.

If versioning is enabled for the destination bucket, OSS generates a unique version ID for the new object. The version ID is returned in x-oss-version-id of the response header. If versioning is not enabled or suspended for the destination bucket, OSS generates a version with version ID null for the new object and overwrites the original version with version ID null.

Limits

  • CopyObject only supports objects less than 1 GB in size. To copy objects greater than 1 GB in size, you can call the UploadPartCopy operation.
  • You can call the CopyObject operation to modify the metadata of an object that is equal to or less than 48.8 TB in size. The source object and destination object must be the same.
  • To use CopyObject, you must have the read permissions on the source object.
  • The source and destination objects must be in the same region.
  • You cannot copy objects that were created through the AppendObject operation.
  • If the source object is a symbolic link, only the symbolic link is copied but not the object to which the link points.

Billing items

  • Each time you call the CopyObject operation, fees are incurred for a GET request to the source bucket and a PUT request to the destination bucket.
  • The storage capacity usage is billed based on the bucket that contains the destination object.
  • If you use the CopyObject operation to change the storage class of an object, the object is considered as overwritten and fees will be incurred. Early deletion fees are incurred when IA objects are overwritten within 30 days after creation or when Archive objects are overwritten within 60 days after creation. For example, if you change the storage class of an object from IA to Archive or Standard 10 days after the object is created, early deletion fees for 20 days are charged.

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

Note The request headers used in the CopyObject operation start with x-oss-. Therefore, these headers must be added to the signature string.
Header Type Required Description
x-oss-forbid-overwrite String No Specifies whether the CopyObject operation overwrites the object with the same name.
  • By default, if x-oss-forbid-overwrite is not specified, the object with the same name is overwritten.
  • If x-oss-forbid-overwrite is set to true, the object with the same name cannot be overwritten. If x-oss-forbid-overwrite is set to false, the object with the same name can be overwritten.
Note
  • The x-oss-forbid-overwrite request header is invalid when the versioning state of the target bucket is Enabled or Suspended. In this case, the CopyObject operation overwrites the object with the same name.
  • Specifying the x-oss-forbid-overwrite request header may degrade the query per second (QPS) performance of OSS. If you want to use the x-oss-forbid-overwrite request header for a large number of operations (QPS > 1000), submit a ticket.
x-oss-copy-source String Yes Specifies the address of the source object.

This parameter is empty by default.
x-oss-copy-source-if-match String No If the ETag value of the source object is the same as the ETag value specified in the request, OSS copies the object and returns 200 OK. Otherwise, OSS returns 412 Precondition Failed, indicating that the preprocessing has failed.

This parameter is empty by default.
x-oss-copy-source-if-none-match String No If the ETag value of the source object is different from the ETag value specified in the request, OSS copies the object and returns 200 OK. Otherwise, OSS returns 304 Not Modified, indicating that the preprocessing has failed.

This parameter is empty by default.
x-oss-copy-source-if-unmodified-since String No If the specified time is the same as or later than the modification time of the object, OSS copies the object and returns 200 OK. Otherwise, OSS returns 412 Precondition Failed, indicating that the preprocessing has failed.

This parameter is empty by default.
x-oss-copy-source-if-modified-since String No If the source object is modified after the specified time, OSS copies the object. Otherwise, OSS returns 304 Not Modified, indicating that the preprocessing has failed.

This parameter is empty by default.
x-oss-metadata-directive String No Specifies how to set the metadata of the destination object. Valid values:
  • COPY (default)
    The metadata of the source object is copied to the destination object.
    Note x-oss-server-side-encryption of the source object is not copied. That is, server-side encryption is performed on the destination object only if the x-oss-server-side-encryption header is specified in the CopyObject request.
  • REPLACE

    The metadata specified in the request instead of the metadata of the source object is used.

Note If the source object URL is the same as the destination object URL in the CopyObject operation, the system replaces the metadata of the source object regardless of the value of x-oss-metadata-directive.
x-oss-server-side-encryption String No Specifies the entropy coding-based encryption algorithm that OSS uses to encrypt a new object.

Valid values: AES256 and KMS. You must activate KMS to use the KMS-based encryption algorithm. Otherwise, a KmsServiceNotEnabled error code is returned.

Note
  • If the x-oss-server-side-encryption header is not specified in the CopyObject request, the destination object is not encrypted on the server regardless of whether the source object has been encrypted on the server.
  • If the x-oss-server-side-encryption header is specified in the CopyObject request, the destination object is encrypted on the server after the CopyObject operation is performed regardless of whether the source object has been encrypted on the server. In addition, the CopyObject response header contains the x-oss-server-side-encryption header, the value of which is set to the encryption algorithm of the destination object. When the destination object is downloaded, the x-oss-server-side-encryption header is included in the response header and its value is set to the algorithm used to encrypt the object.
x-oss-server-side-encryption-key-id String No Specifies the ID of the customer master key (CMK) hosted in KMS.

This parameter takes effect only when x-oss-server-side-encryption is set to KMS.

x-oss-object-acl String No Specifies the ACL configured when OSS creates the destination object.

Valid values: public-read, private, public-read-write, and default
x-oss-storage-class String No Specifies the storage class of the object.

Valid values: Standard, IA, Archiveand ColdArchive

Supported operations: PutObject, InitiateMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

Note
  • IA, Archive or Cold Archive objects that are less than 64 KB are charged as 64 KB. We recommend that you do not set the storage class of the object to IA, Archive or Cold Archive when you call the CopyObject operation.
  • If you specify the value of x-oss-storage-class when uploading an object to a bucket, the storage class of the uploaded object is the value of x-oss-storage-class. If you set x-oss-storage-class to Standard when you upload an object to an IA bucket, the object is stored as a Standard object.
  • If you change the storage class of an object, the object is considered as overwritten and fees will be incurred. Early deletion fees are incurred when IA objects are overwritten within 30 days after creation or when Archive objects are overwritten within 60 days after creation.
x-oss-tagging String No Specifies the tag for the object. You can set multiple tags for the object. Example: TagA=A&TagB=B.
Note The tag key and value must be URL-encoded. If a key-value pair does not contain an equal sign (=), the tag value is considered as an empty string.
x-oss-tagging-directive String No Specifies how to set the tag for the destination object. Valid values:
  • Copy: The tag of the source object is copied to the destination object. This is the default value.
  • Replace: The tag of the destination object is set to the tag specified in the request instead of the tag of the source object.

Response elements

Element Type Description
CopyObjectResult String Indicates the result of the CopyObject operation.

This parameter is empty by default.
ETag String Indicates the ETag value of the destination object.

Parent node: CopyObjectResult
LastModified String Indicates the time when the destination object was last modified.

Parent node: CopyObjectResult

Examples

  • Sample request 1 
    PUT /copy_oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Fri, 24 Feb 2012 07:18:48 GMT 
x-oss-storage-class: Archive
x-oss-copy-source: /oss-example/oss.jpg 
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A****
    Sample response 
    HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
Content-Type: application/xml
Content-Length: 193
Connection: keep-alive
Date: Fri, 24 Feb 2012 07:18:48 GMT
Server: AliyunOSS
<? xml version="1.0" encoding="UTF-8"? >
<CopyObjectResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
 <LastModified>Fri, 24 Feb 2012 07:18:48 GMT</LastModified>
 <ETag>"5B3C1A2E053D763E1B002CC607C5****"</ETag>
</CopyObjectResult>
  • Sample request 2 
    PUT /test%2FAK.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
Accept-Encoding: identity
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
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 response 
    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>
    Note 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.
  • Sample request for calling the CopyObject operation without specifying a version ID 
    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 response 
    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>
    Note x-oss-copy-source-version-id in the sample response indicates the version ID of the source object. In this example, it indicates the current version of the source object. x-oss-version-id indicates the version ID of the destination object.
  • Sample request for calling the CopyObject operation by specifying a version ID 
    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 response 
    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>
    Note x-oss-copy-source-version-id in the sample response indicates the version ID of the source object. In this example, it indicates the version specified by version ID in x-oss-copy-source-version-id. x-oss-version-id indicates the version ID of the destination object.

SDKs

The SDKs of the CopyObject operation for various programming languages are as follows:

Error codes

Error code HTTP status code Description
InvalidArgument 400 The error message returned because the values of parameters such as x-oss-storage-class are invalid.
Precondition Failed 412
  • The error message returned because the x-oss-copy-source-if-match request header is specified, but the ETag value of the source object is different from the ETag value in the request.
  • The error message returned because the x-oss-copy-source-if-unmodified-since request header is specified, but the time specified in the request is earlier than the last modification time of the object.
Not Modified 304
  • The error message returned because the x-oss-copy-source-if-none-match request header is specified, but the ETag value of the source object is the same as the ETag value in the request.
  • The error message returned because the x-oss-copy-source-if-modified-since request header is specified, but the source object has not been modified since the time specified in the request.
KmsServiceNotEnabled 403 The error message returned because the x-oss-server-side-encryption request header is set to KMS, but you did not activate KMS in advance.
FileAlreadyExists 409 The error message returned because an object with the same object name already exists when the request contains the x-oss-forbid-overwrite header and the value of this header is set to true.