Call the PutBucketReplication operation to configure data replication rules for a bucket - Object Storage Service

You can use the PutBucketReplication operation to configure data replication rules for a bucket. Object Storage Service (OSS) provides cross-region replication (CRR) and same-region replication (SRR).

Usage notes

Data replication automatically replicates objects and the operations performed on them, such as creation, overwriting, and deletion operations, from a source bucket to a destination bucket. When you use data replication, note the following items:

Data replication is an asynchronous process. It takes several minutes to several hours to complete based on the size of the data to replicate.
The source bucket and the destination bucket must have different names.
For CRR, the source bucket and the destination bucket must be located in different regions. For SRR, the source bucket and the destination bucket must be located in the same region.

For more information about data replication, see Cross-region replication and Same-region replication.

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>
   </Rule>
</ReplicationConfiguration>

Request elements

Parameter	Type	Required	Example	Description
ReplicationConfiguration	The container	Yes	N/A	The container that stores data replication configurations. Parent nodes: none Child nodes: Rule
Rule	The container	Yes	N/A	The container that stores data replication rules. Parent nodes: ReplicationConfiguration Child nodes: Destination, HistoricalObjectReplication, ID, etc.
ID	String	No	first	The unique identifier of the data replication rule Parent nodes: Rule Child nodes: none
PrefixSet	The container	No	N/A	The container that stores prefixes. You can specify up to 10 prefixes in each data replication rule. Parent nodes: Rule Child nodes: Prefix
Prefix	String	No	source1	The prefix that is used to specify the object that you want to replicate. Only objects that match the prefix are replicated to the destination bucket. The value of Prefix can be up to 1,023 characters in length. If you specify Prefix in a data replication rule, OSS synchronizes new data and historical data based on the specified value of Prefix. Parent nodes: PrefixSet Child nodes: none
Action	String	No	ALL	The operations that can be synchronized to the destination bucket. If you configure Action in a data replication rule, OSS synchronizes new data and historical data based on the specified Action value. You can set Action to one or more of the following operation types. Valid values: ALL (default): indicates that the 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: indicates that write operations are synchronized to the destination bucket, including 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 nodes: Rule Child nodes: none
Destination	The container	Yes	N/A	The container that stores information about the destination bucket. Parent nodes: Rule Child nodes: Bucket and Location
Bucket	String	Yes	destbucket	The destination bucket to which data is replicated. Parent nodes: Destination Child nodes: none
Location	String	Yes	oss-cn-hangzhou	The region in which the destination bucket is located. Parent nodes: Destination Child nodes: none
TransferType	String	Yes	oss_acc	The link that is used to transfer data during data replication. Valid values: internal (default): the default data transfer link used in OSS. oss_acc: the transfer acceleration link. You can set TransferType to oss_acc only when you create cross-region replication (CRR) rules. Parent nodes: 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. Default value: enabled. Valid values: enabled (default): indicates that historical data is replicated to the destination bucket. disabled: indicates that historical data is not replicated to the destination bucket. Only data uploaded to the source bucket after data replication is enabled for the source bucket is replicated. Parent nodes: Rule Child nodes: none
SyncRole	String	No	aliyunramrole	The role that you authorize OSS to use to replicate data. If you want to use SSE-KMS to encrypt the objects that are replicated to the destination bucket, you must specify this parameter. Note Make sure that the role is granted the `AliyunOSSFullAccess` permission. Otherwise, data may fail to be replicated. Parent nodes: Rule Child nodes: none
SourceSelectionCriteria	The container	No	N/A	The container that specifies other conditions used to filter the source objects to replicate. Filtering conditions can be specified only for source objects encrypted by using SSE-KMS. Parent nodes: Rule Child nodes: SseKmsEncryptedObjects
SseKmsEncryptedObjects	The container	No	N/A	The container that stores source objects that are encrypted by using SSE-KMS. This parameter must be specified if the SourceSelectionCriteria parameter is specified in the data replication rule. Parent nodes: SourceSelectionCriteria Child nodes: Status
Status	String	No	Enabled	Specifies whether to replicate objects encrypted by using SSE-KMS. Default value: Disabled. Valid values: Enabled: Objects encrypted by using SSE-KMS are replicated. Disabled (default): Objects encrypted by using SSE-KMS are not replicated. Parent nodes: SseKmsEncryptedObjects Child nodes: none
EncryptionConfiguration	The container	No	N/A	The encryption configuration for the objects that are replicated to the destination bucket. If Status is set to Enabled, you must specify this parameter. Parent nodes: Rule Child nodes: ReplicaKmsKeyID
ReplicaKmsKeyID	String	No	c4d49f85-ee30-426b-a5ed-95e9139d****	The customer master key (CMK) ID that is used in SSE-KMS. If Status is set to Enabled, you must specify this parameter. Parent nodes: EncryptionConfiguration Child nodes: none
RTC	object	No		The container that stores information about the Replication Time Control (RTC) status. Parent nodes: Rule Child nodes: Status
Status	String	No	Enabled	Specifies whether to enable or disable the RTC feature. The RTC feature can be used only for cross-region replication (CRR) tasks. Default value: disabled. Valid values: enabled disabled (default) Parent nodes: RTC Child nodes: none Note For more information about the regions that support the RTC feature, see Regions that support RTC.

For more information about the common request headers contained in PutBucketReplication requests, such as Host and Date, see Common request headers.

Response header

The response to a PutBucketReplication request contains only common response headers. For more information, see Common response headers.

Examples

Sample requests

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>     
  </Rule>
</ReplicationConfiguration>

Sample command output:

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

You can use OSS SDKs for the following programming languages to call the PutBucketReplication operation:

Command-line tool ossutil

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

Error codes

Error code	HTTP status code	Description
InvalidTargetBucket	400 BadRequest	Possible causes: The source bucket and the destination bucket have the same name. The destination bucket does not exist. The error message returned because the source bucket and the destination bucket are owned by different Alibaba Cloud accounts.
InvalidTargetLocation	400 BadRequest	The error message returned because the region of the destination bucket is different from the region specified in the XML body of the request.
BucketReplicationAlreadyExist	400 BadRequest	The error message returned because a data replication rule already exists between the source bucket and the destination bucket. To configure a data replication rule between the source bucket and the destination bucket, delete the existing rule.
BadReplicationLocation	400 BadRequest	The error message returned because the region of the destination bucket is invalid. You can call the GetBucketReplicationLocation operation to query valid regions in which the destination bucket can be located.
NoReplicationLocation	400 BadRequest	The error message returned because the region of the source bucket does not have a matching region for which CRR can be configured. For more information about the matching regions for CRR, see Endpoints and regions.
TooManyReplicationRules	400 BadRequest	The error message returned because 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 error message returned because 100 data replication rules are configured for the bucket. Delete the rules that you no longer use and then try again. You can configure up to 100 data replication rules for a bucket. If your business requirements exceed this limit, please submit a ticket to contact us.
TooManyOutgoingReplication	400 BadRequest	The error message returned because 100 data replication rules are configured for the bucket. Delete the rules that you no longer use and then try again. You can configure up to 100 data replication rules for a bucket. If your business requirements exceed this limit, submit a ticket to contact us.
MissingArgument	400 BadRequest	The error message returned because the transmission link is not specified.
InvalidArgument	400 BadRequest	The error message returned because the specified transmission link is not supported.
ReplicationLocationNotSupportRtc	400 BadRequest	The error message returned because the RTC feature is unavailable in this region. For more information about the regions that support the RTC feature, see RTC regions.