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 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 with the version ID null for the new object and overwrites the original version with the 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.
- To use CopyObject or UploadPartCopy, you must have the read permissions on the source object.
- The source and destination objects must be located in the same region.
- When you call CopyObject to copy an object, if the source object and the destination object are the same object, OSS only modifies the metadata of the source object but not copy the content of the object.
- Objects created by using the AppendObject operation cannot be copied.
- 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.
- 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
The request headers used in the CopyObject operation start with x-oss-. Therefore, these headers must be added to the signature string.
Parameter | Type | Required | Description |
---|---|---|---|
x-oss-forbid-overwrite | String | No | Specifies whether the CopyObject operation overwrites the object with the same name.
Note
|
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 | The method used to set the metadata of the destination object. Valid values:
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.
|
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, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject
|
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 | The method used to set the tag for the destination object. Valid values:
|
Response parameters
Parameter | 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 success responseHTTP/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 success response
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>
- 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 success response
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.
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>
- 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 success response
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.
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
The SDKs used to call the InitiateMultipartUpload 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 |
|
Not Modified | 304 |
|
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 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 data that is protected. During the protection period, data in the bucket cannot be deleted or modified. |