Configures data replication rules for a bucket. Object Storage Service (OSS) provides two data replication features: cross-region replication (CRR) and same-region replication (SRR).
Usage notes
You can use data replication features to automatically synchronize objects and the operations performed on the objects, such as creation, overwriting, and deletion operations from a source bucket to a destination bucket. When you use data replication features, take note of the following items:
Data replication is an asynchronous process. It takes several minutes to several hours to complete a data replication process based on the size of the data to replicate.
The source bucket and the destination bucket cannot have the same name.
When you use CRR, the source bucket and the destination bucket must be located in different regions. When you use SRR, the source bucket and the destination bucket must be located in the same region.
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>
<PrefixSet>
<Prefix>prefix_1</Prefix>
<Prefix>prefix_2</Prefix>
</PrefixSet>
<Action>ALL,PUT</Action>
<Destination>
<Bucket>Target Bucket Name</Bucket>
<Location>oss-cn-hangzhou</Location>
<TransferType>oss_acc</TransferType>
</Destination>
<HistoricalObjectReplication>enabled or disabled</HistoricalObjectReplication>
</Rule>
</ReplicationConfiguration>
Request elements
Element | Type | Required | Description |
---|---|---|---|
ReplicationConfiguration | Container | Yes | The container that stores data replication configurations. Parent nodes: none Child nodes: Rule |
Rule | Container | Yes | The container that stores data replication rules. Parent nodes: ReplicationConfiguration Child nodes: Destination, HistoricalObjectReplication, and ID |
PrefixSet | Container | No | 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 | The prefix that is used to specify the object to replicate. Only objects whose names contain the specified prefix are replicated to the destination bucket.
Parent nodes: PrefixSet Child nodes: none |
Action | String | No | 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 value of Action. You can set Action to one or more of the following operation types. Default value: ALL. Valid values:
Parent nodes: Rule Child nodes: none |
Destination | Container | Yes | The container that stores the information about the destination bucket. Parent nodes: Rule Child nodes: Bucket and Location |
Bucket | String | Yes | The destination bucket to which the data is replicated. Parent nodes: Destination Child nodes: none |
Location | String | Yes | The region in which the destination bucket is located. Parent nodes: Destination Child nodes: none |
TransferType | String | Yes | The link that is used to transfer data during data replication. Default value: internal. Valid values:
Parent nodes: Destination Child nodes: none |
HistoricalObjectReplication | String | No | Specifies whether to replicate historical data from the source bucket to the destination bucket before data replication is enabled. Default value: enabled. Valid values:
Parent nodes: Rule Child nodes: none |
SyncRole | String | No | 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 element. |
SourceSelectionCriteria | Container | No | 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. |
SseKmsEncryptedObjects | Container | No | The container that is used to filter source objects encrypted by using SSE-KMS. This element must be specified if SourceSelectionCriteria is specified in the data replication rule. |
Status | String | No | Specifies whether to replicate objects encrypted by using SSE-KMS. Default value: Disabled. Valid values:
|
EncryptionConfiguration | Container | No | The encryption configuration for the objects that are replicated to the destination bucket. If Status is set to Enabled, you must specify this element. |
ReplicaKmsKeyID | String | No | The customer master key (CMK) ID that is used in SSE-KMS. If Status is set to Enabled, you must specify this element. |
For more information about the common request headers contained in PutBucketReplication requests such as Host and Date, see Common request headers.
Response headers
The headers contained in the response to a PutBucketReplication request are all common response headers. For more information about common response headers, see the "Common response headers" section in Common HTTP 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, 24 Sep 2015 15:39:12 GMT
Authorization: OSS qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrTZ****
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
<Rule>
<PrefixSet>
<Prefix>source_image</Prefix>
<Prefix>video</Prefix>
</PrefixSet>
<Action>PUT</Action>
<Destination>
<Bucket>target-bucket</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 responses
HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 24 Sep 2015 15:39:12 GMT
Content-Length: 0
Connection: close
Server: AliyunOSS
Error codes
Error code | HTTP status code | Description |
---|---|---|
InvalidTargetBucket | 400 BadRequest | Possible causes:
|
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 which CRR can be configured, see Regions and endpoints. |
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 you must configure more than 100 data replication rules for a bucket, submit a ticket. |
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 you must configure more than 100 data replication rules for a bucket, submit a ticket. |
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. |