PUT Object - Copy
Last updated: 2019-12-16 17:54:51
This API (PUT Object - Copy) is used to create a copy of an object that already exists in COS, i.e., copying an object from the source path (object key) to the destination path (object key). The recommended object size is from 1 MB to 5 GB. For objects over 5 GB, please use the Upload Part - Copy API. You can modify the object metadata and access control list (ACL) during the copying process.
You can use this API to move, rename, and copy an object and modify its metadata.
- For cross-account copy, you need to set the access permissions of the source object to Public Read or authorize the destination account to read the source object. This is not required for intra-account copy.
- An error may be returned when COS receives the copy request or is copying the object. If an error occurs before the copy operation begins, a standard error response will be returned. If an error occurs during the execution of the copy operation,
HTTP 200 OKwill be returned with the error as the response body. This means that the
HTTP 200 OKresponse can mean both success and error. When you use this API, please pay attention to the content of the response body to determine if the copy request is successful and deal with the result accordingly.
If versioning is enabled for the destination bucket, by default COS will generate a unique version ID for the object copy, which will be different from the version ID of the source object and will be returned in the
x-cos-version-id response header.
If versioning is suspended or not enabled for the destination bucket, the version ID generated by COS will always be `null.
PUT /<ObjectKey> HTTP/1.1 Host: <BucketName-APPID>.cos.<Region>.myqcloud.com Date: GMT Date Authorization: Auth String x-cos-copy-source: <BucketName-APPID>.cos.<Region>.myqcloud.com/filepath
Authorization: Auth String (see Request Signature for details).
The implementation of this operation uses common request headers. For more information on common request headers, see Common Request Headers.
|x-cos-copy-source||URL path to the source file. You can specify a historical version using the `versionid` subresource||string||Yes|
|x-cos-metadata-directive||Whether to copy the metadata of the source file. Enumerated values: `Copy`, copy the metadata of the source file; `Replaced`, modify the metadata according to the header information in the current request. Default value: `Copy`. If the destination path is the same as the source path, which means you want to modify the object metadata, you must specify this header as `Replaced`||string||No|
|x-cos-copy-source-If-Modified-Since||If the object is modified after the specified time, the operation will be performed; otherwise, `412` will be returned. This header can be used together with `x-cos-copy-source-If-None-Match`. If it is used together with other conditions, a conflict will be returned||string||No|
|x-cos-copy-source-If-Unmodified-Since||If the object is not modified after the specified time, the operation will be performed; otherwise, `412` will be returned. This header can be used together with `x-cos-copy-source-If-Match`. If it is used together with other conditions, a conflict will be returned||string||No|
|x-cos-copy-source-If-Match||If the `Etag` of the object is the same as the specified one, the operation will be performed; otherwise, `412` will be returned. This header can be used together with `x-cos-copy-source-If-Unmodified-Since`. If it is used together with other conditions, a conflict will be returned||string||No|
|x-cos-copy-source-If-None-Match||If the `Etag` of the object is different from the specified one, the operation will be performed; otherwise, `412` will be returned. This header can be used together with `x-cos-copy-source-If-Modified-Since`. If it is used together with other conditions, a conflict will be returned||string||No|
|x-cos-storage-class||Sets the storage class of the object. Enumerated values: `STANDARD`, `STANDARD_IA`. Default value: `STANDARD`||string||No|
|x-cos-acl||Defines the ACL attribute of the object. Valid values: `private`, `public-read`. Default value: `private`||string||No|
|x-cos-grant-read||Grants the grantee Read access. Format: `x-cos-grant-read: id="[OwnerUin]"`||string||No|
|x-cos-grant-write||Grants the grantee Write access. Format: `x-cos-grant-write: id="[OwnerUin]"`||string||No|
|x-cos-grant-full-control||Grants the grantee full permission. Format: `x-cos-grant-full-control: id="[OwnerUin]"`||string||No|
|x-cos-meta-*||Suffix and information of the user-defined header, which will be returned as the object metadata; maximum size: 2 KB.
Note: user-defined header information can contain underscores, whereas user-defined header suffixes cannot
Server-side encryption-related headers
This request operation specifies the data encryption policy for COS data storage. COS will automatically encrypt the data written to the IDC and automatically decrypt it when you retrieve it. Currently, AES-256 encryption with the COS master key is supported. If you want to enable server-side encryption for your data, please pass in the following header:
|x-cos-server-side-encryption||Specifies how the server-side encryption is enabled for the object.
For encryption with the COS master key, pass in
|String||Yes if encryption is needed|
The request body of this request is empty.
Common Response Headers
This response uses common response headers. For more information on common response headers, see Common Response Headers.
Special Response Headers
|x-cos-version-id||Version of the object copy in the destination bucket. This parameter will be returned only if versioning is enabled or enabled and then suspended for the bucket||String|
|x-cos-server-side-encryption||If the object is stored with COS-managed server-side encryption, the response will contain this header and the value of the encryption algorithm used (AES256)||String|
This response body returns application/xml data. The following contains all the node data:
<CopyObjectResult> <ETag>"ba82b57cfdfda8bd17ad4e5879ebb4fe"</ETag> <LastModified>2017-08-04T02:41:45</LastModified> </CopyObjectResult>
Please find the details below:
|CopyObjectResult||Returns the result of the copy operation||String|
|ETag||Returns the MD5 checksum of the file. The value of
|LastModified||Returns the time in GMT time when the file is last modified||String|
PUT /exampleobject HTTP/1.1 Host: destinationbucket-1250000000.cos.ap-beijing.myqcloud.com Date: Fri, 04 Aug 2017 02:41:45 GMT Connection: keep-alive Accept-Encoding: gzip, deflate Accept: */* User-Agent: python-requests/2.12.4 Authorization: q-sign-algorithm=sha1&q-ak=AKID15IsskiBQKTZbAo6WhgcBqVls9SmuG00&q-sign-time=1480932292;1981012292&q-key-time=1480932292;1981012292&q-url-param-list=&q-header-list=host&q-signature=eacefe8e2a0dc8a18741d9a29707b1dfa5aa47cc x-cos-copy-source: sourcebucket-1250000001.cos.ap-beijing.myqcloud.com/picture.jpg Content-Length: 0
HTTP/1.1 200 OK Content-Type: application/xml Content-Length: 133 Connection: keep-alive Date: Fri, 04 Aug 2017 02:41:45 GMT Server: tencent-cos x-cos-request-id: NTk4M2RlZTlfZDRiMDM1MGFfYTA1ZV8xMzNlYw== <CopyObjectResult> <ETag>"ba82b57cfdfda8bd17ad4e5879ebb4fe"</ETag> <LastModified>2017-08-04T02:41:45</LastModified> </CopyObjectResult>