Description
The PUT Bucket replication API is used to configure cross-region replication rules for a bucket with versioning enabled. If cross-region replication rules are already configured for the bucket, this request will replace the existing settings.
Note:
To call this API, ensure that versioning is enabled for the bucket. For details about the API for enabling versioning, see PUT Bucket versioning.
Request
Request Example
PUT /?replication HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Content-MD5: MD5
Authorization: Auth String
request body
Note:
Authorization: Auth String (See Request Signature for details.)
Request Header
This API only uses common request headers. For details, see Common Request Headers documentation.
Request Body
Set specific cross-region replication configuration in the request body. The configuration includes the enabling status of the cross-region replication rule, content to be copied, and the name, storage region, and other information of the destination bucket. For each bucket with versioning enabled, COS supports only one cross-region replication rule.
<ReplicationConfiguration>
<Role>qcs::cam::uin/<OwnerUin>:uin/<SubUin></Role>
<Rule>
<Status></Status>
<ID></ID>
<Prefix></Prefix>
<Destination>
<Bucket>qcs::cos:<Region>::<BucketName-APPID></Bucket>
</Destination>
</Rule>
</ReplicationConfiguration>
The specific contents are described as follows:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| ReplicationConfiguration | No | All cross-region replication configurations. | Container | Yes |
| Role | ReplicationConfiguration | Identifier of the initiator: qcs::cam::uin/<OwnerUin>:uin/<SubUin> |
String | Yes |
| Rule | ReplicationConfiguration | Specific configuration information. Up to 1000 rules are supported. | Container | Yes |
| ID | ReplicationConfiguration.Rule | Identifies the name of a specific rule. | String | No |
| Status | ReplicationConfiguration.Rule | Identifies whether a rule takes effect. Enumerated values: Enabled and Disabled | String | Yes |
| Prefix | ReplicationConfiguration.Rule | Prefix matching policy, which cannot overlap. If overlapping occurs, an error is returned. The root directory for prefix matching is empty. | String | Yes |
| Destination | ReplicationConfiguration.Rule | Destination bucket information. | Container | Yes |
| Bucket | ReplicationConfiguration.Rule.Destination | Resource identifier:qcs::cos:<Region>::<BucketName-APPID> |
String | Yes |
| StorageClass | ReplicationConfiguration.Rule.Destination | Storage class. Enumerated values: STANDARD and STANDARD_IA; default value: original bucket class Note: Cross-region replication does not support specifying copied objects as the archive storage. To set the object replicas as the archive storage type, configure lifecycle management in the destination bucket. For detailed operations, see PUT Bucket lifecycle. |
String | No |
Response
Response Headers
This API only returns the public response header. For details, see Common Response Headers documentation.
Response Body
The response body is empty.
Error Analysis
The following table describes some common special errors that may occur with this request. For all error information, see Error Code.
| Error Code | Description | Status Code |
|---|---|---|
| InvalidBucketState | Versioning is not enabled for the bucket. As a result, cross-region replication cannot be enabled. | 409 Conflict |
| InvalidArgument | The parameter content is invalid. | 400 Bad Request |
Practical Case
Request
The following PUT Bucket replication request adds a cross-region replication configuration record to the bucket originbucket-1250000000. The configuration is used to copy objects with the prefix testPrefix to the destination bucket destinationbucket-1250000000 in Region1.
PUT /?replication HTTP/1.1
Date: Mon, 28 Aug 2017 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR**&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=replication&q-signature=254bf9cd3d6615e89a36ab652437f9d45c5f**
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: <BucketName-APPID>.<Endpoint>
Content-Length: 312
<ReplicationConfiguration>
<Role>qcs::cam::uin/100000000001:uin/100000000001</Role>
<Rule>
<Status>Enabled</Status>
<ID>RuleId_01</ID>
<Prefix>testPrefix</Prefix>
<Destination>
<Bucket>qcs::cos:ap-region1::destinationbucket-1250000000</Bucket>
</Destination>
</Rule>
</ReplicationConfiguration>
Response
After receiving the request, COS returns the following response, indicating that the cross-region replication configuration is set successfully.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 14 Apr 2019 07:06:19 GMT
x-cos-bucket-region: ap-region1
x-cos-request-id: NWQwMzQ3NmJfMjRiMjU4NjRfOTM4NV82ZDU1****
x-cos-trace-id: OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODc0OWRkZjk0ZDM1NmI1M2E2MTRlY2MzZDhmNmI5MWI1OWE4OGMxZjNjY2JiNTBmMTVmMWY1MzAzYzkyZGQ2ZWM4MzUyZTg1NGRhNWY0NTJiOGUyNTViYzgyNzgxZTEwOTY=