You can call this operation to copy objects within a bucket or between buckets in the same region.
Versioning
By default, the value of the x-oss-copy-source
header in a CopyObject request specifies the current version of the object to copy.
You can add a version ID to the value of x-oss-copy-source
to copy a specified version of the object. If the specified version of the object
to copy is a delete marker, OSS returns 404 Not Found, which indicates that the object
does not exist.
To recover a previous version of an object to the current version, you can copy the previous version of the object to the bucket in which the object is stored. OSS then stores the previous version of the object as the current version.
If versioning is enabled for the destination bucket, OSS generates a unique version
ID for the object copied to the destination bucket. The version ID is returned as
the x-oss-version-id
header in the response. If versioning is not enabled or suspended for the destination
bucket, OSS generates a version whose ID is null for the object copied to the destination
bucket, and overwrites the original version whose ID is null.
Limits
- CopyObject can be used to copy only objects smaller than 1 GB in size. To copy objects
larger than 1 GB in size, we recommend that you call the UploadPartCopy operation.
To use CopyObject or UploadPartCopy, you must have read permissions on the source object.
- If you use CopyObject to copy an object to the same unversioned bucket in which the object is stored, only the metadata of the object is updated. The content of the object is not copied.
- Append objects stored in versioned buckets cannot be copied.
- If the source object is a symbolic link, only the symbolic link is copied. The object to which the symbolic link points is not copied.
- Directories in buckets for which the hierarchical namespace feature is enabled cannot be copied.
Billable items
- Each time when 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 call the CopyObject operation to modify the storage class of an object by overwriting the object, corresponding fees are incurred. For example, if you call CopyObject to convert an IA object to a Standard object by overwriting the IA object 10 days after the IA object is created, you are charged for the entire minimum storage period of 30 days. For more information about storage fees, see Storage fees.
Request structure
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 headers in a CopyObject request start with x-oss-. Therefore, these headers must be added to the signature string.
Header | Type | Required | Example | Description |
---|---|---|---|---|
x-oss-forbid-overwrite | String | No | true | Specifies whether the CopyObject operation overwrites the object with the same name.
The x-oss-forbid-overwrite request header is invalid when versioning is enabled or suspended for the destination
bucket. In this case, the CopyObject operation overwrites the object with the same
name.
If you specify the x-oss-forbid-overwrite request header, the queries per second (QPS) performance of OSS may degrade. If you want to specify the x-oss-forbid-overwrite header in multiple requests to perform a large number of operations (QPS greater than 1,000), submit a ticket. Default value: false. |
x-oss-copy-source | String | Yes | /oss-example/oss.jpg | The path of the source object.
Default value: null |
x-oss-copy-source-if-match | String | No | 5B3C1A2E053D763E1B002CC607C5**** | 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.
Default value: null |
x-oss-copy-source-if-none-match | String | No | 5B3C1A2E053D763E1B002CC607C5**** | 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.
Default value: null |
x-oss-copy-source-if-unmodified-since | String | No | 2019-04-09T07:01:56.000Z | If the time specified in the request is the same as or later than the modified time
of the object, OSS copies the object and returns 200 OK.
Default value: null |
x-oss-copy-source-if-modified-since | String | No | 2019-04-09T07:01:56.000Z | If the source object is modified after the time specified in the request, OSS copies
the object.
Default value: null |
x-oss-metadata-directive | String | No | COPY | The method used to configure the metadata of the destination object. Default value:
COPY.
Notice If the path of the source object is the same as that of the destination object and
versioning is not enabled for the bucket in which the source and destination objects
are stored, metadata specified in the CopyObject request is used as the metadata of
the destination object regardless of the value of x-oss-metadata-directive.
|
x-oss-server-side-encryption | String | No | AES256 | The entropy coding-based encryption algorithm that OSS uses to encrypt an object when
you create the object.
Valid values: AES256 and KMS. You must enable Key Management Service (KMS) on the console before you can use the KMS encryption algorithm. Otherwise, KmsServiceNotEnabled is returned.
|
x-oss-server-side-encryption-key-id | String | No | 9468da86-3509-4f8d-a61e-6eab1eac**** | The ID of the customer master key (CMK) hosted in KMS.
This parameter is valid only when x-oss-server-side-encryption is set to KMS. |
x-oss-object-acl | String | No | private | The ACL configured when OSS creates the destination object.
Valid values: public-read, private, public-read-write, and default. For more information about object ACLs, see ACL. |
x-oss-storage-class | String | No | Standard | The storage class of the destination object.
Valid values: Standard, IA, Archive, and ColdArchive. For more information about storage classes, see Overview. Supported operations: PutObject, InitiateMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject |
x-oss-tagging | String | No | a:1 | The tags of the destination object. You can configure multiple tags for the destination
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 | Copy | The method used to configure tags for the destination object. Default value: Copy.
Valid values:
|
For more information about the common request headers included in CopyObject requests such as Host and Date see Common request headers.
Response headers
The response to a CopyObject request contains only common response headers. For more information, see Common response headers.
Response elements
Element | Type | Example | Description |
---|---|---|---|
CopyObjectResult | String | N/A | The result of the CopyObject operation.
Default value: null |
ETag | String | 5B3C1A2E053D763E1B002CC607C5**** | The ETag value of the destination object.
Parent nodes: CopyObjectResult |
LastModified | String | Fri, 24 Feb 2012 07:18:48 GMT | The time when the destination object was last modified.
Parent nodes: CopyObjectResult |
Examples
- Copy an object in an unversioned bucket.
Sample requests
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: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A**** Content-Length: 0
Sample responses
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.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 in a versioned bucket without specifying a version ID.
Sample requests
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
x-oss-copy-source-version-id
in the sample response indicates the ID of the copied version 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.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 in a versioned bucket by specifying a version ID.
Sample requests
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
x-oss-copy-source-version-id
in the sample response indicates the ID of copied version of the source object. In this example, x-oss-copy-source-version-id indicates the version ID specified byx-oss-copy-source
in the request.x-oss-version-id
indicates the version ID of the destination 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>
SDK
You can use OSS SDKs for the following programming languages to call the CopyObject operation:
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 | Possible causes:
|
Not Modified | 304 | Possible causes:
|
KmsServiceNotEnabled | 403 | The error message returned because the x-oss-server-side-encryption header is set to KMS, but KMS is not activated in advance. |
FileAlreadyExists | 409 | Possible causes:
|
FileImmutable | 409 | The error message returned because you delete or modify protected. During the protection period, data in the bucket cannot be deleted or modified. |