PUT Object - Copy

Last updated: 2019-12-16 17:54:51

PDF

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). 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 OK will be returned with the error as the response body. This means that the HTTP 200 OK response 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.

Version

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.

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 Headers

Common Headers

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

Special Headers

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

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:

Name Description Type Required
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 AES256
String Yes if encryption is needed

Request Body

The request body of this request is empty.

Response

Response Headers

Common Response Headers

This response uses common response headers. For more information on common response headers, see Common Response Headers.

Special Response Headers

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

Response Body

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:

Name Description Type
CopyObjectResult Returns the result of the copy operation 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 time in GMT time when the file is last modified String

Example

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>