文档首页/ 对象存储服务 OBS/ API参考/ API/ 对象操作/ 复制对象
更新时间：2024-09-29 GMT+08:00
查看PDF
分享

复制对象

功能介绍

复制对象（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策略进行配置也不会影响新建的目标对象。

归档或深度归档存储对象

如果源对象是归档或深度归档存储对象，需要判断源对象的恢复状态，只有当源对象处于已恢复状态时，才能复制成功。源对象未恢复或者正在恢复时，会复制失败，返回错误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.region.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所示。

表1 请求消息头

消息头名称

消息头类型

是否必选

描述

x-obs-acl

String

否

参数解释：

复制对象时，可以加上此消息头设置对象的权限控制策略，使用的策略为预定义的常用策略。

示例：x-obs-acl: acl

约束限制：

预定义策略为字符串形式。

取值范围：

  • private
  • public-read
  • public-read-write

各策略详细说明见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
  • REPLACE

默认取值：

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（前置条件不满足）。

约束限制：

  • 此参数指定的时间不能晚于当前的服务器时间（GMT时间），否则参数不生效。
  • 此参数可与x-obs-copy-source-if-match一起使用，但不能与其它条件复制参数一起使用
  • 格式：符合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

取值范围：

无

默认取值：

无

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

String

否

参数解释：

只有当源对象在此参数指定的时间之后修改过才进行复制对象操作，否则返回412（前置条件不满足）。

约束限制：

  • 此参数指定的时间不能晚于当前的服务器时间（GMT时间），否则参数不生效。
  • 此参数可与x-obs-copy-source-if-none-match一起使用，但不能与其它条件复制参数一起使用
  • 格式：符合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

取值范围：

无

默认取值：

无

x-obs-storage-class

String

否

参数解释：

复制对象时，可以加上此头域设置目的对象的存储类型。如果未设置此头域，则以目的对象所在桶的默认存储类型作为对象的存储类型。

示例：x-obs-storage-class: STANDARD

约束限制：

设置该参数的值时请注意大小写敏感。

取值范围：

  • STANDARD
  • WARM
  • COLD
  • DEEP_ARCHIVE

默认取值：

默认继承桶的存储类型。

x-obs-persistent-headers

String

否

参数解释：

复制对象时，可以在HTTP请求中加入“x-obs-persistent-headers”消息头，用来加入一个或多个自定义的响应头，当用户获取目标对象或查询目标对象元数据时，加入的自定义响应头将会在返回消息的头域中出现。

约束限制：

  • 通过该方式指定的自定义响应头不能以“x-obs-”为前缀，比如可以指定“key1”，但是不能指定“x-obs-key1”。
  • 不能指定http标准头，例如host/content-md5/origin/range/Content-Disposition等。
  • 此头域和自定义元数据总长度不能超过8KB。
  • 如果传入相同key，将value以“,”拼接后放入同一个key中返回。
  • 如果源对象中已经存在自定义响应头，复制的时候不会拷贝到目标对象中。
  • 如果value解码后存在非US-ASCII值或不可识别字符，则服务端只会作为字符串处理并通过“?UTF-8?B?<(str)>?=”包装，而不会做解码，例如key1:abbc，会返回key1: =?UTF-8?B?abbc?=。
  • value不支持包含的字符“空格”、“=”、“,”、“;”、“:”、"."，如果需要包含，请使用URL编码或者Base64编码。
  • 格式：x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2)....

    说明：其中key1/key2等为自定义header，如果含有非ASCII码或不可识别字符，可以采用URL编码或者Base64编码，服务端只会作为字符串处理，不会做解码。value1/value2等为对应自定义header的值，base64_encode指做base64编码，即将自定义header和对应值的base64编码作为一个key-value对用“:”连接，然后用“,”将所有的key-value对连接起来，放在x-obs-persistent-headers这个header中即可，服务端会对上传的value做解码处理。

    示例：x-obs-persistent-headers: key1:dmFsdWUx,key2:dmFsdWUy

    在下载目标对象或获取目标对象元数据时：返回两个头域为“key1:value1”与“key2:value2”

取值范围：

无

默认取值：

无

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

约束限制：

无

取值范围：

  • kms
  • AES256

默认取值：

无

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

约束限制：

  • 仅在SSE-C加密方式下使用该头域。
  • 需要和x-obs-server-side-encryption-customer-key， x-obs-server-side-encryption-customer-key-MD5一起使用。

取值范围：

AES256

默认取值：

无

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

String

否。当使用SSE-C方式时，必选。

参数解释：

该头域表示加密目标对象使用的密钥。

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

约束限制：

  • 仅在SSE-C加密方式下使用该头域。
  • 该头域由256-bit的密钥经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key-MD5一起使用。

取值范围：

无

默认取值：

无

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

String

否。当使用SSE-C方式时，必选。

参数解释：

该头域表示加密目标对象使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。

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

约束限制：

  • 仅在SSE-C加密方式下使用该头域。
  • 该头域由密钥的128-bit MD5值经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key一起使用。

取值范围：

密钥的MD5值。

默认取值：

无

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

String

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

参数解释：

该头域表示解密源对象使用的算法。

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

约束限制：

  • 仅在SSE-C加密方式下使用该头域。
  • 需要和x-obs-copy-source-server-side-encryption-customer-key，x-obs-copy-source-server-side-encryption-customer-key-MD5一起使用。

取值范围：

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=

约束限制：

  • 仅在SSE-C加密方式下使用该头域。
  • 该头域由256-bit的密钥经过base64-encoded得到，需要和x-obs-copy-source-server-side-encryption-customer-algorithm，x-obs-copy-source-server-side-encryption-customer-key-MD5一起使用。

取值范围：

无

默认取值：

无

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==

约束限制：

  • 仅在SSE-C加密方式下使用该头域。
  • 该头域由密钥的128-bit MD5值经过base64-encoded得到，需要和x-obs-copy-source-server-side-encryption-customer-algorithm，x-obs-copy-source-server-side-encryption-customer-key一起使用。

取值范围：

密钥的MD5值。

默认取值：

无

success-action-redirect

String

否

参数解释：

用于指定当此次请求操作成功响应后的重定向的地址。

  • 如果此参数值有效且操作成功，响应码为303，Location头域由此参数以及桶名、对象名、对象的ETag组成。
  • 如果此参数值无效，则OBS忽略此参数的作用，Location头域为对象地址，响应码根据操作成功或失败正常返回。

约束限制：

需要为URL格式，如http://domainname、https://domainname。

取值范围：

URL

默认取值：

无

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

约束限制：

  • 格式要求为UTC时间，并符合ISO 8601标准。如：2015-07-01T04:11:15Z
  • 该参数需要和x-obs-object-lock-mode一同使用。

取值范围：

需要大于当前时间。

默认取值：

无

其他消息头请参见表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.region.myhuaweicloud.com/doc/2015-06-30/">
    <LastModified>modifiedDate</LastModified> 
    <ETag>etagValue</ETag> 
</CopyObjectResult>

响应消息头

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

除公共响应消息头之外，还可能使用如下表2中的消息头。

表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方式，响应包含该头域。

取值范围：

  • kms
  • AES256

默认取值：

无

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

参数解释：

对象的存储类型。

约束限制：

对象为非标准存储对象时，会返回此头域。

取值范围：

  • WARM
  • COLD
  • DEEP_ARCHIVE

默认取值：

返回对象的存储类型。

响应消息元素

该请求的响应消息通过消息元素来返回复制结果，元素具体含义如表3所示。

表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.region.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.region.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.region.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.region.myhuaweicloud.com/doc/2015-06-30/">
  <LastModified>2015-07-01T01:48:07.706Z</LastModified>  
  <ETag>"507e3fff69b69bf57d303e807448560b"</ETag> 
</CopyObjectResult>
父主题： 对象操作