复制对象
功能介绍
复制对象(Copy Object)特性用来为OBS上已经存在的对象创建一个副本。
当进行复制对象操作时,目标对象默认复制源对象的元数据;用户也可以将目标对象的元数据替换为本次请求中所带的元数据。新建的目标对象不会复制源对象的ACL信息,默认的新建对象的ACL是private,用户可以使用设置ACL的操作接口来重新设定新对象的ACL。
复制对象操作的请求需要通过头域携带拷贝的原桶和对象信息,不能携带消息实体。
该操作支持服务端加密功能。
目标对象大小范围是[0, 5GB],如果源对象大小超过5GB,只能使用拷贝段功能拷贝部分对象。
复制对象的结果不能仅根据HTTP返回头域中的status_code来判断请求是否成功,头域中status_code返回200时表示服务端已经收到请求,且开始处理复制对象请求。复制是否成功会在响应消息的body中,只有body体中有ETag标签才表示成功,否则表示复制失败。
多版本
默认情况下,x-obs-copy-source标识复制源对象的最新版本。如果源对象的最新版本是删除标记,则认为该对象已删除。要复制指定版本的对象,可以在x-obs-copy-source请求消息头中携带versionId参数。
如果目标对象的桶的多版本状态是开启的,系统为目标对象生成唯一的版本号(此版本号与源对象的版本号不同),并且会在响应报头x-obs-version-id返回该版本号。如果目标对象的桶的多版本状态是暂停的,则目标对象的版本号为null。
在桶没有开启多版本的情况下,将源对象object_A复制为目标对象object_B,如果在复制操作之前对象object_B已经存在,复制操作执行之后老对象object_B则会被新复制对象object_B覆盖,复制成功后,只能下载到新的对象object_B,老对象object_B将会被删除。因此在使用copy接口时请确保目标对象不存在或者已无价值,避免因copy导致数据误删除。复制过程中源对象object_A无任何变化。
WORM
如果桶的WORM开关是开启的,则可以为对象配置WORM。您可以通过携带头域x-obs-object-lock-mode和x-obs-object-lock-retain-until-date在复制对象的同时指定对象的保护策略,如果您不携带这些头域,但配置了桶级默认WORM策略,则复制的对象会自动应用默认策略。您还可以在复制后配置或修改对象级WORM保护策略。
在复制对象时,新建的目标对象与源对象的WORM保护状态相互独立,复制时不会复制源对象的WORM保护状态。在复制完成后,对源对象的WORM策略进行配置也不会影响新建的目标对象。
对象标签
可以通过携带头域x-obs-tagging-directive指定对象标签的复制策略。也可在对象复制完成后,重新设置对象标签。
复制对象时,如果需要复制源对象的标签,则需拥有源对象的GetObjectTagging权限;如果需要复制某一个版本源对象的标签,则需拥有源对象的GetObjectTagging+GetObjectVersionTagging权限。可通过对象ACL或桶策略授权。
复制对象时,如果需要设置目标对象的标签,则需拥有目标对象的PutObjectTagging权限;如果需要设置某一个版本目标对象的标签,则需拥有目标对象的PutObjectTagging+PutObjectVersionTagging权限。可通过桶ACL或桶策略授权。
归档或深度归档存储对象
如果源对象是归档或深度归档存储对象,需要判断源对象的恢复状态,只有当源对象处于已恢复状态时,才能复制成功。源对象未恢复或者正在恢复时,会复制失败,返回错误403 Forbidden。异常描述为:
ErrorCode: InvalidObjectState
ErrorMessage: Operation is not valid for the source object's storage class
请求消息样式
1 2 3 4 5 6 7 8 9 10 |
PUT /destinationObjectName HTTP/1.1 Host: bucketname.obs.cn-north-4.myhuaweicloud.com x-obs-copy-source: /sourceBucket/sourceObject x-obs-metadata-directive: metadata_directive x-obs-copy-source-if-match: etag x-obs-copy-source-if-none-match: etag x-obs-copy-source-if-unmodified-since: time_stamp x-obs-copy-source-if-modified-since: time_stamp Authorization: signature Date: date |
请求消息参数
该请求消息中不使用消息参数。
请求消息头
该消息可以带附加的消息头指定复制的信息,具体如表3所示。
消息头名称 |
消息头类型 |
是否必选 |
描述 |
---|---|---|---|
x-obs-acl |
String |
否 |
参数解释: 复制对象时,可以加上此消息头设置对象的权限控制策略,使用的策略为预定义的常用策略。 示例:x-obs-acl: acl 约束限制: 预定义策略为字符串形式。 取值范围:
各策略详细说明见ACL章节的“使用头域设置ACL”。 默认取值: private |
x-obs-grant-read |
String |
否 |
参数解释: 复制对象时,使用此头域授权读对象和获取对象元数据的权限给domain下的所有用户。 约束限制: 无 取值范围: 无 默认取值: 无 |
x-obs-grant-read-acp |
String |
否 |
参数解释: 复制对象时,使用此头域授权获取对象ACL的权限给domain下的所有用户。 约束限制: 无 取值范围: 无 默认取值: 无 |
x-obs-grant-write-acp |
String |
否 |
参数解释: 复制对象时,使用此头域授权写对象ACL的权限给domain下的所有用户。 约束限制: 无 取值范围: 无 默认取值: 无 |
x-obs-grant-full-control |
String |
否 |
参数解释: 复制对象时,使用此头域授权以下权限给domain下的所有用户: 读对象、获取对象元数据、获取对象ACL、写对象ACL的权限。 约束限制: 无 取值范围: 无 默认取值: 无 |
x-obs-copy-source |
String |
是 |
参数解释: 用来指定复制对象操作的源桶名以及源对象名。当源对象存在多个版本时,通过versionId参数指定版本源对象。 示例:x-obs-copy-source: /source_bucket/sourceObject 约束限制: 中文字符与%,需要进行URL编码。 取值范围: 无 默认取值: 无 |
x-obs-metadata-directive |
String |
否 |
参数解释: 此参数用来指定新对象的元数据是从源对象中复制,还是用请求中的元数据替换。 示例:x-obs-metadata-directive: metadata_directive 约束限制: 如果此参数的值不是COPY或REPLACE,则OBS立即返回400错误;如果用户进行修改元数据操作(源对象与目标对象相同),则此参数只能为REPLACE,否则此请求作为无效请求,服务端响应400。此参数不支持将加密的对象更改成非加密对象(源对象与目标对象相同)。如果用户使用此参数更改加密的对象,系统将返回400。 取值范围:
默认取值: COPY |
x-obs-copy-source-if-match |
String |
否 |
参数解释: 只有当源对象的Etag与此参数指定的值相等时才进行复制对象操作,否则返回412(前置条件不满足)。 示例:x-obs-copy-source-if-match: etag 约束限制: 此参数可与x-obs-copy-source-if-unmodified-since一起使用,但不能与其它条件复制参数一起使用。 取值范围: 无 默认取值: 无 |
x-obs-copy-source-if-none-match |
String |
否 |
参数解释: 只有当源对象的Etag与此参数指定的值不相等时才进行复制对象操作,否则返回412(前置条件不满足)。 示例:x-obs-copy-source-if-none-match: etag 约束限制: 此参数可与x-obs-copy-source-if-modified-since一起使用,但不能与其它条件复制参数一起使用。 取值范围: 无 默认取值: 无 |
x-obs-copy-source-if-unmodified-since |
String |
否 |
参数解释: 只有当源对象在此参数指定的时间之后没有修改过才进行复制对象操作,否则返回412(前置条件不满足)。 约束限制:
取值范围: 无 默认取值: 无 |
x-obs-copy-source-if-modified-since |
String |
否 |
参数解释: 只有当源对象在此参数指定的时间之后修改过才进行复制对象操作,否则返回412(前置条件不满足)。 约束限制:
取值范围: 无 默认取值: 无 |
x-obs-storage-class |
String |
否 |
参数解释: 复制对象时,可以加上此头域设置目的对象的存储类型。如果未设置此头域,则以目的对象所在桶的默认存储类型作为对象的存储类型。 示例:x-obs-storage-class: STANDARD 约束限制: 设置该参数的值时请注意大小写敏感。 取值范围:
默认取值: 默认继承桶的存储类型。 |
x-obs-persistent-headers |
String |
否 |
参数解释: 复制对象时,可以在HTTP请求中加入“x-obs-persistent-headers”消息头,用来加入一个或多个自定义的响应头,当用户获取目标对象或查询目标对象元数据时,加入的自定义响应头将会在返回消息的头域中出现。 约束限制:
取值范围: 无 默认取值: 无 |
x-obs-website-redirect-location |
String |
否 |
参数解释: 当桶设置了Website配置,可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的URL,OBS将这个值从头域中取出,保存在对象的元数据中。 约束限制: 必须以“/”、“http://”或“https://”开头,长度不超过2K。 取值范围: 无 默认取值: 无 |
x-obs-server-side-encryption |
String |
否。当使用SSE-KMS方式时,必选。 |
参数解释: 使用该头域表示服务端加密是SSE-KMS方式。目标对象使用SSE-KMS方式加密。 示例:x-obs-server-side-encryption: kms 约束限制: 无 取值范围:
默认取值: 无 |
x-obs-server-side-data-encryption |
String |
否 |
参数解释: 该头域表示目标对象使用的数据加密算法。 示例:x-obs-server-side-data-encryption:SM4 约束限制: 仅在SSE-KMS加密方式下使用该头域。 取值范围:
默认取值: 无 |
x-obs-server-side-encryption-kms-key-id |
String |
否 |
参数描述: 当加密方式为SSE-KMS且使用指定密钥加密时,需输入密钥ID。密钥ID获取方法请参见查看密钥。 约束限制: 当您设置了x-obs-server-side-encryption头域且赋值为“kms”,即选择kms加密方式时,才能使用该头域指定加密密钥。 默认取值: 当您选择使用kms加密方式,但未设置此头域时,默认的主密钥将会被使用。如果默认主密钥不存在,系统将默认创建并使用。 |
x-obs-server-side-encryption-customer-algorithm |
String |
否。当使用SSE-C方式时,必选。 |
参数解释: 该头域表示加密目标对象使用的算法。 示例:x-obs-server-side-encryption-customer-algorithm: AES256 约束限制:
取值范围: AES256 默认取值: 无 |
x-obs-server-side-encryption-customer-key |
String |
否。当使用SSE-C方式时,必选。 |
参数解释: 该头域表示加密目标对象使用的密钥。 示例:x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= 约束限制:
取值范围: 无 默认取值: 无 |
x-obs-server-side-encryption-customer-key-MD5 |
String |
否。当使用SSE-C方式时,必选。 |
参数解释: 该头域表示加密目标对象使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。 示例:x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== 约束限制:
取值范围: 密钥的MD5值。 默认取值: 无 |
x-obs-copy-source-server-side-encryption-customer-algorithm |
String |
否。当拷贝源对象使用SSE-C方式时,必选。 |
参数解释: 该头域表示解密源对象使用的算法。 示例:x-obs-copy-source-server-side-encryption-customer-algorithm: AES256 约束限制:
取值范围: AES256 默认取值: 无 |
x-obs-copy-source-server-side-encryption-customer-key |
String |
否。当拷贝源对象使用SSE-C方式时,必选。 |
参数解释: 该头域表示解密源对象使用的密钥。 示例:x-obs-copy-source-server-side-encryption-customer-key: K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= 约束限制:
取值范围: 无 默认取值: 无 |
x-obs-copy-source-server-side-encryption-customer-key-MD5 |
String |
否。当拷贝源对象使用SSE-C方式时,必选。 |
参数解释: 该头域表示解密源对象使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。 示例:x-obs-copy-source-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== 约束限制:
取值范围: 密钥的MD5值。 默认取值: 无 |
success-action-redirect |
String |
否 |
参数解释: 用于指定当此次请求操作成功响应后的重定向的地址。
约束限制: 需要为URL格式,如http://domainname、https://domainname。 取值范围: URL 默认取值: 无 |
x-obs-tagging-directive |
String |
否 |
参数解释: 通过携带头域x-obs-tagging-directive指定对象标签的复制策略。不带该头域默认不复制。 示例:x-obs-tagging-directive:COPY 约束限制: 无 取值范围:
默认取值: REPLACE |
x-obs-object-lock-mode |
String |
否,携带x-obs-object-lock-retain-until-date头域时必带 |
参数解释: 要应用于此对象的WORM模式。 示例:x-obs-object-lock-mode:COMPLIANCE 约束限制: 该参数需要和x-obs-object-lock-retain-until-date一同使用。 取值范围: COMPLIANCE 默认取值: 无 |
x-obs-object-lock-retain-until-date |
String |
否,携带x-obs-object-lock-mode头域时必带 |
参数解释: 此对象的WORM策略过期的截止时间。 示例:x-obs-object-lock-retain-until-date:2015-07-01T04:11:15Z 约束限制:
取值范围: 需要大于当前时间。 默认取值: 无 |
x-obs-tagging |
String |
否 |
参数解释: 以键值对(Key-Value)的形式指定Object的标签信息,可同时设置多个标签。 示例:x-obs-tagging:TagA=A&TagB&TagC 约束限制:
取值范围: 无 默认取值: 无 |
其他消息头请参见表3章节。
请求消息元素
该请求在消息中不使用消息元素。
响应消息样式
1 2 3 4 5 6 7 8 9 10 |
HTTP/1.1 status_code Content-Type: application/xml Date: date Content-Length: length <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> <LastModified>modifiedDate</LastModified> <ETag>etagValue</ETag> </CopyObjectResult> |
响应消息头
该请求的响应消息使用公共消息头,具体请参考表1。
除公共响应消息头之外,还可能使用如下表2中的消息头。
消息头名称 |
消息头类型 |
描述 |
---|---|---|
x-obs-copy-source-version-id |
String |
参数解释: 源对象的版本号。 约束限制: 无 取值范围: 无 默认取值: 无 |
x-obs-version-id |
String |
参数解释: 目标对象的版本号。 约束限制: 无 取值范围: 无 默认取值: 无 |
x-obs-server-side-encryption |
String |
参数解释: 该头域表示服务端的加密方式。 示例:x-obs-server-side-encryption: kms 约束限制: 如果服务端加密是SSE-KMS方式,响应包含该头域。 取值范围:
默认取值: 无 |
x-obs-server-side-encryption-kms-key-id |
String |
参数描述: 当加密方式为SSE-KMS且使用指定密钥加密时,需输入密钥ID。密钥ID获取方法请参见查看密钥。 约束限制: 当您设置了x-obs-server-side-encryption头域且赋值为“kms”,即选择kms加密方式时,才能使用该头域指定加密密钥。 默认取值: 当您选择使用kms加密方式,但未设置此头域时,默认的主密钥将会被使用。如果默认主密钥不存在,系统将默认创建并使用。 |
x-obs-server-side-encryption-customer-algorithm |
String |
参数解释: 该头域表示加密使用的算法。 示例:x-obs-server-side-encryption-customer-algorithm: AES256 约束限制: 如果服务端加密是SSE-C方式,响应包含该头域。 取值范围: AES256 默认取值: 无 |
x-obs-server-side-encryption-customer-key-MD5 |
String |
参数解释: 该头域表示加密使用的密钥的MD5值。 示例:x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== 约束限制: 如果服务端加密是SSE-C方式,响应包含该头域。 取值范围: 密钥ID MD5的base64值。 默认取值: 无 |
x-obs-storage-class |
String |
参数解释: 对象的存储类型。 约束限制: 对象为非标准存储对象时,会返回此头域。 取值范围:
默认取值: 返回对象的存储类型。 |
响应消息元素
该请求的响应消息通过消息元素来返回复制结果,元素具体含义如表3所示。
元素名称 |
元素类型 |
描述 |
---|---|---|
CopyObjectResult |
XML |
参数解释: 复制对象结果的容器。 约束限制: 无 取值范围: 无 默认取值: 无 |
LastModified |
String |
参数解释: 对象最近一次被修改的时间(UTC时间)。 约束限制: 日期格式为ISO8601的格式。 例如:2018-01-01T00:00:00.000Z,表示最后一次修改时间为2018-01-01T00:00:00.000Z。 取值范围: 无 默认取值: 无 |
ETag |
String |
参数解释: 新对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识,可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A,下载对象时ETag为B,则说明对象内容发生了变化。 约束限制: 当对象是服务端加密的对象时,ETag值不是对象的MD5值。 取值范围: 长度为32的字符串。 默认取值: 无 |
错误响应消息
无特殊错误,所有错误已经包含在表2中。
请求示例:普通复制
普通对象拷贝,将桶bucket中的对象srcobject拷贝到桶examplebucket中destobject对象
1 2 3 4 5 6 7 |
PUT /destobject HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: WED, 01 Jul 2015 04:19:21 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:2rZR+iaH8xUewvUKuicLhLHpNoU= x-obs-copy-source: /bucket/srcobject |
响应示例:普通复制
1 2 3 4 5 6 7 8 9 10 11 12 |
HTTP/1.1 200 OK Server: OBS x-obs-request-id: 001B21A61C6C00000134031BE8005293 x-obs-id-2: MDAxQjIxQTYxQzZDMDAwMDAxMzQwMzFCRTgwMDUyOTNBQUFBQUFBQWJiYmJiYmJi Date: WED, 01 Jul 2015 04:19:21 GMT Content-Length: 249 <?xml version="1.0" encoding="utf-8"?> <CopyObjectResult xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> <LastModified>2015-07-01T00:48:07.706Z</LastModified> <ETag>"507e3fff69b69bf57d303e807448560b"</ETag> </CopyObjectResult> |
请求示例:复制多版本对象
拷贝一个多版本对象,将桶bucket中的版本号为AAABQ4uBLdLc0vycq3gAAAAEVURTRkha的对象srcobject拷贝到桶examplebucket中destobject对象
1 2 3 4 5 6 7 |
PUT /destobject HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: WED, 01 Jul 2015 04:20:29 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:4BLYv+1UxfRSHBMvrhVLDszxvcY= x-obs-copy-source: /bucket/srcobject?versionId=AAABQ4uBLdLc0vycq3gAAAAEVURTRkha |
响应示例:复制多版本对象
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
HTTP/1.1 200 OK Server: OBS x-obs-request-id: DCD2FC9CAB78000001438B8A9C898B79 x-obs-id-2: DB/qBZmbN6AIoX9mrrSNYdLxwvbO0tLR/l6/XKTT4NmZspzharwp5Z74ybAYVOgr Content-Type: application/xml x-obs-version-id: AAABQ4uKnOrc0vycq3gAAAAFVURTRkha x-obs-copy-source-version-id: AAABQ4uBLdLc0vycq3gAAAAEVURTRkha Date: WED, 01 Jul 2015 04:20:29 GMT Transfer-Encoding: chunked <?xml version="1.0" encoding="utf-8"?> <CopyObjectResult xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> <LastModified>2015-07-01T01:48:07.706Z</LastModified> <ETag>"507e3fff69b69bf57d303e807448560b"</ETag> </CopyObjectResult> |