PUT Object Copy

Description

You can call this operation to copy an object that is already stored in Kingsoft Cloud Standard Storage Service (KS3) to a bucket. You can specify the data source to be copied by configuring the request header x-kss-copy-source.

You can create a copy of an object up to 1 GB in size. For an object greater than 1 GB, you must call the Upload Part Copy operation to copy the object in multiple parts.

This operation does not support cross-region copies.

You can call this operation to move and rename objects, and modify the metadata and storage classes of objects.

By default, KS3 uses the storage class that is specified in the desired bucket to store the newly created object. You can specify a different storage class in the request. For more information, see PUT Bucket.

This operation supports cross-account copies. However, you must have the read permissions on the source object and write permission on the desired bucket.

Request

Request syntax

PUT /{destinationObject} HTTP/1.1
Host: {destinationBucket}.{endpoint}
x-kss-copy-source: {/source_bucket/sourceObject}
Authorization: {SignatureValue}
Date: {date}

References:

• Endpoints and regions
• Request signature

Request parameters

No request parameter is used.

Request headers

This operation supports all common request headers and the request headers that are described in the following table. For more information, see Common request headers.

Request header encryption

Note: The copy of an unencrypted object does not support encryption. The desired object must use the same encryption method as the source object. If the desired object adopts key encryption protection provided by the client, the desired object must use the same key encryption.

Configure the following request header to enable default encryption.

Configure the following request headers to enable key encryption as specified in the request.

Request body

No request body is used.

Response

Response headers

This operation supports all common response headers. For more information, see Common response headers.

Response body

Operation-specific errors

This operation does not return operation-specific errors.

Examples

Sample request

PUT /rename-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-copy-source: /SourceBucket/SourceObjectKey
x-kss-tagging-directive:REPLACE
x-kss-tagging:TagA=A&TagB=B//URLencode required
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: Tengine

Sample request: Modify the metadata of an object

PUT /modifymetakey HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-copy-source: /ks3-example/modifymetakey
x-kss-metadata-directive:REPLACE
x-kss-meta-youmetakey:yourmetavalue
Authorization: authorization string

Sample response: Modify the metadata of an object

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: Tengine

<CopyObjectResult>
<LastModified>2009-10-28T22:32:00</LastModified>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

Sample request: Modify the storage class of an object

PUT /yourobjectkey HTTP/1.1
Host: yourbucket.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-copy-source: /yourbucket/yourobjectkey
x-kss-storage-class:STANDARD_IA
Authorization: authorization string

Sample response: Modify the storage class of an object

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: Tengine

<CopyObjectResult>
<LastModified>2009-10-28T22:32:00</LastModified>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

Usage notes

• You must have the read permissions on the object in the source bucket and the write permissions on the desired bucket.
• If the key of the object to be copied already exists in the desired bucket, an 400 error is returned.
• By default, the desired object remains the tag of the source object. To modify the object tag, you must have the ks3:GetObjectTagging permission on the source object. You must also have the permissions to write objects in the desired bucket and add tags to these objects.
• This operation supports you to modify the storage class and metadata of the same object if the source object and the desired object are with the same key in the same bucket You can edit the metadata of the object by modifying the following elements:
  1. HTTP header: Content-Type, Content-Length, Cache-Control, Content-Disposition, Content-Encoding, Expires
  2. x-kss-meta-
• To copy an object with a tag, you must have the ks3:GetObject and ks3:GetObjectTagging permissions on the source object, and the ks3:PutObject and ks3:PutObjectTagging permissions on the desired objects. However, if you set the x-kss-tagging-directive to REPLACE and the new tag is empty, you only need the ks3:PutObject permission on the desired object.
• To replace the tag of source object, you must set x-kss-tagging-directive to REPLACE and ensure that the value set to x-kss-tagging is valid. This way, the desired object will use the tag provided in x-kss-tagging. Make sure that both x-kss-tagging-directive and x-kss-tagging are specified.