更新时间:2024-01-02 GMT+08:00

拷贝段

功能介绍

多段上传任务创建后,用户可以通过指定多段上传任务号,为特定的任务上传段。添加段的方式还包括调用段拷贝接口。允许客户将已上传对象的一部分或全部拷贝为段。

该操作支持服务端加密功能。

拷贝段的结果不能仅根据HTTP返回头域中的status_code来判断请求是否成功,头域中status_code返回200时表示服务端已经收到请求,且开始处理拷贝段请求。拷贝是否成功会在响应消息的body中,只有body体中有ETag标签才表示成功,否则表示拷贝失败。

将源对象object拷贝为一个段part1,如果在拷贝操作之前part1已经存在,拷贝操作执行之后老段数据part1会被新拷贝的段数据覆盖。拷贝成功后,只能列举到最新的段part1,老段数据将会被删除。因此在使用拷贝段接口时请确保目标段不存在或者已无价值,避免因拷贝段导致数据误删除。拷贝过程中源对象object无任何变化。

冷存储对象

如果源对象是冷存储对象,需要判断源对象的恢复状态,只有当源对象处于已恢复状态时,才能拷贝成功。源对象未恢复或者正在恢复时,会拷贝失败,返回错误403 Forbidden。异常描述为:

ErrorCode: InvalidObjectState

ErrorMessage: Operation is not valid for the source object's storage class

请求消息样式

PUT /ObjectName?partNumber=partNum&uploadId=UploadID HTTP/1.1 
Host: bucketname.obs.region.example.com
Date: date
x-obs-copy-source: sourceobject
x-obs-copy-source-range:bytes=start-end
Authorization: authorization
Content-Length: length

请求消息参数

拷贝段需要在参数中指定目标段的段号和多段上传任务号,参数的具体意义如表1所示。

表1 请求消息参数

参数名称

描述

是否必选

partNumber

上传段的段号。

类型:Integer

uploadId

多段上传任务Id。

类型:String

请求消息头

该请求的除了使用公共消息头外,还使用了两个扩展的消息头。公共消息头如表3所示。

表2 请求消息头

消息头名称

描述

是否必选

x-obs-copy-source

拷贝的源对象。

类型:String

x-obs-copy-source-range

源对象中待拷贝的段的字节范围(start - end),start为段起始字节,end为段结束字节。

类型:Integer

x-obs-server-side-encryption-customer-algorithm

SSE-C方式下使用该头域,该头域表示加密目标段使用的算法。

类型:String

示例:x-obs-server-side-encryption-customer-algorithm:AES256

约束:需要和x-obs-server-side-encryption-customer-key, x-obs-server-side-encryption-customer-key-MD5一起使用。

否。当使用SSE-C方式时,必选,需要与初始化上传段任务使用相同的算法。

x-obs-server-side-encryption-customer-key

SSE-C方式下使用该头域,该头域表示加密目标段使用的密钥。该密钥用于加密对象。

类型:String

示例:x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

约束:该头域由256-bit的密钥经过base64-encoded得到,需要和x-obs-server-side-encryption-customer-algorithm,x-obs-server-side-encryption-customer-key-MD5一起使用。

否。当使用SSE-C方式时,必选,需要与初始化上传段任务使用相同的密钥。

x-obs-server-side-encryption-customer-key-MD5

SSE-C方式下使用该头域,该头域表示加密目标段使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。

类型:String

示例:x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

约束:该头域由密钥的128-bit MD5值经过base64-encoded得到,需要和x-obs-server-side-encryption-customer-algorithm,x-obs-server-side-encryption-customer-key一起使用。

否。当使用SSE-C方式时,必选,需要与初始化上传段任务使用相同的MD5值。

x-obs-copy-source-server-side-encryption-customer-algorithm

SSE-C方式下使用该头域,该头域表示源对象使用的算法。

类型:String

示例:x-obs-copy-source-server-side-encryption-customer-algorithm:AES256

约束:需要和x-obs-copy-source-server-side-encryption-customer-key,x-obs-copy-source-server-side-encryption-customer-key-MD5一起使用。

否。当拷贝源对象使用SSE-C方式时,必选。

x-obs-copy-source-server-side-encryption-customer-key

SSE-C方式下使用该头域,该头域表示源对象使用的密钥。用于解密源对象。

类型:String

示例:x-obs-copy-source-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

约束:该头域由256-bit的密钥经过base64-encoded得到,需要和x-obs-copy-source-server-side-encryption-customer-algorithm,x-obs-copy-source-server-side-encryption-customer-key-MD5一起使用。

否。当拷贝源对象使用SSE-C方式时,必选。

x-obs-copy-source-server-side-encryption-customer-key-MD5

SSE-C方式下使用该头域,该头域表示源对象使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。

类型:String

示例:x-obs-copy-source-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

约束:该头域由密钥的128-bit MD5值经过base64-encoded得到,需要和x-obs-copy-source-server-side-encryption-customer-algorithm,x-obs-copy-source-server-side-encryption-customer-key一起使用。

否。当拷贝源对象使用SSE-C方式时,必选。

x-obs-copy-source-if-match

只有当源对象的Etag与此参数指定的值相等时才进行复制对象操作,否则返回412(前置条件不满足)。

类型:String

示例:x-obs-copy-source-if-match: etag

约束条件:此参数可与x-obs-copy-source-if-unmodified-since一起使用,但不能与其它条件复制参数一起使用。

x-obs-copy-source-if-none-match

只有当源对象的Etag与此参数指定的值不相等时才进行复制对象操作,否则返回412(前置条件不满足)。

类型:String

示例:x-obs-copy-source-if-none-match: etag

约束条件:此参数可与x-obs-copy-source-if-modified-since一起使用,但不能与其它条件复制参数一起使用。

x-obs-copy-source-if-unmodified-since

只有当源对象在此参数指定的时间之后没有修改过才进行复制对象操作,否则返回412(前置条件不满足),此参数可与x-obs-copy-source-if-match一起使用,但不能与其它条件复制参数一起使用。

类型:String

格式:符合http://www.ietf.org/rfc/rfc2616.txt规定格式的HTTP时间字符串。

  1. EEE, dd MMM yyyy HH:mm:ss z
  2. EEEE, dd-MMM-yy HH:mm:ss z
  3. EEE MMM dd HH:mm:ss yyyy

对应示例:

  1. x-obs-copy-source-if-unmodified-since: Sun, 06 Nov 1994 08:49:37 GMT
  2. x-obs-copy-source-if-unmodified-since: Sunday, 06-Nov-94 08:49:37 GMT
  3. x-obs-copy-source-if-unmodified-since: Sun Nov 6 08:49:37 1994

约束条件:此参数指定的时间不能晚于当前的服务器时间(GMT时间),否则参数不生效。

x-obs-copy-source-if-modified-since

只有当源对象在此参数指定的时间之后修改过才进行复制对象操作,否则返回412(前置条件不满足),此参数可与x-obs-copy-source-if-none-match一起使用,但不能与其它条件复制参数一起使用。

类型:String

格式:符合http://www.ietf.org/rfc/rfc2616.txt规定格式的HTTP时间字符串。

  1. EEE, dd MMM yyyy HH:mm:ss z
  2. EEEE, dd-MMM-yy HH:mm:ss z
  3. EEE MMM dd HH:mm:ss yyyy

对应示例:

  1. x-obs-copy-source-if-unmodified-since: Sun, 06 Nov 1994 08:49:37 GMT
  2. x-obs-copy-source-if-unmodified-since: Sunday, 06-Nov-94 08:49:37 GMT
  3. x-obs-copy-source-if-unmodified-since: Sun Nov 6 08:49:37 1994

约束条件:此参数指定的时间不能晚于当前的服务器时间(GMT时间),否则参数不生效。

请求消息元素

该请求消息中不使用消息元素。

响应消息样式

HTTP/1.1 status_code
Date: date

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<CopyPartResult xmlns="http://obs.region.example.com/doc/2015-06-30/"> 
    <LastModified>modifiedDate</LastModified>  
    <ETag>etag</ETag> 
</CopyPartResult>

响应消息头

该请求的响应消息使用公共消息头,具体请参考表1

表3 附加响应消息头

消息头名称

描述

x-obs-server-side-encryption

如果服务端加密是SSE-KMS方式,响应包含该头域。

类型:String

示例:x-obs-server-side-encryption:kms

x-obs-server-side-encryption-kms-key-id

如果服务端加密是SSE-KMS方式,响应包含该头域,该头域表示主密钥。

类型:String

格式为: regionID:domainID(租户ID):key/key_id

其中regionID是使用密钥所属region的ID;domainID是使用密钥所属租户的租户ID;key_id是本次加密使用的密钥ID。

示例: x-obs-server-side-encryption-kms-key-id:region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-obs-server-side-encryption-customer-algorithm

如果服务端加密是SSE-C方式,响应包含该头域,该头域表示加密使用的算法。

类型:String

示例:x-obs-server-side-encryption-customer-algorithm:AES256

x-obs-server-side-encryption-customer-key-MD5

如果服务端加密是SSE-C方式,响应包含该头域,该头域表示加密使用的密钥的MD5值。

类型:String

示例:x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

响应消息元素

该请求的响应消息使用消息元素来返回段拷贝的结果,元素的意义如表4所示。

表4 响应消息元素

元素名称

描述

LastModified

对象上次修改时间。

类型:String

ETag

目标段的ETag值,是段内容的唯一标识,用于段合并时校验数据一致性。

类型:String

错误响应消息

  1. 如果AccessKey或签名无效,OBS返回403 Forbidden,错误码为AccessDenied。
  2. 查询源桶或目的桶是否存在,如果不存在,OBS返回404 Not Found,错误码为NoSuchBucket。
  3. 如果源对象不存在,OBS返回404 Not Found,错误码为NoSuchKey。
  4. 如果用户对指定对象没有读权限,OBS返回403 Forbidden,错误码为AccessDenied。
  5. 如果用户对目的桶没有写权限,OBS返回403 Forbidden,错误码为AccessDenied。
  6. 查询指定的任务不存在,OBS返回404 Not Found,错误码为NoSuchUpload。
  7. 如果用户不是多段上传任务的发起者,OBS返回403 Forbidden,错误码为AccessDenied。
  8. 当拷贝的单段超过5G时,OBS返回400 Bad Request。
  9. 如果段序号超过范围[1,10000],OBS返回错误400 Bad Request。

其他错误已包含在表2中。

请求示例

PUT /tobject02?partNumber=2&uploadId=00000163D40171ED8DF4050919BD02B8 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 05:16:32 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:dSnpnNpawDSsLg/xXxaqFzrAmMw=
x-obs-copy-source: /destbucket/object01

响应示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D40ABBD20405D30B0542
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCTIJpD2efLy5o8sTTComwBb2He0j11Ne
Content-Type: application/xml
Date: WED, 01 Jul 2015 05:16:32 GMT
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CopyPartResult xmlns="http://obs.example.com/doc/2015-06-30/">
  <LastModified>2015-07-01T05:16:32.344Z</LastModified>
  <ETag>"3b46eaf02d3b6b1206078bb86a7b7013"</ETag>
</CopyPartResult>