All Products
Search
Document Center

PutBucketReplication

Edit in GitHub
Last Updated: Sep 22, 2020 Edit in GitHub

You can call this operation to configure cross-region replication (CRR) rules for a bucket.

Usage notes

Cross-region replication enables the automatic and asynchronous (near real-time) replication of objects across buckets in different OSS regions. Operations such as the creation, overwriting, and deletion of objects can be synchronized from a source bucket to a destination bucket. When you use CRR, take note of the following items:

  • CRR is an asynchronous process. Based on the size of the data, it takes several minutes to several hours to replicate data from the source bucket to the destination bucket.

  • The names of the source bucket and destination bucket must be different. The source bucket and destination bucket must be in different regions.

    For more information, see Cross-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>     
        <PrefixSet>
            <Prefix>prefix_1</Prefix>
            <Prefix>prefix_2</Prefix>
        </PrefixSet>
        <Action>ALL,PUT</Action>
        <Destination>
            <Bucket>Target Bucket Name</Bucket>
            <Location>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 CRR rules.

Parent node: none

Chile node: Rule

Rule

Container

Yes

The container that stores the CRR rule. Only one CRR rule can be configured for a bucket.

Parent node: ReplicationConfiguration

Child nodes: Destination, HistoricalObjectReplication, and ID

ID

String

No

The ID of the CRR rule.

The ID of a CRR rule can be up to 255 characters in length and is globally unique in a bucket.

If the ID of a CRR rule is null or is not specified, OSS generates a unique ID for the CRR rule.

Parent node: Rule

Child node: none

PrefixSet

Container

No

The container that stores prefixes. You can specify up to 10 prefixes in each CRR rule.

Parent node: Rule

Child node: Prefix

Prefix

String

No

The prefix used to specify the object 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 CRR rule, the prefixes specified by Prefix apply to the synchronization of new data and historical data.

Parent node: PrefixSet

Child node: none

Action

String

No

The operations that can be synchronized to the destination bucket. If you configure Action in a CRR rule, the operations specified by Action apply to the synchronization of new data and historical data.

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

Valid values:

  • All: PUT, DELETE, and ABORT operations are synchronized to the destination bucket. This is the default value.

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

Parent node: Rule

Child node: none

Destination

Container

Yes

The container that stores the information about the destination bucket.

Parent node: Rule

Child nodes: Bucket and Location

Bucket

String

Yes

The destination bucket to which the data is replicated.

Parent node: Destination

Child node: none

Location

String

Yes

The region in which the destination bucket is located.

Parent node: Destination

Child node: none

TransferType

String

Yes

The link used to transfer data in CRR.

Valid values:

  • internal: the default link.

  • oss_acc: the link in which data transmission is accelerated.

    Note

    If you set TransferType to oss_acc when you create a CRR rule, OSS checks whether transfer acceleration is enabled for the destination bucket after the CRR rule is created. If transfer acceleration is not enabled for the destination bucket, OSS automatically enables transfer acceleration for the destination bucket.

Parent node: Destination

Child node: none

HistoricalObjectReplication

String

No

Specifies whether to replicate historical data. Historical data indicates the data stored in the source bucket before CRR is enabled for the source bucket.

Valid values:

  • Enabled: indicates that historical data is replicated to the destination bucket. This is the default value.

  • Disabled: indicates that historical data is not replicated to the destination bucket. Only data uploaded to the source bucket after CRR is enabled for the source bucket is replicated.

Parent node: Rule

Child node: none

SyncRole

String

No

The role that you authorize OSS to use to replicate data. If SSE-KMS is specified to encrypt the objects replicated to the destination bucket, SyncRole must be specified.

SourceSelectionCriteria

Container

No

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

SseKmsEncryptedObjects

Container

No

The container used to filter source objects encrypted by using SSE-KMS. This element must be specified if SourceSelectionCriteria is specified in the CRR rule.

Status

String

No

Specifies whether to replicate objects encrypted by using SSE-KMS.

EncryptionConfiguration

Container

No

The encryption configuration of the objects replicated to the destination bucket.

ReplicaKmsKeyID

String

No

The CMK ID used in SSE-KMS.

Examples

  • Sample request

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>
     <ID>test_replication_1</ID>
     <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>acs:ram::174649585760****:role/aliyunramrole</SyncRole>
      <SourceSelectionCriteria>
         <SseKmsEncryptedObjects>
           <Status>Enabled</Status>
         </SseKmsEncryptedObjects>
      </SourceSelectionCriteria>
      <EncryptionConfiguration>
           <ReplicaKmsKeyID>c4d49f85-ee30-426b-a5ed-95e9139d****</ReplicaKmsKeyID>
      </EncryptionConfiguration>     
  </Rule>
</ReplicationConfiguration>
  • Sample response

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

  • The error message returned because the name of the source bucket is the same as that of the destination bucket.

  • The error message returned because the specified bucket does not exist.

  • The error message returned because the source bucket and destination bucket are owned by different users.

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.

BucketAlreadyHasReplicationConfiguration

400 BadRequest

The error message returned because CRR can be configured for only two buckets that are not synchronized with other buckets. In addition, CRR can be configured bidirectional between two buckets.

To synchronize data from a source bucket for which a CRR rule is configured to a new destination bucket that is not specified in the CRR rule, you must delete the existing CRR rule first.

BucketReplicationAlreadyExist

400 BadRequest

The error message returned because CRR has been configured between the requested bucket and another bucket.

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 only one CRR rule can be configured for a bucket.

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.