金山云-文档中心-PUT Object Copy

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

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

On this page

Previous:PUT Object ACL

Next:Initiate Multipart Upload

Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen