PUT Object Copy

Last updated:2021-04-07 21:40:38

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:

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.

Header Description Required
x-kss-copy-source The combination of the source bucket and the object key of the source object, which is separated by a forward slash (/).
Type: String
Default value: None
Constraints: URL-encoding is required for the value Additionally, the source bucket must be valid, and you must have the read permissions on the source object.
Yes
x-kss-metadata-directive The directive that specifies whether the metadata is copied from the source object or replaced with the metadata specified in the request.
Valid values: COPY and REPLACE
Default value: COPY
COPY: indicates that the metadata is copied from the source object (including the user-defined x-kss-meta-* header and the standard HTTP request header). The information specified in the request does not take effect.
REPLACE: indicates that the metadata of the source object is replaced with the metadata specified in the request.
Notes: To modify only the metadata of the source object, you must set the key of the source object and the x-kss-copy-source to the same value. Set this request header to REPLACE.
Note that if the source object has multiple pieces of metadata, except
Content-MD5, content-part-md5,
Content-Length, and server-side-encryption-customer-key-MD5, other metadata of the source object that requires no modification should also be added.
If you encrypt the source object, you must also specify the x-kss-service-side-encryption-* and x-kss-copy-source-server-side-encryption-* as the storage encryption.
No
x-kss-storage-class The storage class to store newly created objects.
Type: String
Default value: None
Valid values: STANDARD, STANDARD_IA, and ARCHIVE
For more information, see Introduction of Storage Class.
Notes:
1. Assume that x-kss-storage-class is not specified. If the bucket is of the Archive storage class, the object is of the Archive storage class by default.
2. If the storage class of the source object is ARCHIVE, you must restore the object before you modify its storage class.
No
x-kss-tagging The tag to be added to the desired object. You can set multiple tags. Example: TagA=A&TagB=B.
Notes: URL-encoding is required for the key-value pair of each tag. If a key-value pair does not contain an equal sign (=), the value is considered an empty string.
No
x-kss-tagging-directive The directive that specifies whether the object tag is copied from the source object or replaced with the tag provided in the request.
Default value: COPY
Valid values:
1. COPY: indicates that the object tag is copied from the source object.
2. REPLACE: indicates that the tag of the source object is replaced with the tag specified in the request.
No
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.

Header Description Required
x-kss-server-side-encryption The encryption algorithm that is used. If the server-side encryption is used to store an object, this header will be included in the response.
Type: String
Yes

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

Header Description Required
x-kss-server-side-encryption-customer-key The base64-encoded encryption key for KS3 to use to encrypt data. The encryption key provided in this header must be the one that is used when the source object is created.
Type: String
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-algorithm and x-kss-server-side-encryption-customer-key-MD5.
Yes
x-kss-server-side-encryption-customer-algorithm The user-defined encryption algorithms. If the server-side encryption uses a user-defined encryption key, the response will include this header to check the decryption algorithms to use when decrypting the object.
Type: String
Valid value: AES256
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-key and x-kss-server-side-encryption-customer-key-MD5.
Yes
x-kss-server-side-encryption-customer-key-MD5 The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key.
Type: String
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-key and x-kss-server-side-encryption-customer-algorithm.
Yes
x-kss-copy-source-server-side-encryption-customer-key The base64-encoded encryption key for KS3 to use to decrypt data. The encryption key provided in this header must be the one that is used when the source object is created.
Type: String
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-algorithm and x-kss-server-side-encryption-customer-key-MD5.
Yes
x-kss-copy-source-server-side-encryption-customer-algorithm The operation that specifies the algorithm to decrypt the source object.
Type: String
Valid value: AES256
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-key and x-kss-server-side-encryption-customer-key-MD5.
Yes
x-kss-copy-source-server-side-encryption-customer-key-MD5 The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key.
Type: String
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-key and x-kss-server-side-encryption-customer-algorithm.
Yes
x-kss-tagging The tag to be added to the desired object. You can set multiple tags. Example: TagA=A&TagB=B.
Notes: URL-encoding is required for the key-value pair of each tag. If a key-value pair does not contain an equal sign (=), the value is considered an empty string.
No
x-kss-tagging-directive The directive that specifies whether the object tag is copied from the source object or replaced with the tag provided in the request.
Default value: COPY
Valid values:
1. COPY: indicates that the object tag is copied from the source object.
2. REPLACE: indicates that the tag of the source object is replaced with the tag specified in the request.
No

Request body

No request body is used.

Response

Response headers

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

Header Description
x-kss-server-side-encryption The encryption algorithm that is used. If the server-side encryption is used to store an object, this header will be included in the response.
Type: String
x-kss-server-side-encryption-customer-algorithm The user-defined encryption algorithms. If the server-side encryption uses a user-defined encryption key, the response will include this header to check the decryption algorithms to use when decrypting the object.
Type: String
Valid value: AES256
x-kss-server-side-encryption-customer-key-MD5 The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key.
Type: String

Response body

Parameter Description
CopyObjectResult Container for all response elements.
Type: Container
Parent node: None
ETag The entity tag of the new object. The entity tag reflects the changes to the contents of an object rather than its name or metadata.
Type: String
Parent node: CopyObjectResult
LastModified The last modification time of the object.
Type: String
Parent node: CopyObjectResult

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

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

  • Insufficient
  • Outdated
  • Unclear or awkward
  • Redundant or clumsy
  • Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈