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

用户必须对源Bucket的Object具有ks3:GetObject权限，对目标Bucket具有ks3:PutObject权限。
拷贝的源文件大小不能超过5GB，超过5GB时请使用Upload Part Copy接口进行分块拷贝。
目标桶和源桶必须在同一个Region。
支持跨账户复制，但用户需要具有拷贝对象的ks3:GetObject权限，以及目标空间的ks3:PutObject权限。
用户可以指定Object的存储类型，如果不指定，目标对象默认跟随目标Bucket的默认存储类型。
用户可以通过此接口实现对象移动、重命名、修改对象元数据和修改存储类型。
当源与目标为同一个桶且Key相同时，支持该接口实现对同一文件的修改存储类型与元数据的目的。
Object可修改的元数据包括：
- HTTP Header头：Content-Type，Content-Length， Cache-Control， Content-Disposition， Content-Encoding，Expires
- x-kss-meta-
如果复制的源文件带有标签，则需要对源文件有ks3:GetObject与ks3:GetObjectTagging权限，对目标文件有ks3:PutObject与ks3:PutObjectTagging权限。但是如果指定x-kss-tagging-directive为REPLACE且新指定Tag为空，则对目标文件只需有ks3:PutObject权限即可。
如果需要覆盖源文件对象标签，则x-kss-tagging-directive需设置为Replace且指定x-kss-tagging合法，这时将采用x-kss-tagging指定的对象标签作为目标对象的新标签。若仅x-kss-tagging时无法完成重置目标对象的标签的覆盖。

请求

语法

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

注意：
endpoint与Region对应关系
SignatureValue签名算法

请求参数

该请求不使用请求参数。

请求头部

该接口可以使用所有常用请求头部，此外，也可以使用下表所列请求头部。获取更多信息，请点击常用请求头部。

名称	描述	是否必选
x-kss-copy-source	指定拷贝的源地址。格式为空间名称与对象的`Object Key`名称组合，通过斜杠分隔(’/’)。类型: String 默认值: None 约束条件：其值必须使用URL编码。另外，空间名称必须有效，同时用户需要拥有对拷贝对象的读权限。	是
x-kss-meta-	用户元数据前缀标识。若某个头部前缀为x-kss-meta-，则为用户自定义元数据。类型: String 默认值: None 约束条件：无	否
x-kss-metadata-directive	指定是否拷贝源Object的元数据信息，有效值：COPY, REPLACE。如果此选项不指定，默认为COPY。 COPY：目标Object的元信息会从源Object拷贝（包括用户自定义x-kss-meta-``头和标准HTTP Header头），请求中新指定的信息不生效。 REPLACE：忽略源Object的元信息，目标Object直接采用请求中指定的元信息。说明： 1. 如果仅需要修改Object元信息而不拷贝，需将请求的Object Key和x-kss-copy-source设置为相同并且设置本选项为REPLACE，则会修改为请求中新指定的信息。 2. 如果原来Object的元信息有多个，则除Content-MD5， content-part-md5，Content-Length，server-side-encryption-customer-key-MD5之外，Object其他无需修改的元信息也需要加上。 3. 如果源Object采用了加密存储，则同时需要指定x-kss-service-side-encryption-``和x-kss-copy-source-server-side-encryption-`*`为源文件加密信息。	否
x-kss-storage-class	设置存储类型。有关存储类型的详细介绍请参见文档：存储类型介绍。 1. 当不上传x-kss-storage-class时，如果Bucket是归档类型，Object自动为归档类型，如果Bucket是非归档类型，Object自动为标准类型。 2. 若原文件存储类型为ARCHIVE，必须为解冻状态才可修改成功。类型：String 默认值：None 有效值：STANDARD/STANDARD_IA/ARCHIVE	否
x-kss-tagging	指定目标Object对象标签，可同时设置多个标签，如：TagA=A&TagB=B。说明Key和Value需要先进行URL编码，如果某项没有“=”，则看作Value为空字符串。详情请见对象标签。	否
x-kss-tagging-directive	指定如何设置目标Object的对象标签。默认值：COPY 有效值： COPY（默认值）：复制源Object的对象标签到目标Object。 REPLACE：忽略源Object的对象标签，直接采用请求中指定的对象标签。	否
x-kss-acl	用于对象的预定义权限。类型：String 默认值：private 有效值：`private` `public-read` 约束条件：无	否
x-kss-copy-source-if-match	条件复制参数，如果源`Object` 的`ETag(entity tag)`与指定值一致，则拷贝成功。否则，返回412 Precondition Failed。注意：此参数可搭配x-kss-copy-source-if-unmodified-since一起使用，x-kss-copy-source-if-match优先级高类型：String 默认值：None	否
x-kss-copy-source-if-none-match	条件复制参数，如果源`Object`的`ETag(entity tag)`与指定值不一致，则拷贝成功。否则，返回412 Precondition Failed。注意：此参数可搭配x-kss-copy-source-if-modified-since一起使用，x-kss-copy-source-if-none-match优先级高类型：String 默认值：None	否
x-kss-copy-source-if-modified-since	条件复制参数，如果源`Object`在指定时间后被修改，则拷贝成功。否则，返回412 Precondition Failed 类型：String 默认值：None	否
x-kss-copy-source-if-unmodified-since	条件复制参数，如果源`Object`在指定时间后没有被修改，则拷贝成功。否则，返回412 Precondition Faile 类型：String 默认值：None	否

加密相关请求头部

注意：如果源Object没有进行过加密，不支持对目标Object进行加密。且目标Object的加密方式要与源Object的加密方式一致，如果源Object是客户提供的密钥加密，目标Object应该使用同样的加密密钥。

若使用KS3托管密钥的服务器端加密，则需要使用以下请求头。

名称	描述	是否必选
x-kss-server-side-encryption	如果存储`Object`时使用了服务端加密，则响应会包含该头部，值为使用的加密算法。类型：String	是

名称

描述

是否必选

x-kss-server-side-encryption

如果存储Object时使用了服务端加密，则响应会包含该头部，值为使用的加密算法。

类型：String

是

若使用客户提供的加密密钥的服务器端加密，则需要使用以下请求头。

名称	描述	是否必选
x-kss-server-side-encryption-customer-key	由用户指定KS3加密时使用的 `base64-encoded` 加密秘钥。其值必须与源Object创建时使用的秘钥一致。类型：String 约束：需要和有效的 `x-kss-server-side-encryption-customer-algorithm`,`x-kss-server-side-encryption-customer-key-MD5` 同时使用。	是
x-kss-server-side-encryption-customer-algorithm	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。类型：String 有效值：AES256 约束：需要和有效的 `x-kss-server-side-encryption-customer-key`,`x-kss-server-side-encryption-customer-key-MD5` 同时使用。	是
x-kss-server-side-encryption-customer-key-MD5	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。类型：String 约束：需要和有效的 `x-kss-server-side-encryption-customer-key`,`x-kss-server-side-encryption-customer-algorithm` 同时使用。	是
x-kss-copy-source-server-side-encryption-customer-key	由用户指定KS3解密时使用的 `base64-encoded` 加密秘钥，其值必须与源Object创建时使用的秘钥一致。类型：String 约束：需要和有效的 `x-kss-server-side-encryption-customer-algorithm`,`x-kss-server-side-encryption-customer-key-MD5` 同时使用。	是
x-kss-copy-source-server-side-encryption-customer-algorithm	指定数据源对象解密使用的解密算法。类型：String 有效值：AES256 约束：需要和有效的 `x-kss-server-side-encryption-customer-key`,`x-kss-server-side-encryption-customer-key-MD5` 同时使用	是
x-kss-copy-source-server-side-encryption-customer-key-MD5	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。类型：String 约束：需要和有效的 `x-kss-server-side-encryption-customer-key`,`x-kss-server-side-encryption-customer-algorithm` 同时使用。	是
x-kss-tagging	指定Object的对象标签，可同时设置多个标签，如：TagA=A&TagB=B。说明 Key和Value需要先进行URL编码，如果某项没有“=”，则看作Value为空字符串。	否
x-kss-tagging-directive	指定如何设置目标Object的对象标签。默认值：Copy 有效值： 1. COPY（默认值）：复制源Object的对象标签到目标Object。 2. REPLACE：忽略源Object的对象标签，直接采用请求中指定的对象标签。	否

请求内容

该接口不使用请求内容。

响应

响应头部

该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。

名称	描述
x-kss-checksum-crc64ecma	Object的CRC64值，用于对象完整性校验。关于CRC64的计算标准，请参见：ECMA-182标准。类型：String
x-kss-server-side-encryption	如果存储`Object`时使用了服务端加密，则响应会包含该头部，值为使用的加密算法。类型：String
x-kss-server-side-encryption-customer-algorithm	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。类型：String 有效值：AES256
x-kss-server-side-encryption-customer-key-MD5	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息类型：String

响应内容

名称	描述
CopyObjectResult	响应内容的容器。类型: Container 父节点: 无
ETag	返回一个新对象的实体标签。影响因素为对象的内容，与对象名称或元数据无关。类型: String 父节点: CopyObjectResult
LastModified	返回最后被修改的时间日期。类型: String 父节点: CopyObjectResult
ChecksumCRC64ECMA	Object的CRC64值，用于对象完整性校验。关于CRC64的计算标准，请参见：ECMA-182标准。类型：String

特殊错误

该请求不返回任何特殊错误。

示例

普通复制请求示例

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
Authorization: authorization string

普通响应示例

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: keep-alive
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3

修改元数据请求示例

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

修改元数据响应示例

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: keep-alive
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3

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

修改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

修改Object存储类型响应示例

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: keep-alive
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3

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

错误码

错误码	HTTP状态码	描述
ObjectAlreayExists	400	要复制的目标存储中已经存在同名Key。
InvalidEncryptionAlgorithmError	400	x-kss-server-side-encryption请求头值不是AES256。
Md5NotMatchForOldMd5	400	x-kss-copy-source-server-side-encryption-customer-key-MD5不是x-kss-copy-source-server-side-encryption-customer-key的MD5值。
AlgorithmInvalidForCustomerKey	400	x-kss-server-side-encryption-customer-algorithm不是合法的AES256。

文档导读

上一篇：HEAD Object

下一篇：Append Object

纯净模式常规模式

纯净模式

点击可全屏预览文档内容