PUT Bucket replication

Last updated: 2019-09-25 18:48:13



The PUT Bucket replication API is used to configure a cross-region replication rule for a bucket where versioning is enabled. If there is already a rule for the bucket, the existing one will be overwritten.

When using this API, make sure that the bucket has versioning enabled. For more information, see the API documentation PUT Bucket versioning.


Sample Request

PUT /?replication HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-MD5: MD5
Authorization: Auth String
request body

Authorization: Auth String (see Request Signature for more information).

Request Headers

Common Headers

The implementation of this request uses a common request header. For more information on common request headers, see Common Request Headers.

Special Headers

This request does not use any special request header.

Request Body

You need to set the configuration information for cross-region replication in the request body, including the status of the cross-region replication rule, content to be replicated, and the name and the region of the destination bucket. Currently, you can only configure one cross-region replication rule for each bucket that has versioning enabled.


The content is described in details below:

Node Name (Keyword) Parent Node Description Type Required
ReplicationConfiguration None Describes all cross-region replication configuration information Container Yes
Role ReplicationConfiguration Initiator ID: qcs::cam::uin/<OwnerUin>:uin/<SubUin> String Yes
Rule ReplicationConfiguration Specific configuration information of up to 1,000 rules. Container Yes
ID ReplicationConfiguration.Rule Name used to identify a specific rule String No
Status ReplicationConfiguration.Rule Indicates whether a rule is in effect; enumerators: Enabled, Disabled String Yes
Prefix ReplicationConfiguration.Rule Prefix matching policy. Policies cannot overlap; otherwise, an error will be returned. The prefix matching root directory is empty String Yes
Destination ReplicationConfiguration.Rule Destination bucket information Container Yes
Bucket ReplicationConfiguration.Rule.Destination Resource ID: qcs::cos:<Region>::<BucketName-APPID> String Yes
StorageClass ReplicationConfiguration.Rule.Destination Storage class; enumerators: STANDARD, STANDARD_IA. It follows the storage class of the source bucket by default.
Note: Currently, cross-region replication does not support specifying the storage class of object copies as archive storage. If you need to set this class for the copies, you can configure lifecycle management for the destination bucket. For more information, see PUT Bucket lifecycle
String No


Response Headers

Common Response Headers

This response contains a common response header. For more information on common response headers, see Common Response Headers.

Special Response Headers

The response to this request does not have special response headers.

Response Body

This response body is empty.

Error Codes

Some common special errors that may occur with this request are listed below. For common error codes, see Error Codes.

Error Code Description Status Code
InvalidBucketState Versioning is not enabled for the current bucket; therefore, cross-region replication cannot be enabled. 409 Conflict
InvalidArgument Invalid parameter. 400 Bad Request



The following PUT Bucket replication request adds a cross-region replication configuration to the bucket originbucket-1250000000, specifying that objects prefixed with testPrefix are to be replicated to the destination bucket destinationbucket-1250000000 in Guangzhou.

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: originbucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 312



After the request above is made, COS returns the following response, indicating that the cross-region replication rule has been successfully configured.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 14 Apr 2019 07:06:19 GMT
Server: tencent-cos
x-cos-bucket-region: ap-guangzhou
x-cos-request-id: NWQwMzQ3NmJfMjRiMjU4NjRfOTM4NV82ZDU1****