Docs

Torch Object Storage

Bucket Replication

PutBucketReplication

Feature description

This interface sets cross-region or same-region replication rules for a bucket. Using the PutBucketReplication interface, you can replicate newly created and modified objects from a source bucket to a destination bucket in the same or different region.

tip

HNS buckets do not support the PutBucketReplication interface.

Prerequisites

If you set cross-account cross-region or cross-account same-region replication rules, you must grant TOS read permission on the source bucket and write permission on the destination bucket before setting the rules. For detailed operations, see Permission configuration for cross-account replication.

Request syntax

PUT /?replication HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: Fri, 30 Jul 2021 08:05:36 +0000​
Authorization: authorization string​
Content-Length: 120​
Content-MD5: XrY7u+Ae7tCTyyK7j1rNww==​
{​
  "Role": "ServiceRoleforReplicationAccessTOS",​
  "Rules": [{​
      "ID": "1",​
      "Status": "Enabled",​
      "PrefixSet": ["prefix_1", "prefix_2"],​
      "Destination": {​
        "Bucket": "Target Bucket Name",​
        "Location": "cn-beijing",​
        "StorageClass": "STANDARD"​
      },​
      "HistoricalObjectReplication": "Enabled",​
      "DeleteMarkerReplication": "Enabled",​
      "DeleteObjectReplication": "Disabled",​
      "AccessControlTranslation": {​
        "Owner": "BucketOwnerEntrusted"​
      }​
   }]​
}​

Request parameters and headers

warning

This request uses public request headers. See public parameters.

Name	Location	Type	Required	Sample value	Note
replication	Query	String	Yes	-	Represents a special identifier for the PutBucketReplication request.

Request body elements

Name	Type	Required	Sample value	Note
Role	String	Yes	ServiceRoleforReplicationAccessTOS	Role name. This role must have read and write permissions and service access permissions for TOS. You can also use the default TOS role ServiceRoleforReplicationAccessTOS.
Rules	Array	Yes	-	Copy the replication rule information.
ID	String	No	1	Unique identifier of the rule, fewer than 255 characters.
Status	String	Yes	Enabled	Specify whether to enable this rule; the values are explained as follows: Enabled: enable this rule. Disabled: do not enable this rule.
PrefixSet	Array	No	prefix_1	Object name prefix applicable to this rule.
Tags	Array	No	-	TOS can replicate objects with specific tags, supporting up to 10 tags. For more details on tags, see Managing object tags.
Key	String	No	key	The key of the object tag. Parent node: Tags
Value	String	No	value	The value of the object tag. Parent node: Tags
Destination	Object	Yes	-	Target bucket information.
Bucket	String	Yes	Target Bucket Name	Target bucket name.
Location	String	Yes	cn-beijing	Region of the target bucket.
StorageClass	String	No	STANDARD	Specify the storage class of the object copied to the destination bucket. The values are described as follows: STANDARD: Standard Storage. STANDARD_IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering Storage. GLACIER_IR: archive instant retrieval storage. ARCHIVE: archive storage. COLD_ARCHIVE: cold archive storage. DEEP_COLD_ARCHIVE: deep cold archive storage. tip Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is currently in closed beta. Please contact your account manager for access. If both StorageClass and StorageClassInheritDirective parameters are set, the storage type is determined by the value specified in StorageClass.
StorageClassInheritDirective	String	No	DESTINATION_BUCKET	Set the storage class for objects copied to the destination bucket. The values are described as follows: SOURCE_OBJECT: inherit the storage class of the source bucket object. DESTINATION_BUCKET: inherit the default storage class of the destination bucket.
HistoricalObjectReplication	String	Yes	Enabled	Whether to enable replication of historical objects. If enabled, historical objects matching this rule will be replicated. The options are as follows: Enabled: Enable replication of historical objects. Disabled: Do not enable replication of historical objects.
DeleteMarkerReplication	String	No	Enabled	Whether to enable synchronizing deletion markers. If enabled, deletion markers matching this rule will be synchronized. The options are as follows: Enabled：Enable synchronizing deletion markers. Disabled：Do not enable synchronizing deletion markers. warning Synchronizing deletion markers is only supported for buckets with version control enabled. Synchronizing deletion markers is an invitation-only feature. To try it, contact your account manager. The tagging and synchronizing deletion markers functions can only be selected one at a time; simultaneous use of both functions is not supported.
DeleteObjectReplication	String	No	Enabled	Whether to enable synchronizing object deletion. If enabled, after deleting an object in the source bucket, the object in the target bucket will be deleted synchronously. The options are as follows: Enabled：Enable synchronizing object deletion. Disabled：Do not enable synchronizing object deletion. warning Synchronizing object deletion will synchronize deletion operations from the source bucket to the target bucket. For example, when you delete a file on the source bucket or when an expired file deletion rule takes effect in its lifecycle, the target bucket will also synchronously delete the file. Please choose this option carefully. When synchronous object deletion is enabled, TOS automatically ensures eventual consistency of data between the source and destination buckets. However, if you set up bidirectional replication rules between multiple buckets and then delete an object in a destination bucket during replication, TOS cannot guarantee the eventual consistency of data across those buckets. Synchronizing object deletion is an invitation-only feature. To try it, contact your account manager.
TransferType	String	No tip This parameter is required for cross-region replication scenarios between mainland China and regions outside mainland China.	tos_acc	Specify the data transfer link used for cross-region replication; the values are explained as follows: internal: TOS default transfer link. This link is only allowed for cross-region replication data transfers within mainland China. tos_acc: transfer acceleration link. This link is only allowed for cross-region replication data transfers between mainland China and regions outside mainland China. The default value is internal. tip Before using the transfer acceleration link to transfer data, you must enable the transfer acceleration feature, which cannot be disabled once enabled. For details, see enable transfer acceleration. Transfer acceleration is an invitation-only feature. To try it, contact your account manager. Transfer acceleration is billed separately. When using transfer acceleration, TOS charges both the cross-region replication traffic fee for the source bucket and the transfer acceleration outbound traffic fee. For detailed information, see Transfer acceleration fees.
AccessControlTranslation	Object	No	-	Object owner manages permissions. tip When replicating objects across accounts only, set the AccessControlTranslation parameter.
Owner	String	No	BucketOwnerEntrusted	Only supports setting to BucketOwnerEntrusted, which grants the destination bucket owner management permissions for the copied objects. This means the destination bucket owner can read the objects and grant other accounts permission to read the objects. By default, the destination bucket owner can overwrite and delete objects but cannot read the objects or grant other accounts permission to read the objects. Parent node: AccessControlTranslation tip The Owner parameter must be set only when copying objects across accounts.

Response headers

This request returns public response headers. See public parameters.

Response body elements

No elements are used.

Sample request

PUT /?replication HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: Fri, 30 Jul 2021 08:05:36 +0000​
Authorization: authorization string​
Content-Length: 120​
Content-MD5: XrY7u+Ae7tCTyyK7j1rNww==​
{​
  "Role": "ServiceRoleforReplicationAccessTOS",​
  "Rules": [{​
      "ID": "1",​
      "Status": "Enabled",​
      "PrefixSet": ["prefix_1", "prefix_2"],​
      "Destination": {​
        "Bucket": "Target Bucket Name",​
        "Location": "cn-beijing",​
        "StorageClass": "STANDARD"​
      },​
      "HistoricalObjectReplication": "Enabled",​
      "DeleteMarkerReplication": "Enabled",​
      "DeleteObjectReplication": "Disabled",​
      "AccessControlTranslation": {​
        "Owner": "BucketOwnerEntrusted"​
      }​
   }]​
}​

Sample response

HTTP/1.1 200 OK​
x-tos-id-2: f91b0c03a01300c1-a444ed0        ​
x-tos-request-id: f91b0c03a01300c1-a444ed0            ​
Date: Fri, 30 Jul 2021 06:45:39 GMT​
server: TosServer​

Last updated: 2026.02.03 16:24:25