调用PutBucketReplication接口为存储空间指定数据复制规则-对象存储(OSS)-阿里云帮助中心

注意事项

数据复制是以异步（近实时）方式将源Bucket中的文件（Object）以及对Object的创建、更新和删除等操作自动复制到目标Bucket。使用数据复制时，有如下注意事项：

数据复制采用异步复制，数据复制到目标Bucket需要一定的时间，通常几分钟到几小时不等，具体取决于数据的大小。
源Bucket与目标Bucket的名称不能相同。
使用跨区域复制时，源Bucket与目标Bucket必须处于不同的数据中心；使用同地域复制时，源Bucket与目标Bucket必须处于相同的数据中心。

请求语法

POST /?replication&comp=add HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Authorization: SignatureValue
Host: BucketName.oss-cn-hangzhou.aliyuncs.com

<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
   <Rule>     
        <RTC>
            <Status>enabled or disabled</Status>
        </RTC>
        <PrefixSet>
            <Prefix>prefix_1</Prefix>
            <Prefix>prefix_2</Prefix>
        </PrefixSet>
        <Action>ALL or PUT</Action>
        <Destination>
            <Bucket>destbucket</Bucket>
            <Location>oss-cn-hangzhou</Location>
            <TransferType>oss_acc</TransferType>
        </Destination>
        <HistoricalObjectReplication>enabled or disabled</HistoricalObjectReplication>
        <SyncRole>aliyunramrole</SyncRole>
        <UserTaggings>
            <FilterType>AND or OR</FilterType>
            <UserTagging>
                <Key>key1</Key>
                <Value>value1</Value>
            </UserTagging>
            ...
        </UserTaggings>
   </Rule>
</ReplicationConfiguration>

请求元素

名称	类型	是否必选	示例值	描述
ReplicationConfiguration	容器	是	不涉及	配置Bucket数据复制规则的容器。父节点：无子节点：Rule
Rule	容器	是	不涉及	保存数据复制规则的容器。父节点：ReplicationConfiguration 子节点：Destination、HistoricalObjectReplication、UserTaggings和ID等
ID	字符串	否	first	数据复制规则的唯一标识父节点：Rule 子节点：无
PrefixSet	容器	否	不涉及	保存前缀（Prefix）的容器。每条数据复制规则中，最多可指定10条Prefix。父节点：Rule 子节点：Prefix
Prefix	字符串	否	source1	设置待复制Object的Prefix。只有匹配该Prefix的Object才被复制到目标Bucket。 Prefix最大长度为1023个字符。如果配置了Prefix，则新写入的数据和历史数据的同步都会遵循Prefix指定的规则。父节点：PrefixSet 子节点：无
Action	字符串	否	ALL	指定可以被复制到目标Bucket的操作。如果配置了Action，则新写入的数据和历史数据的同步都会遵循Action指定的复制操作。 Action允许以下操作类型，您可以指定一项或多项。取值： ALL（默认值）：表示PUT、DELETE、ABORT操作均会被同步到目标Bucket。重要该策略下新增、更新和删除Object都会被复制到目标Bucket。通过这种方式，确保了数据的一致性，适用于需要共享和访问同一数据集的多用户或应用程序环境。但是配置该策略后，当手动删除或者通过生命周期自动删除源Bucket内的Object时，目标Bucket也会删除对应的Object，且Object删除后无法恢复。 PUT：表示被同步到目标Bucket的写入操作，包括PutObject、PostObject、AppendObject、CopyObject、PutObjectACL、InitiateMultipartUpload、UploadPart、UploadPartCopy、CompleteMultipartUpload。重要该策略下仅新增和更新的Object会被复制，而删除操作不会影响目标Bucket。通过这种方式，可以有效防止因源Bucket手动删除、通过生命周期自动删除的行为导致目标Bucket数据丢失的问题。父节点：Rule 子节点：无
Destination	容器	是	不涉及	保存目标Bucket信息的容器。父节点：Rule 子节点：Bucket和Location
Bucket	字符串	是	destbucket	指定数据要复制到的目标Bucket。父节点：Destination 子节点：无
Location	字符串	是	oss-cn-hangzhou	目标Bucket所处的地域。父节点：Destination 子节点：无
TransferType	字符串	是	oss_acc	指定数据复制时使用的数据传输链路。取值： internal（默认值）：OSS默认传输链路。 oss_acc：传输加速链路。只有创建跨区域复制规则时才能使用传输加速链路。配置此项后，目标 Bucket 的传输加速功能会自动开启，无需提前手动开启。父节点：Destination 子节点：无
HistoricalObjectReplication	字符串	否	disabled	指定是否复制历史数据。即开启数据复制前，是否将源Bucket中的数据复制到目标Bucket。取值： enabled（默认值）：表示复制历史数据。 disabled：表示不复制历史数据。即仅复制创建数据复制规则后新写入的数据。父节点：Rule 子节点：无
SyncRole	字符串	是	aliyunramrole	授权OSS使用哪个RAM角色来进行数据复制。数据复制权限有同账号复制与跨账号复制两种使用场景。对于同账号与跨账号复制，您必须授予RAM角色相应的复制权限，否则无法完成复制任务。详情请参见数据复制权限介绍。父节点：Rule 子节点：无
SourceSelectionCriteria	容器	否	不涉及	用于标识要复制的源对象的其他筛选条件的容器。当前OSS仅支持针对SSE-KMS加密的源对象指定筛选条件。父节点：Rule 子节点：SseKmsEncryptedObjects
SseKmsEncryptedObjects	容器	否	不涉及	用于筛选使用SSE-KMS加密对象的容器。如果在数据复制规则中指定了SourceSelectionCriteria，则必须指定该元素。父节点：SourceSelectionCriteria 子节点：Status
Status	字符串	否	Enabled	指定OSS是否复制通过SSE-KMS加密创建的对象。取值范围如下： Enabled：表示复制通过SSE-KMS加密创建的对象。 Disabled（默认值）：表示不复制通过SSE-KMS加密创建的对象。父节点：SseKmsEncryptedObjects 子节点：无
EncryptionConfiguration	容器	否	不涉及	目标对象加密配置。如果指定Status为Enabled，则必须指定该元素。父节点：Rule 子节点：ReplicaKmsKeyID
ReplicaKmsKeyID	字符串	否	c4d49f85-ee30-426b-a5ed-95e9139d****	指定SSE-KMS密钥ID。如果指定Status为Enabled，则必须指定该元素。父节点：EncryptionConfiguration 子节点：无
RTC	容器	否	不涉及	数据复制时间控制功能的状态。父节点：Rule 子节点：Status
Status	字符串	否	Enabled	开启或关闭RTC功能。RTC功能仅支持跨区域复制时配置。取值： enabled：开启RTC功能。 disabled（默认值）：关闭RTC功能。父节点：RTC 子节点：无说明关于RTC功能支持地域的更多信息，请参见RTC支持地域。
UserTaggings	容器	否	不涉及	保存标签过滤规则的容器。配置后，仅复制拥有指定标签的Object到目标Bucket。配置UserTaggings时，FilterType和UserTagging必须同时设定。父节点：Rule 子节点：FilterType、UserTagging
FilterType	字符串	否	OR	标签过滤策略。区分大小写。取值： AND：Object中所有标签都在过滤规则设置的标签集合中时，才复制该Object。 OR：Object中任意一个标签在过滤规则设置的标签集合中时，即复制该Object。父节点：UserTaggings 子节点：无
UserTagging	容器	否	不涉及	保存单个标签键值对的容器。最多可指定10个标签。设置的标签（键-值对）不可以重复。父节点：UserTaggings 子节点：Key、Value
Key	字符串	否	env	标签键。最大长度为128个字符。区分大小写。合法字符包括字母、数字、空格以及以下符号：+‑=._:/ 父节点：UserTagging 子节点：无
Value	字符串	否	test	标签值。最大长度为256个字符。区分大小写。合法字符包括字母、数字、空格以及以下符号：+‑=._:/ 父节点：UserTagging 子节点：无

此接口还需要包含Host、Date等公共请求头。更多信息，请参见公共请求头（Common Request Headers）。

响应头

此接口仅包含公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

示例

请求示例1（OR过滤策略）

POST /?replication&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
  <Rule>  
     <RTC>
        <Status>enabled</Status>
     </RTC>
     <PrefixSet>
        <Prefix>source1</Prefix>
        <Prefix>video</Prefix>
     </PrefixSet>
     <Action>PUT</Action>
     <Destination>
        <Bucket>destbucket</Bucket>
        <Location>oss-cn-beijing</Location>
        <TransferType>oss_acc</TransferType>
     </Destination>
     <HistoricalObjectReplication>enabled</HistoricalObjectReplication>
      <SyncRole>aliyunramrole</SyncRole>
      <SourceSelectionCriteria>
         <SseKmsEncryptedObjects>
           <Status>Enabled</Status>
         </SseKmsEncryptedObjects>
      </SourceSelectionCriteria>
      <EncryptionConfiguration>
           <ReplicaKmsKeyID>c4d49f85-ee30-426b-a5ed-95e9139d****</ReplicaKmsKeyID>
      </EncryptionConfiguration>
      <UserTaggings>
           <FilterType>OR</FilterType>
           <UserTagging>
               <Key>env</Key>
               <Value>test</Value>
           </UserTagging>
           <UserTagging>
               <Key>dept</Key>
               <Value>dev</Value>
           </UserTagging>
      </UserTaggings>
  </Rule>
</ReplicationConfiguration>

请求示例2（AND过滤策略）

POST /?replication&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Content-Type: application/xml
Content-Length: 350
Date: Thu, 17 Apr 2025 16:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=b8d4e5f6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
  <Rule>  
     <PrefixSet>
        <Prefix>source1</Prefix>
        <Prefix>video</Prefix>
     </PrefixSet>
     <Action>PUT</Action>
     <Destination>
        <Bucket>destbucket</Bucket>
        <Location>oss-cn-beijing</Location>
        <TransferType>oss_acc</TransferType>
     </Destination>
     <HistoricalObjectReplication>disabled</HistoricalObjectReplication>
      <SyncRole>aliyunramrole</SyncRole>
      <UserTaggings>
           <FilterType>AND</FilterType>
           <UserTagging>
               <Key>env</Key>
               <Value>production</Value>
           </UserTagging>
           <UserTagging>
               <Key>dept</Key>
               <Value>finance</Value>
           </UserTagging>
      </UserTaggings>
  </Rule>
</ReplicationConfiguration>

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 24 Sep 2025 15:39:12 GMT
Content-Length: 0
Connection: close
Server: AliyunOSS

SDK

此接口所对应的各语言SDK如下：

命令行工具ossutil

PutBucketReplication接口所对应的ossutil命令，请参见put-bucket-replication。

错误码

错误码	状态码	描述
InvalidTargetBucket	400 BadRequest	返回此错误的可能原因如下：目标Bucket名称与源Bucket名称相同。目标Bucket不存在。目标Bucket与源Bucket不属于同一个用户。
InvalidTargetLocation	400 BadRequest	目标Bucket所在的Location不是请求XML中指定的Location。
BucketReplicationAlreadyExist	400 BadRequest	源Bucket到目标Bucket已存在复制关系。如果需要配置新的数据复制规则，请先删除已有的数据复制规则再配置。
BadReplicationLocation	400 BadRequest	选择的目的数据中心不合法。您可通过GetBucketReplicationLocation来获得合法的可复制到的数据中心。
NoReplicationLocation	400 BadRequest	使用跨区域复制时，源Bucket所在的数据中心没有与之配对的可实施跨区域复制的数据中心。跨区域复制数据中心的配对关系可通过访问域名和数据中心查看。
TooManyReplicationRules	400 BadRequest	请求中配置的数据复制规则超过一条。单次请求中只能配置一条数据复制规则。
TooManyIncomingReplication	400 BadRequest	为Bucket配置的数据复制规则个数已达到100条。请删除不再使用的数据复制规则后重试。单个Bucket支持配置100条数据复制规则。如果业务需求超出数量限制，请联系技术支持。
TooManyOutgoingReplication	400 BadRequest	为Bucket配置的数据复制规则个数已达到100条。请删除不再使用的数据复制规则后重试。单个Bucket支持配置100条数据复制规则。如果业务需求超出数量限制，请联系技术支持。
MissingArgument	400 BadRequest	未指定数据传输链路。
InvalidArgument	400 BadRequest	不支持指定的数据传输链路。
ReplicationLocationNotSupportRtc	400 BadRequest	不支持在该地域开启RTC功能。关于支持开启RTC功能的地域信息，请参见RTC地域。
TooManyTaggings	400 BadRequest	为Bucket配置的数据复制规则中tagging个数不能超过10条。
DuplicateReplicationRuleTaggings	400 BadRequest	为Bucket配置的数据复制规则中有tagging的key和value重复。
DuplicateReplicationRuleTaggingKeys	400 BadRequest	为Bucket配置的数据复制规则中，设置了FilterType为AND，且有tagging的key重复。