PUT Object Copy

描述

此PUT接口可以拷贝一个在KS3中已经存在的 object 到某个 bucket。用户通过在请求中配置请求头部 x-kss-copy-source 来指定要拷贝的数据源。

PUT Object Copy接口能拷贝的源文件大小不能超过5GB，超过5GB时请使用Upload Part Copy接口 进行分块拷贝。

PUT Object Copy接口的目标桶和源桶必须在同一个region。

用户可以通过此接口实现对象移动、重命名、修改对象元数据和修改存储类型。

除非在此接口请求中显式指定存储类型，否则无论何种处理方式，目标对象均保持为目标bucket的默认存储类型。

PUT Object Copy接口支持跨账户复制，但用户需要具有拷贝对象的读权限，以及目标空间的写权限。

说明

• 用户必须对源bucket的Object具有读权限，对目标Bucket具有写权限。
• 默认会将源Object的对象标签复制到目标 Object，用户需要具有源文件ks3:GetObjectTagging 以及目标桶的写文件与写标签权限。
• 当源与目标为同一个桶且Key相同时，支持该接口实现对同一文件的修改存储类型与元数据的目的。
  object 可修改的元数据包括 ：
  1. HTTP Header头：Content-Type，Content-Length， Cache-Control， Content-Disposition， Content-Encoding，Expires
  2. 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	设置存储类型。 类型：String 默认值：None 有效值：STANDARD/STANDARD_IA/ARCHIVE 存储类型请参考存储类型介绍 。 说明： 1. 当不上传x-kss-storage-class时，如果Bucket是归档类型，Object自动为归档类型，如果Bucket是非归档类型，Object自动为标准类型。 2. 若原文件存储类型为ARCHIVE，必须为解冻状态才可修改成功。	否
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的对象标签，直接采用请求中指定的对象标签。	否

加密相关请求头部

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

若使用KS3 托管密钥的服务器端加密，则会返回以下响应头。

名称	描述	是否必选
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-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

特殊错误

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

示例

普通复制请求示例

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
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
Server: KS3

<CopyObjectResult>
<LastModified>2009-10-28T22:32:00</LastModified>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</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
Server: KS3

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

错误码

错误码	HTTP状态码	描述
ObjectAlreayExists	400	要复制的目标存储中已经存在同名Key。
AlgorithmInvalidForS3	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。