All Products
Search
Document Center

Object Storage Service:PutBucketReplication

Last Updated:Apr 28, 2024

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 operations, such as the create, overwrite, and delete operations, that are performed on objects from a source bucket to a destination bucket. When you use data replication features, take note of the following items:

  • Data is asynchronously replicated. The time that is required to replicate data from the source bucket to the destination bucket may range from a few minutes to a few hours. The replication time varies based on the data size.

  • 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.

For more information, see CRR and SRR.

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,PUT</Action>
        <Destination>
            <Bucket>destbucket</Bucket>
            <Location>oss-cn-hangzhou</Location>
            <TransferType>oss_acc</TransferType>
        </Destination>
        <HistoricalObjectReplication>enabled or disabled</HistoricalObjectReplication>
   </Rule>
</ReplicationConfiguration>

Request parameters

Parameter

Type

Required

Example

Description

ReplicationConfiguration

Container

Yes

N/A

The container that stores data replication configurations.

Parent nodes: none

Child nodes: Rule

Rule

Container

Yes

N/A

The container that stores data replication rules.

Parent nodes: ReplicationConfiguration

Child nodes: Destination, HistoricalObjectReplication, and ID

RTC

Container

No

N/A

The container that stores the status of the Replication Time Control (RTC) feature.

Parent nodes: Rule

Child nodes: Status

Status

String

No

enabled

Specifies whether to enable or disable the RTC feature. The RTC feature can only be used for CRR tasks.

Valid values:

  • enabled

  • disabled (default)

Parent nodes: RTC

Child nodes: none

Note

For more information about the regions in which the RTC feature is available, see RTC.

PrefixSet

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 whose names contain the specified prefix are replicated to the destination bucket.

  • The value of the Prefix parameter can be up to 1,023 characters in length.

  • If you specify the Prefix parameter in a data replication rule, OSS synchronizes new data and historical data based on the value of the Prefix parameter.

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 value of Action.

You can set Action to one or more of the following operation types.

Valid values:

  • ALL (default): PUT, DELETE, and ABORT operations are synchronized to the destination bucket.

  • PUT: Write operations are synchronized to the destination bucket, including PutObject, PostObject, AppendObject, CopyObject, PutObjectACL, InitiateMultipartUpload, UploadPart, UploadPartCopy, and CompleteMultipartUpload.

Parent nodes: Rule

Child nodes: none

Destination

Container

Yes

N/A

The container that stores the 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 link in which data transmission is accelerated. You can set TransferType to oss_acc only when you create 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.

Valid values:

  • enabled (default): replicates historical data to the destination bucket.

  • disabled: does not replicate historical data 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 want to 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.

Note

Make sure that you attach the AliyunOSSFullAccess policy to the role. Otherwise, data may fail to be replicated.

SourceSelectionCriteria

Container

No

N/A

The container that specifies other conditions used to filter the source objects that you want to replicate. Filtering conditions can be specified only for source objects encrypted by using SSE-KMS.

SseKmsEncryptedObjects

Container

No

N/A

The container that is used to filter the 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.

Status

String

No

Enabled

Specifies whether to replicate objects that are encrypted by using SSE-KMS. Valid values:

  • Enabled

  • Disabled (default)

EncryptionConfiguration

Container

No

N/A

The encryption configuration for the objects replicated to the destination bucket. If the Status parameter is set to Enabled, you must specify this parameter.

ReplicaKmsKeyID

String

No

c4d49f85-ee30-426b-a5ed-95e9139d****

The customer master key (CMK) ID that is used in SSE-KMS. If the Status parameter is set to Enabled, you must specify this parameter.

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

Response headers

The response to a PutBucketReplication request contains only common response headers. For more information, see 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 qn6q**************:77Dv****************
<?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 success 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

Status code

Description

InvalidTargetBucket

400 BadRequest

Possible causes:

  • The error message returned because the source bucket and the destination bucket have the same name.

  • The error message returned because 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 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 need to 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 need to 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.

ReplicationLocationNotSupportRtc

400 BadRequest

The error message returned because the RTC feature is unavailable in this region. For more information about the regions in which the RTC feature is available, see Overview.