You can call this operation to copy objects within a bucket or between different 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 current 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 smaller than 1 GB in size. To copy objects larger 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 smaller 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 located in the same region.
  • You cannot copy objects that are created by using AppendObject.
  • If the source object is a symbolic link, only the symbolic link is copied but not the object to which the link points.

Billing

  • 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.
  • Storage usage of the destination bucket is increased when you call the CopyObject operation.
  • If you use the CopyObject operation to change the storage class of an object, the object is considered to be overwritten and fees are 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 destination bucket is in the Enabled or Suspended versioning state. In this case, the PutObject operation overwrites the object with the same name.
  • Specifying the x-oss-forbid-overwrite request header may degrade the queries per second (QPS) performance of OSS. If you want to use the x-oss-forbid-overwrite request header to perform a large number of operations (QPS greater than 1000), submit a ticket.
x-oss-copy-source String Yes The address of the source object.

Default value: none
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.

Default value: none
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.

Default value: none
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.

Default value: none
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.

Default value: none
x-oss-metadata-directive String No Specifies how to set the metadata of the destination object. Valid values:
  • COPY

    The metadata of the source object is copied to the destination object. This is the default value.

    x-oss-server-side-encryption of the source object is not copied. 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 is used, instead of the metadata of the source object.

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 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, the KmsServiceNotEnabled error code is returned.

  • 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 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 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 The storage class of the destination object.

Valid values: Standard, IA, Archive, and ColdArchive

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

  • IA, Archive and Cold Archive objects that are smaller 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 you upload an object to a bucket, the storage class of the uploaded object is the value of x-oss-storage-class. For example, if you set the value of x-oss-storage-class to Standard when you upload an object to a bucket of the IA storage class, the storage class of the object is Standard.
  • If you change the storage class of an object, the object is considered to be overwritten and fees are 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 The object tag. 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 to be 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 The result of the CopyObject operation.

Default value: none
ETag String The ETag value of the destination object.

Parent node: CopyObjectResult
LastModified String 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 responses 
    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: tesx.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 responses 
    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 responses 
    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, x-oss-copy-source-version-id 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 responses 
    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, x-oss-copy-source-version-id 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.

SDK

The SDKs of the CopyObject operation for various programming languages:

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 modified 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.
FileImmutable 409 The error message returned because you delete or modify the data. During the protection period, data in the bucket is protected.