PUT Object - Copy
Last updated: 2019-10-23 16:43:56
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). It is recommended that the object size be between 1 MB and 5 GB. For objects over 5 GB, please use the Upload Part - Copy API. Object metadata and access control list (ACL) can be modified during the copy process.
This API allows you to move, rename, and copy an object and modify its metadata.
- For cross-account copy, you need to set the access permission to the source object to public-read or authorize the destination account. 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 OK will still be returned with the error as the response body. This means that the HTTP 200 OK response can contain both success and error. When this API is used, the success or failure of the copy request should be further determined based on the content of the response body, so that the result can be processed correctly.
By default, versioning is enabled for the destination bucket, and COS will generate a unique version ID for the object copy, which is 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 request operation uses a common request header. For more information on common request headers, see Common Request Headers.
|x-cos-copy-source||Source file URL path. A previous version can be specified using the versionid sub-resource||string||Yes|
|x-cos-metadata-directive||Whether to copy the metadata of the source file. Enumerated values: Copy, Replaced. Default value: Copy. If the flag is Copy, the metadata will be copied; if the flag is Replaced, the metadata will be modified based on the header information in the current request. If the destination path is the same as the source path (i.e., when you want to modify the metadata), the flag has to be Replaced||string||No|
|x-cos-copy-source-If-Modified-Since||If the object is modified after the specified time, the operation is performed; otherwise, 412 is returned. This parameter can be used together with x-cos-copy-source-If-None-Match. If it is used together with other conditions, a conflict is returned||string||No|
|x-cos-copy-source-If-Unmodified-Since||If the object is not modified after the specified time, the operation is performed; otherwise, 412 is returned. This parameter can be used together with x-cos-copy-source-If-Match. If it is used together with other conditions, a conflict is returned||string||No|
|x-cos-copy-source-If-Match||If the Etag of the object is the same as the specified one, the operation is performed; otherwise, 412 is returned. This parameter can be used together with x-cos-copy-source-If-Unmodified-Since. If it is used together with other conditions, a conflict is returned||string||No|
|x-cos-copy-source-If-None-Match||If the Etag of the object is different from the specified one, the operation is performed; otherwise, 412 is returned. This parameter can be used together with x-cos-copy-source-If-Modified-Since. If it is used together with other conditions, a conflict is returned||string||No|
|x-cos-storage-class||This sets the storage class of the object. Enumerated values: STANDARD, STANDARD_IA. Default value: STANDARD||string||No|
|x-cos-acl||It defines the ACL attribute of the object. Value range: private, public-read. Default value: private||string||No|
|x-cos-grant-read||Grants the grantee read permission in the format of x-cos-grant-read: id="[OwnerUin]"||string||No|
|x-cos-grant-write||Grants the grantee write permission in the format of x-cos-grant-write: id="[OwnerUin]"||string||No|
|x-cos-grant-full-control||Grants the grantee full permission in the format of x-cos-grant-full-control: id="[OwnerUin]"||string||No|
|x-cos-meta-*||This includes the suffix and information of the user-defined header, which will be returned as the object metadata of up to 2 KB.
Note: User-defined header information can contain underscores, but user-defined header suffixes cannot
Server-side encryption-related headers
This request operation specifies the data encryption policy during COS data upload. 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, upload the following header:
|x-cos-server-side-encryption||This specifies how the server-side encryption is enabled for the object.
For encryption with the COS master key, enter AES256
|String||Yes if encryption is needed|
The request body of this request is empty.
Common Response Headers
This response contains a common response header. For more information on common response headers, see Common Response Headers.
Special Response Headers
|x-cos-version-id||Version of the copied object 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 the values of this header and the encryption algorithm used (AES256)||String|
The return of this response body is application/xml data. Below is a sample containing all the node data:
<CopyObjectResult> <ETag>"ba82b57cfdfda8bd17ad4e5879ebb4fe"</ETag> <LastModified>2017-08-04T02:41:45</LastModified> </CopyObjectResult>
Detailed data is as shown below:
|CopyObjectResult||Returns the copy result information||String|
|ETag||Returns the MD5 checksum of the file. The value of ETag can be used to check whether the object content has changed||String|
|LastModified||Returns the last modified time of the file in GMT time||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>