全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

PUT Object Copy

最近更新时间:2024-07-25 16:55:30

描述

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

说明

  • 用户必须对源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:GetObjectks3:GetObjectTagging权限,对目标文件有ks3:PutObjectks3: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}

注意:

请求参数

该请求不使用请求参数。

请求头部

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

名称

描述

是否必选

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

  • 有效值:

  1. COPY(默认值):复制源Object的对象标签到目标Object。

  2. REPLACE:忽略源Object的对象标签,直接采用请求中指定的对象标签。

x-kss-acl

用于对象的预定义权限。

  • 类型:String

  • 默认值:private

  • 有效值:private public-read

  • 约束条件:无

x-kss-copy-source-if-match

条件复制参数,如果源ObjectETag(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

条件复制参数,如果源ObjectETag(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 Failed。

  • 类型:String

  • 默认值:None

若在拷贝过程中选择加密,KS3拷贝加密支持如下场景:(1)若源Object未加密,支持对目标Object加密;(2)若源Object加密,目标Object可以选择不加密;(3)目标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-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。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈