Configure a data replication rule with PutBucketReplication - Object Storage Service

The PutBucketReplication operation is used to configure data replication rules for a bucket. OSS supports cross-region replication (CRR) and same-region replication (SRR).

Usage notes

Data replication asynchronously (near real-time) replicates objects in the source bucket, along with object creation, update, and deletion operations, to the destination bucket. Take note of the following items when you use data replication:

Data replication is asynchronous. It takes a few minutes to a few hours to replicate data to the destination bucket, depending on the data size.
The source bucket and the destination bucket cannot have the same name.
For cross-region replication (CRR), the source and destination buckets must be in different regions. For same-region replication (SRR), the source and destination buckets must be in the same region.
Currently, the tag-based filtering feature is not supported in the China (Zhangjiakou), China (Zhongwei), and Mexico regions.

For more information about data replication, see CRR overview and SRR overview.

Request syntax

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>

Request elements

Name	Type	Required	Example	Description
ReplicationConfiguration	Container	Yes	N/A	The container that stores data replication rules for the bucket. Parent node: none Child nodes: Rule
Rule	Container	Yes	N/A	The container that stores a data replication rule. Parent node: ReplicationConfiguration Child nodes: Destination, HistoricalObjectReplication, UserTaggings, ID, and so on
ID	String	No	first	The unique ID of the data replication rule. Parent node: Rule Child nodes: none
PrefixSet	Container	No	N/A	The container that stores prefixes. You can specify up to 10 prefixes in a data replication rule. Parent node: Rule Child nodes: Prefix
Prefix	String	No	source1	The prefix of the objects to be replicated. Only objects whose names contain the specified prefix are replicated to the destination bucket. The prefix can be up to 1,023 characters in length. If you configure a prefix, both newly written data and historical data are replicated based on the rule specified by the prefix. Parent node: PrefixSet Child nodes: none
Action	String	No	ALL	The operations that can be synchronized to the destination bucket. If you configure Action, both newly written data and historical data are synchronized based on the operations specified by Action. Action allows the following operation types. You can specify one or more operation types. Valid values: ALL (default): specifies that PUT, DELETE, and ABORT operations are synchronized to the destination bucket. Important Besides replication of newly uploaded and updated objects, this replication policy includes replication of deletion, which ensures the consistency of data. This policy is applicable to scenarios in which multiple users or applications need to share and access the same dataset. Objects deleted from the source bucket, either manually or through lifecycle policies, will also be deleted from the destination bucket. Objects cannot be recovered after they are deleted. PUT: specifies that write operations are synchronized to the destination bucket. Write operations include PutObject, PostObject, AppendObject, CopyObject, PutObjectACL, InitiateMultipartUpload, UploadPart, UploadPartCopy, and CompleteMultipartUpload. Important If this replication policy is applied, only objects that are uploaded or updated after the policy takes effect will be replicated to the destination bucket, and objects deleted from the source bucket will not be deleted from the destination bucket. This policy effectively prevents data loss in the destination bucket resulting from manual deletion or automated deletion triggered by lifecycle policies in the source bucket. Parent node: Rule Child nodes: none
Destination	Container	Yes	N/A	The container that stores the information about the destination bucket. Parent node: Rule Child nodes: Bucket and Location
Bucket	String	Yes	destbucket	The destination bucket to which data is replicated. Parent node: Destination Child nodes: none
Location	String	Yes	oss-cn-hangzhou	The region in which the destination bucket is located. Parent node: Destination Child nodes: none
TransferType	String	Yes	oss_acc	The data transfer link used for data replication. Valid values: internal (default): the default OSS transfer link. oss_acc: the transfer acceleration link. You can use the transfer acceleration link only when you create a CRR rule. Parent node: Destination Child nodes: none
HistoricalObjectReplication	String	No	disabled	Specifies whether to replicate historical data from the source bucket to the destination bucket before data replication is enabled. Valid values: enabled (default): replicates historical data. disabled: does not replicate historical data. Only data written to the source bucket after the data replication rule is created is replicated. Parent node: Rule Child nodes: none
SyncRole	String	Yes	aliyunramrole	The RAM role that you authorize OSS to use for data replication. Data replication permissions apply to same-account replication and cross-account replication. For same-account and cross-account replication, you must grant the corresponding replication permissions to the RAM role. Otherwise, the replication task fails. For more information, see Required permissions for data replication. Parent node: Rule Child nodes: none
SourceSelectionCriteria	Container	No	N/A	The container that stores other filter conditions for the source objects to be replicated. Currently, OSS supports filter conditions only for source objects encrypted by using SSE-KMS. Parent node: Rule Child nodes: SseKmsEncryptedObjects
SseKmsEncryptedObjects	Container	No	N/A	The container that stores the filter condition for objects encrypted by using SSE-KMS. If you specify SourceSelectionCriteria in the data replication rule, you must specify this element. Parent node: SourceSelectionCriteria Child nodes: Status
Status	String	No	Enabled	Specifies whether OSS replicates objects created by using SSE-KMS encryption. Valid values: Enabled: replicates objects created by using SSE-KMS encryption. Disabled (default): does not replicate objects created by using SSE-KMS encryption. Parent node: SseKmsEncryptedObjects Child nodes: none
EncryptionConfiguration	Container	No	N/A	The encryption configuration for destination objects. If you set Status to Enabled, you must specify this element. Parent node: Rule Child nodes: ReplicaKmsKeyID
ReplicaKmsKeyID	String	No	c4d49f85-ee30-426b-a5ed-95e9139d****	The ID of the SSE-KMS key. If you set Status to Enabled, you must specify this element. Parent node: EncryptionConfiguration Child nodes: none
RTC	Container	No	N/A	The status of the Replication Time Control (RTC) feature. Parent node: Rule Child nodes: Status
Status	String	No	Enabled	Specifies whether to enable RTC. You can enable RTC only when you configure CRR. Valid values: enabled: enables RTC. disabled (default): disables RTC. Parent node: RTC Child nodes: none Note For more information about the regions that support RTC, see Regions that support RTC.
UserTaggings	Container	No	N/A	The container that stores tag-based filtering rules. After you configure tag-based filtering rules, only objects that have the specified tags are replicated to the destination bucket. If you configure UserTaggings, you must specify both FilterType and UserTagging. Parent node: Rule Child nodes: FilterType and UserTagging
FilterType	String	No	OR	The tag-based filtering policy. Case-sensitive. Valid values: AND: replicates an object only if the object has all the tags specified in the filtering rules. OR: replicates an object if the object has one of the tags specified in the filtering rules. Parent node: UserTaggings Child nodes: none
UserTagging	Container	No	N/A	The container that stores a single tag key-value pair. You can specify up to 10 tags. The specified tags (key-value pairs) must be unique. Parent node: UserTaggings Child nodes: Key and Value
Key	String	No	env	The tag key. The key can be up to 128 characters in length and is case-sensitive. The key can contain letters, digits, spaces, and the following special characters: + - = . _ : / Parent node: UserTagging Child nodes: none
Value	String	No	test	The tag value. The value can be up to 256 characters in length and is case-sensitive. The value can contain letters, digits, spaces, and the following special characters: + - = . _ : / Parent node: UserTagging Child nodes: none

This operation also involves common request headers such as Host and Date. For more information, see Common request headers.

Response headers

This operation returns only common response headers. For more information, see Common response headers.

Examples

Sample request 1 (OR filtering policy)

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>

Sample request 2 (AND filtering policy)

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>

Sample response

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

The following table describes the SDKs that support this operation:

ossutil

For more information about the ossutil command corresponding to the PutBucketReplication operation, see put-bucket-replication.

Error codes

Error codes	HTTP status code	Description
InvalidTargetBucket	400 BadRequest	The possible causes of this error are: The destination bucket has the same name as the source bucket. The destination bucket does not exist. The destination bucket and the source bucket do not belong to the same user.
InvalidTargetLocation	400 BadRequest	The region in which the destination bucket is located is not the region specified in the XML request.
BucketReplicationAlreadyExist	400 BadRequest	A replication relationship already exists between the source bucket and the destination bucket. If you want to configure a new data replication rule, delete the existing data replication rule first.
BadReplicationLocation	400 BadRequest	The selected destination region is invalid. You can call the GetBucketReplicationLocation operation to obtain valid destination regions to which data can be replicated.
NoReplicationLocation	400 BadRequest	For CRR, no destination region is paired with the region in which the source bucket is located. For more information about the region pairs for CRR, see Regions and endpoints.
TooManyReplicationRules	400 BadRequest	More than one data replication rule is configured in the request. You can configure only one data replication rule in a single request.
TooManyIncomingReplication	400 BadRequest	The number of data replication rules configured for the bucket has reached 100. Delete data replication rules that are no longer used and try again. You can configure up to 100 data replication rules for a bucket. If your business requirements exceed the limit, submit a ticket to contact technical support.
TooManyOutgoingReplication	400 BadRequest	The number of data replication rules configured for the bucket has reached 100. Delete data replication rules that are no longer used and try again. You can configure up to 100 data replication rules for a bucket. If your business requirements exceed the limit, submit a ticket to contact technical support.
MissingArgument	400 BadRequest	The data transfer link is not specified.
InvalidArgument	400 BadRequest	The specified data transfer link is not supported.
ReplicationLocationNotSupportRtc	400 BadRequest	RTC cannot be enabled in this region. For more information about the regions that support RTC, see Regions that support RTC.
TooManyTaggings	400 BadRequest	The number of tags in the data replication rule configured for the bucket cannot exceed 10.
DuplicateReplicationRuleTaggings	400 BadRequest	The data replication rule configured for the bucket contains duplicate tag keys and values.
DuplicateReplicationRuleTaggingKeys	400 BadRequest	The data replication rule configured for the bucket has FilterType set to AND and contains duplicate tag keys.