CopyObject is used to copy objects within a bucket or between buckets in the same region.

This interface sends a PUT request to OSS and adds the x-oss-copy-source element in the PUT request header to specify the source object. OSS recognizes the request as a copy operation and perform this operation on the server. If the copy operation is successful, the information about the target object is returned.

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

Name Type Description
x-oss-copy-source String Specifies the address of the source object.

Default value: None
x-oss-copy-source-if-match String 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 HTTP error code (preprocessing failed) is returned.

Default value: None
x-oss-copy-source-if-none-match String 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 HTTP error code (preprocessing failed) is returned.

Default value: None
x-oss-copy-source-if-unmodified-since String If the time specified in the received parameter is the same as or later than the modification time of the object, the object is transferred normally and a 200 OK message is returned. Otherwise, a 412 Precondition Failed error code is returned.

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

Default value: None
x-oss-metadata-directive String
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 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 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. Additionally, 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.
  • 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.
x-oss-object-acl String Specifies the access permission of the target object when it is created.
Valid values:
  • public-read
  • private
  • public-read-write
x-oss-storage-class String 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 is returned. Error code: InvalidArgument
  • We recommend that you do not set the storage class in PutObjectSymlink to IA or Archive because an IA or Archive object smaller than 64 KB is billed as 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. 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.

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 element: CopyObjectResult
LastModified String Indicates the time when the target object is last modified.

Parent element: CopyObjectResult

Detail analysis

  • Limits
    • CopyObject only supports objects smaller than 1 GB. To copy objects larger than 1 GB, you must use MultipartUpload. For more information, see UploadPartCopy.
    • The requester 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 with 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.
  • Predetermined request headers
    • You can include any number of the four predetermined request headers (x-oss-copy-source-if-match, x-oss-copy-source-if-none-match, x-oss-copy-source-if-unmodified-since, and x-oss-copy-source-if-modified-since) in a request at the same time. For more information, see Detail analysis in GetObject.
    • The request headers used in the copy operation start with x-oss-. Therefore, these headers must be added into the signature string.

Example

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>