Description
The PUT Object - Copy is used to copy a file from the source path to the target path. The recommended file size is from 1 MB to 5 GB. For files larger than 5 GB, use the Upload - Copy API to perform the multipart upload. During the copy process, file meta-attributes and ACL can be modified.
Users can use this API to move files, rename files, modify file attributes, and create replicas.
Request
Request Example
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
x-cos-copy-source: <BucketName-APPID>.<Endpoint>/filepath
Note:
Authorization: Auth String (For details, please refer to Request Signature section).
Request Header
Common Headers
This request uses common request headers. For details, see Public Request Headers.
Non-common Headers
| Name | Description | Type | Required |
|---|---|---|---|
| x-cos-copy-source | Source file URL path. You can specify the historical version by using the versionid subresource. | string | Yes |
| x-cos-metadata-directive | Whether to copy the metadata of the source file, with enumerated values: Copy, Replaced, default value Copy. If marked as Copy, the metadata of the source file will be copied; if marked as Replaced, the metadata will be modified according to the Header information of this request. If the target path is the same as the source path, i.e., when the user attempts to modify the metadata, the mark must 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. Can be used together with x-cos-copy-source-If-None-Match, conflicts with other conditions when used in combination. | string | No |
| x-cos-copy-source-If-Unmodified-Since | If the object has not been modified after the specified time, the operation is performed; otherwise, 412 is returned. Can be used together with x-cos-copy-source-If-Match, conflicts with other conditions when used in combination. | string | No |
| x-cos-copy-source-If-Match | When the Object's Etag is consistent with the given one, the operation is performed, otherwise 412 is returned. Can be used together with x-cos-copy-source-If-Unmodified-Since, conflicts with other conditions when used in combination. | string | No |
| x-cos-copy-source-If-None-Match | When the Etag of the Object is inconsistent with the given one, the operation is performed, otherwise 412 is returned. Can be used together with x-cos-copy-source-If-Modified-Since, conflicts with other conditions when used in combination. | string | No |
| x-cos-acl | Define the ACL attributes of an object. Valid values: private, public-read; default value: private | string | No |
| x-cos-grant-read | Grants read access to the grantee. Format: x-cos-grant-read: id="[OwnerUin]" | string | No |
| x-cos-grant-write | Grants write permission to the grantee. Format: x-cos-grant-write: id="[OwnerUin]" | string | No |
| x-cos-grant-full-control | Grants full permission to the grantee. Format: x-cos-grant-full-control: id="[OwnerUin]" | string | No |
| x-cos-meta-* | Includes user-defined header suffix and user-defined header information, which will be returned as Object metadata, with a size limit of 2 KB. Note: User-defined header information supports underscores, but user-defined header suffix does not support underscores. |
string | No |
Request Body
The request body of this request is empty.
Response
Response Headers
Common Response Headers
This response contains common response headers. For details on common response headers, please refer to the Common Response Header document.
Response Body
The response body returns application/xml data. The following contains all the nodes:
<CopyObjectResult>
<ETag>"ba82b57cfdfda8bd17ad4e5879ebb4fe"</ETag>
<LastModified>2017-08-04T02:41:45</LastModified>
</CopyObjectResult>
The data are as follows:
| Name | Description | Type |
|---|---|---|
| CopyObjectResult | Returns the copy result information | String |
| ETag | Returns the MD5 algorithm check value of the file. The value of ETag can be used to check whether the object content is changed. | String |
| LastModified | Last modification time of the file, in GMT format. | String |
Practical Case
Request
PUT /exampleobject HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
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=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&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.<Endpoint>/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
x-cos-request-id: NTk4M2RlZTlfZDRiMDM1MGFfYTA1ZV8xMzNlYw==
<CopyObjectResult>
<ETag>"ba82b57cfdfda8bd17ad4e5879ebb4fe"</ETag>
<LastModified>2017-08-04T02:41:45</LastModified>
</CopyObjectResult>