文档首页/ 对象存储服务 OBS/ API参考/ 桶API/ 桶的跨区域复制/ 设置桶的跨区域复制配置-SetBucketReplication
更新时间：2026-07-10 GMT+08:00
查看PDF
分享

设置桶的跨区域复制配置-SetBucketReplication

功能介绍

跨区域复制是指同账号下跨不同区域中的桶自动、异步地复制对象。通过激活跨区域复制，OBS可将新创建的对象及修改的对象从一个源桶复制到不同区域中的目标桶。桶拥有者或拥有设置桶的跨区域复制配置的用户，可以通过本接口设置桶的跨区域复制配置。了解更多跨区域复制相关信息，请参见使用OBS实现同账号跨区域桶之间数据复制。

配置跨区域复制需要选择IAM委托，该委托必须为“对象存储服务 OBS”的云服务委托，委托需要具有表5 委托需要的OBS权限中的权限。配置方法请参见创建IAM委托。

设置桶的跨区域复制，需要满足以下要求：

要求源桶和目标桶多版本状态保持一致，否则不能设置replication。如何设置桶的多版本，请参见设置桶的多版本状态-SetBucketVersioning。

接口约束

表1 跨区域复制约束与限制

限制类别

具体限制

桶版本限制

桶版本号为3.0及以上的桶支持跨区域复制功能。

桶版本号可以在OBS管理控制台上，进入桶概览页后，在“基本信息”中查看。详情请参见查看桶信息。

功能限制
  • 源桶中归档存储或深度归档存储类型的对象不支持跨区域复制到目标桶。
  • 如果目标桶所属区域不支持存储类别，则复制后对象的存储类别均为标准存储类别。
  • OBS目前仅支持一个源桶同时复制到一个目标桶，不支持一个源桶同时复制到多个目标桶。允许修改目标桶，但修改目标桶会更改所有已创建规则的目标桶。
  • 跨区域复制不支持追加写对象（Appendable类型的对象）复制。
  • 同一个源桶只能创建一条复制所有对象的跨区域复制规则，或多条（最多100条）按前缀匹配的跨区域复制规则。
  • 不支持跨区域复制SSE-C加密的对象。

时间限制

跨区域复制不保证时效性，配置跨区域复制规则后，可能会出现对象不会立即进行复制的情况，请耐心等待。

区域限制
  • 源桶和目标桶必须属于不同的区域。
  • OBS跨区域复制支持的区域情况如下图跨区域复制支持区域所示。√表示两个区域可连通，x表示两个区域不可连通。

同步历史对象相关
  • 启用跨区域复制功能之前上传的对象，默认不会被复制到目标桶，除非开启了“同步历史对象”功能。
  • 启用历史对象复制后，修改跨区域复制配置可能导致历史对象不复制，建议在历史对象复制完成前不要改变该桶的跨区域复制配置。
  • 源桶中对象复制到目标桶后，如果目标桶中对象被删除，3天内重新配置源桶到目标桶的启用历史对象复制的复制规则，在目标桶中被删除的对象的相同版本不会再次被从源桶复制到目标桶。

    例如：您先配置跨区域复制规则1，将源桶中的当前版本对象test.txt复制到了目标桶，又从目标桶中删除了该对象test.txt，同时删除了跨区域复制规则1。2天后又配置了启用历史对象复制的跨区域复制规则2，此时对象test.txt不会再被复制到目标桶中。

多版本控制相关
  • 源桶和目标桶的多版本控制状态必须保持一致，即同时开启或关闭多版本控制。配置了跨区域复制后，如果修改了多版本状态，会导致源桶和目标桶多版本状态不一致期间的操作无法被复制；且多版本控制一旦开启只能暂停而无法关闭，因此在使用replication规则时请谨慎修改多版本状态。
  • 当源桶、目标桶多版本控制处于开启或暂停状态，且跨区域复制规则处于开启状态时，在源桶中不指定版本删除对象，目标桶会同步删除此对象。
  • 在启用跨区域复制过程中，如果您修改目标桶的多版本控制状态，会导致对象复制失败；如果您尝试修改源桶多版本控制状态，必须先删除复制配置，然后才能进行修改。

权限相关
  • 需要保证桶拥有者具有源桶和目标桶的读写权限，以确保数据能够成功复制。如果源桶或目标桶的读写权限错误，导致系统没有读源对象或者写目标对象的权限，这种对象将一直复制不成功，即使将权限修改正确后，也不会重新复制。
  • 不建议您对目标桶中的副本对象进行删除、覆盖或者修改ACL操作，此类操作可能导致目标桶中对象最新版本或者对象访问控制权限与源桶不一致。
  • 如果已复制成功的源对象的ACL发生变化，在该对象匹配的复制策略未发生变化的情况下，这些变化会同步复制到对象副本，但已复制成功的历史对象不会同步源对象的ACL变化。

其他约束与限制
  • 源桶中的对象只能被复制到一个目标桶中，且复制过去的对象不能再被复制到另外一个目标桶。例如有两个不同区域的桶A和桶B，桶A数据可以复制到桶B中，桶B数据也可以复制到桶A中，但桶B中存储的桶A数据的副本不会复制，同理桶A中存储的桶B数据的副本也不会复制。
  • 在启用跨区域复制过程中，如果您删掉OBS云服务委托，会导致对象复制状态为FAILED。
  • 如果目标桶禁止配置公开ACL（开启了阻止公共访问功能中的BlockPublicAcls开关），那么源桶中配置了ACL公开语义的对象，会因为和目标桶的访问策略冲突而导致复制失败。
图1 跨区域复制支持区域

授权信息

您必须是桶拥有者或拥有设置桶的跨区域复制配置的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见OBS不同权限控制方式的区别。

  • 如果使用IAM授权，那么请在“角色与策略授权”、“身份策略授权”两种IAM授权方式中选择一种，并配置相应权限：
    • 如果使用角色与策略授权（旧版IAM，即IAM v3接口），需具备obs:bucket:PutReplicationConfiguration权限，授权操作请参见创建IAM自定义策略。
    • 如果使用身份策略授权（新版IAM，即IAM v5接口），如下表所示，需具备obs:bucket:putReplicationConfiguration权限，授权操作请参见创建IAM自定义身份策略。

      授权项

      Action

      访问级别

      Access Level

      资源类型（*为必须）

      Resource Type (*: required)

      条件键

      Condition Key

      别名

      Alias

      依赖的授权项

      Dependencies

      obs:bucket:putReplicationConfiguration

      Write

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • 如果使用桶策略进行授权，需具备obs:bucket:PutReplicationConfiguration权限，具体操作请参见自定义创建桶策略。

URI

PUT /

调用方法

请参见如何调用API。调用前需要先计算API签名，并将签名添加到请求中。

您还可以使用API Explorer在线调试接口。

请求消息样式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
PUT /?replication HTTP/1.1 
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
x-obs-date: date 
Content-MD5: MD5
Authorization: authorization string 
Content-Length: contentlength 

<ReplicationConfiguration> 
    <Agency>testAcy</Agency>
    <Rule> 
        <ID>rule1</ID> 
        <Filter>
            <Not>
                <Tag>
                    <Key>key1</Key>
                    <Value>value1</Value>
                </Tag>
            </Not>
        </Filter>
        <Status>rule-status</Status> 
        <Destination> 
            <Bucket>targetbucketname</Bucket> 
            <StorageClass>STANDARD</StorageClass>
            <DeleteData>Enabled</DeleteData>
        </Destination> 
        <HistoricalObjectReplication>Enabled</HistoricalObjectReplication>
        <DeleteMarker>Enabled</DeleteMarker>                     
    </Rule> 
</ReplicationConfiguration>

URI参数（URI Parameters）

表2 URI参数

参数名称

参数类型

是否必选

描述

replication

String

否

参数解释：

用于标识API接口与跨区域复制规则有关。

约束限制：

无。

取值范围：

replication

默认取值：

不涉及

请求头参数（Request headers）

该请求使用的消息头如下所示。

表3 设置桶的复制配置请求头参数

参数

是否必选

参数类型

描述

Content-MD5

是

string

参数解释：

按照RFC 1864标准计算出消息体的MD5摘要字符串，即消息体128bit MD5值经过base64编码后得到的字符串。如何计算Content-MD5可参考Java中Content-MD5的计算方法示例。

取值范围：

不涉及

默认取值：

不涉及

请求体参数（Request body）

在此请求中，需要在请求的消息体中配置桶的复制配置，配置信息以XML格式上传。具体的配置元素如下描述。

表4 设置桶的复制配置元素

参数

是否必选

参数类型

描述

ReplicationConfiguration

是

Container

参数解释：

跨区域复制规则的容器。ReplicationConfiguration是Rule和Agency的父节点。

约束限制：

  • 单桶可以配置1~100条跨区域复制规则。
  • 单次配置跨区域复制规则的请求body大小不能超过50K。

取值范围：

不涉及

默认取值：

不涉及

Rule

是

Container

参数解释：

一条特定跨区域复制规则信息的容器。

约束限制：

一个桶上可以配置1~100条跨区域复制规则。

取值范围：

请详见Rule参数说明。

默认取值：

不涉及

Agency

是

String

参数解释：

用户创建用于跨区域复制的委托的名称。

约束限制：

  • 委托必须为“对象存储服务 OBS”的云服务委托，委托需要具有表5 委托需要的OBS权限中的权限。
  • 如果勾选了“复制使用KMS加密的对象”，委托还需要具有“KMS CMKFullAccess”权限，委托的授权范围选择“指定区域项目资源”并选择源桶和目标桶所在区域。

取值范围：

长度为0~64的字符串。

默认取值：

不涉及

表5 委托需要的OBS权限

操作

描述

obs:object:GetObject

获取对象内容、获取对象元数据。

obs:object:DeleteObjectVersion

删除对象、批量删除对象。

obs:object:PutObjectVersionAcl

设置对象ACL。

obs:object:AbortMultipartUpload

取消多段上传任务。

obs:object:PutObjectAcl

设置对象ACL。

obs:object:DeleteObject

删除对象、批量删除对象。

obs:bucket:HeadBucket

获取桶元数据。

obs:object:PutObject

PUT上传、POST上传、复制对象、追加写对象、初始化上传段任务、上传段、合并段

obs:object:GetObjectVersionAcl

获取对象ACL。

obs:bucket:GetBucketVersioning

获取桶的多版本状态。

obs:bucket:ListBucketMultipartUploads

列举多段上传任务。

obs:object:ListMultipartUploadParts

列举已上传的段。

obs:object:ModifyObjectMetaData

修改对象元数据。

obs:bucket:ListBucketVersions

列举桶内多版本对象。

obs:bucket:ListBucket

列举桶内对象。

obs:object:GetObjectVersion

获取对象内容、获取对象元数据。

obs:object:GetObjectAcl

获取对象ACL。

obs:bucket:GetReplicationConfiguration

获取桶的跨区域复制配置。
表6 Rule参数说明

参数

是否必选

参数类型

描述

ID

否

String

参数解释：

跨区域复制规则的规则ID。

约束限制：

规则ID不能重复。

取值范围：

长度为0~255的字符串。

默认取值：

不涉及

Status

是

String

参数解释：

是否启用此跨区域复制规则。

约束限制：

不涉及

取值范围：

  • Enabled：启用规则
  • Disabled：未启用规则

默认取值：

不涉及

Prefix

是

String

参数解释：

对象名的前缀。适配于一个或者多个对象。

约束限制：

  • 如果前缀配置为空，则跨区域复制规则将作用于整个桶。
  • 规则之间前缀的字符不支持重叠。例如用户配置了两条规则，规则1的前缀为object，规则2的前缀是obj，则这两条规则就有个重叠的前缀obj。

取值范围：

经过UTF-8编码的长度大于0且不超过1024的字符序列。

默认取值：

不涉及

Destination

是

Container

参数解释：

目标桶信息的容器。

约束限制：

不涉及

取值范围：

请详见Destination参数说明。

默认取值：

不涉及

HistoricalObjectReplication

否

String

参数解释：

是否复制符合跨区域复制规则的历史对象。

约束限制：

不涉及

取值范围：

  • Enabled：复制符合跨区域复制规则的历史对象
  • Disabled：不复制符合跨区域复制规则的历史对象

默认取值：

如果不设置，则默认为Disabled。

DeleteMarker

否

String

参数解释：

是否复制符合跨区域复制规则的对象的 DeleteMarker。

约束限制：

不涉及

取值范围：

  • Enabled：复制符合跨区域复制规则的对象的 DeleteMarker
  • Disabled：不复制符合跨区域复制规则的对象的 DeleteMarker

默认取值：

Enabled

Filter

否

Container

参数解释：

支持传入标签，实现复制指定过滤条件的对象。

约束限制：

1、与Rule中的Prefix选择其一配置

2、若配置Filter，委托需要保证有obs:object:PutObjectTagging、obs:object:GetObjectTagging、obs:object:DeleteObjectTagging权限

取值范围：

And、Not、Tag三选一

默认取值：

不涉及
表7 Destination参数说明

参数

是否必选

参数类型

描述

Bucket

是

String

参数解释：

跨区域复制目标桶的桶名，该桶用于存储被跨区域复制规则标识的对象副本。

约束限制：

如果在跨区域复制配置中有多条规则，那么每条规则都应该有对应的目标桶名。

取值范围：

长度为3~63的字符串。

默认取值：

不涉及

StorageClass

否

String

参数解释：

表示复制到目标桶的对象将被修改成的目标存储类别。

约束限制：

不涉及

取值范围：

  • STANDARD：标准存储
  • WARM：低频访问存储
  • COLD：归档存储
  • DEEP_ARCHIVE：深度归档存储

默认取值：

不涉及

DeleteData

否

String

参数解释：

源桶的对象删除后是否通过跨区域复制操作同步删除目标桶中的同名对象。

约束限制：

不涉及

取值范围：

  • Enabled：源桶的对象删除操作会同步到目标端。
  • Disabled：源桶的对象删除操作不会同步到目标端。

默认取值：

如果不设置，则默认为Disabled。
表8 Filter参数说明

名称

是否必选

参数类型

描述

And

否

Container

参数解释：

并列条件，条件同时满足才复制

父节点：

Filter

约束限制：

1、Filter标签内仅支持1个标签：And、Not、Tag仅能存在一个

2、And的过滤条件数必须大于等于2，小于等于10

取值范围：

Tag

默认取值：

不涉及

Not

否

Container

参数解释：

指定条件不复制。

父节点：

Filter

约束限制：

1、Filter标签内仅支持1个标签：And、Not、Tag仅能存在一个

2、Not数量仅支持1个，当前仅支持Tag

取值范围：

Tag

默认取值：

不涉及

Tag

否

Container

参数解释：

指定标签的对象才能被复制。

父节点：

And或Not或Filter

约束限制：

1、Filter标签内仅支持1个标签：And、Not、Tag仅能存在一个

2、Tag的父节点是Filter或Not，Tag的数量仅支持1个；Tag的父节点是And，最少2个，最多10个

取值范围：

不涉及

默认取值：

不涉及

Key

存在Tag时，则必选

String

参数解释：

标签的键

父节点：

Tag

约束限制：

  • 区分大小写且必须唯一。
  • 不能为空。
  • 不允许使用,/|<>=*\字符。
  • 长度为1~128的字符串。

取值范围：

不涉及

默认取值：

不涉及

Value

存在Tag时，则必选

String

参数解释：

标签的值，

父节点：

Tag

约束限制：

  • 区分大小写且必须唯一。
  • 不能为空。
  • 不允许使用,/|<>=*\字符。
  • 长度为0~255的字符串。

取值范围：

不涉及

默认取值：

不涉及

响应消息样式

1
2
3
4
 
HTTP/1.1 status_code 
Server: OBS 
Date: date 
Content-Length: contentlength

响应头 (Response Headers)

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

响应体 (Response Body)

本接口的响应消息中不携带响应体。

错误响应消息

无特殊错误，所有错误已经包含在错误码概述中。

请求示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
PUT /?replication HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com
Accept: */*
Date: Wed, 27 Jun 2018 13:39:15 +0000
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:CdeqU0Vg9xNdJMZ0PGPgh5EnkO0=
Content-MD5: l/Z8mfSX+VyV8k5EhIQz5Q==
Content-Length: 330

<ReplicationConfiguration>
    <Agency>testAcy</Agency>
    <Rule>
        <ID>Rule-1</ID>
        <Status>Enabled</Status>
        <Filter>
            <Not>
                <Tag>
                    <Key>key1</Key>
                    <Value>value1</Value>
                </Tag>
            </Not>
        </Filter>
        <Destination>
            <Bucket>dstbucket</Bucket>
            <StorageClass>STANDARD</StorageClass>
            <DeleteData>Enabled</DeleteData>
        </Destination>      
        <HistoricalObjectReplication>Enabled</HistoricalObjectReplication>
        <DeleteMarker>Enabled</DeleteMarker>
    </Rule>
</ReplicationConfiguration>

响应示例

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: B59500000164417839932E5A2295674C
x-obs-id-2: 32AAAQAAEAABKAAQAAEAABAAAQAAEAABCStv51t2NMMx+Ou+ow7IWV4Sxo231fKe
Date: Wed, 27 Jun 2018 13:39:15 GMT
Content-Length: 0

相关文档

父主题： 桶的跨区域复制

相关文档