PUT Object - Copy

Last updated: 2019-10-23 16:43:56

Description

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.

Version

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.

Request

Sample Request

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).

Request Header

Common Headers

The implementation of this request operation uses a common request header. For more information on common request headers, see Common Request Headers.

Special Headers

Name Description Type Required
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
string No

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:

Name Description Type Required
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

Request Body

The request body of this request is empty.

Response

Response Header

Common Response Headers

This response contains a common response header. For more information on common response headers, see Common Response Headers.

Special Response Headers

Name Description Type
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

Response Body

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:

Name Description Type
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

Samples

Request

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

Response

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>