Copies objects within a bucket or between buckets in the same region. By calling CopyObject, you can send a PUT request to OSS. OSS automatically recognizes the request as a copy operation and perform it on the server.

Limits

  • CopyObject only supports objects smaller than 1 GB. To copy objects larger than 1 GB, you must use UploadPartCopy.
  • You can call CopyObject to modify the metadata of an object that equals to or smaller than 48.8 TB (by setting the source object and target object to the same object).
  • To use CopyObject, you must have the read permission on the source object.
  • The source object and the target object must be in the same region.
  • You cannot copy objects created by AppendObject.
  • If the source object is a symbolic link, only the symbolic link (instead of the content that the link directs to) is copied.

Billing items

  • A GET request is billed according to the bucket where the source object is stored.
  • A PUT request is billed according to the bucket where the target object is stored.
  • The used storage capacity is billed according to the bucket where the target object is stored.
  • If you change the storage class of an object by calling CopyObject, the object is considered as overwritten and will incur charges. An object of the IA or Archive storage class will be charged if it is overwritten within 30 and 60 days respectively after it is created. 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 will be 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 header

Note The request headers used in copy operations start with x-oss-. Therefore, these headers must be added into the signature string.
Header Type Required Description
x-oss-copy-source String Yes Specifies the address of the source object.

Default value: None.

x-oss-copy-source-if-match String No If the ETag of the source object is the same as the ETag provided by the user, the copy operation is performed and a 200 OK message is returned. Otherwise, a 412 Precondition Failed error code (preprocessing failed) is returned.

Default value: None.

x-oss-copy-source-if-none-match String No If the ETag of the source object is different from the ETag provided by the user, the copy operation is performed and a 200 OK message is returned. Otherwise, a 304 Not Modified error code (preprocessing failed) is returned.

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, the object is copied normally and a 200 OK message is returned. Otherwise, a 412 Precondition Failed error code (preprocessing failed) is returned.

Default value: None.

x-oss-copy-source-if-modified-since String No If the source object is modified after the time specified by the user, the copy operation is performed. Otherwise, a 304 Not Modified error code (preprocessing failed) is returned.

Default value: None.

x-oss-metadata-directive String No
Specifies how to set the metadata of the target object. The valid values are COPY and REPLACE.
  • COPY (default): The metadata of the source object is copied to the target object. The x-oss-server-side-encryption of the source object is not copied. That is, server-side encryption is performed on the target object only if the x-oss-server-side-encryption header is specified in the COPY request.
  • REPLACE: The metadata of the target object is set to the metadata specified in the user's request instead of the metadata of the source object.
Note If the source object and the target object have the same address, the metadata of the target object is replaced with the metadata of the source object regardless of the value of x-oss-metadata-directive.
x-oss-server-side-encryption String No Specifies the server-side entropy encoding encryption algorithm when OSS creates the target object.
Valid values:
  • AES256
  • KMS (You must enable KMS in the console before you can use the KMS encryption algorithm. Otherwise, a KmsServiceNotEnabled error code is returned.)
Note
  • If the x-oss-server-side-encryption header is not specified in the copy operation, the target object is not encrypted on the server side no matter whether server-side encryption has been performed on the source object.
  • If you specify the x-oss-server-side-encryption header, server-side encryption is performed on the target object no matter whether the encryption has been performed on the source object. In addition, the response header for the copy request includes the x-oss-server-side-encryption header, and the value of the header is the encryption algorithm of the target object. When the target object is downloaded, the response header also includes the x-oss-server-side-encryption header, and the value of the header is the encryption algorithm of the target object.
x-oss-server-side-encryption-key-id String No Indicates the primary key managed by KMS.

This parameter is valid when the value of x-oss-server-side-encryption is KMS.

x-oss-object-acl String No Specifies the ACL for the target object when it is created.
Valid values:
  • public-read
  • private
  • public-read-write
  • default
x-oss-storage-class String No Specifies the storage class of the object.
Valid values:
  • Standard
  • IA
  • Archive

Supported interfaces: PutObject, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

Note
  • If the value of StorageClass is invalid, a 400 error message is returned with an error code: InvalidArgument.
  • We recommend that you do not set the storage class to IA or Archive when calling CopyObject because an IA or Archive object smaller than 64 KB is billed at 64 KB.
  • 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 specified value of x-oss-storage-class. For example, if you specify the value of x-oss-storage-class to Standard when uploading 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 as overwritten and will incur charges. An object of the IA or Archive class will be charged if it is overwritten within 30 and 60 days respectively after it is created.
x‑oss‑tagging String No
Specifies the tag of the object. You can set multiple tags at the same time, for example, TagA=A&TagB=B.
Note You must perform URL encoding for the tag key and value in advance. If a tag does not contain an equal sign (=), this string does not have a value.
x‑oss-tagging-directive String No Specifies how to set the tag of the target object. The valid values are Copy and Replace.
  • Copy (default): The tag of the source object is copied to the target object.
  • Replace: The tag of the target object is set to the tag specified in the request instead of the tag of the source object.

Response elements

Table 1. Response elements
Name Type Description
CopyObjectResult String Indicates the result of CopyObject.

Default value: None.

ETag String Indicates the ETag of the target object.

Parent node: CopyObjectResult

LastModified String Indicates the time when the target object is last modified.

Parent node: CopyObjectResult

Examples

  • Example 1

    Request example:

    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+n0=

    Response example:

    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>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
    </CopyObjectResult>
  • Example 2

    Request example:

    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+n0=
    Content-Length: 0

    Response example:

    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: "F2064A169EE92E9775EE5324D0B1682E"
    x-oss-hash-crc64ecma: 12753002859196105360
    x-oss-server-time: 150
    <? xml version="1.0" encoding="UTF-8"? >
    <CopyObjectResult>
      <ETag>"F2064A169EE92E9775EE5324D0B1682E"</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 in a COPY operation may not have this value.

SDK

The SDKs of this API are as follows:

Error codes

Error code HTTP status code Description
InvalidArgument 400 The values of parameters (such as x-oss-storage-class are invalid.
Precondition Failed 412
  • The x-oss-copy-source-if-match header is specified in the request, but the provided ETag is different from the ETag of the source object.
  • The x-oss-copy-source-if-unmodified-since header is specified in the request, but the time specified in the request is earlier than the modification time of the object.
Not Modified 304
  • The x-oss-copy-source-if-none-match header is specified in the request, and the provided ETag is the same as the ETag of the source object.
  • The x-oss-copy-source-if-modified-since header is specified in the request, but the source object has not been modified after the time specified in the request.
KmsServiceNotEnabled 403 The x-oss-server-side-encryption header is set to KMS, but the KMS service is not enabled.