文档

PutBucketReplication

更新时间:

PutBucketReplication接口用于为存储空间(Bucket)指定数据复制规则。OSS支持跨区域复制(Cross-Region Replication)和同区域复制(Same-Region Replication)。

注意事项

数据复制是以异步(近实时)方式将源Bucket中的文件(Object)以及对Object的创建、更新和删除等操作自动复制到目标Bucket。使用数据复制时,有如下注意事项:

  • 数据复制采用异步复制,数据复制到目标Bucket需要一定的时间,通常几分钟到几小时不等,具体取决于数据的大小。

  • 源Bucket与目标Bucket的名称不能相同。

  • 使用跨区域复制时,源Bucket与目标Bucket必须处于不同的数据中心;使用同地域复制时,源Bucket与目标Bucket必须处于相同的数据中心。

关于数据复制的更多信息,请分别参见跨区域复制介绍同区域复制介绍

请求语法

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>

请求元素

名称

类型

是否必选

示例值

描述

ReplicationConfiguration

容器

不涉及

配置Bucket数据复制规则的容器。

父节点:无

子节点:Rule

Rule

容器

不涉及

保存数据复制规则的容器。

父节点:ReplicationConfiguration

子节点:Destination、HistoricalObjectReplication和ID

RTC

容器

不涉及

保存RTC状态规则的容器。

父节点:Rule

子节点:Status

Status

字符串

enabled

开启或关闭RTC功能。RTC功能仅支持跨区域复制时配置。

取值:

  • enabled:开启RTC功能。

  • disabled(默认值):关闭RTC功能。

父节点:RTC

子节点:无

说明

关于RTC功能支持地域的更多信息,请参见RTC支持地域

PrefixSet

容器

不涉及

保存前缀(Prefix)的容器。每条数据复制规则中,最多可指定10条Prefix。

父节点:Rule

子节点:Prefix

Prefix

字符串

source1

设置待复制Object的Prefix。只有匹配该Prefix的Object才被复制到目标Bucket。

  • Prefix最大长度为1023个字符。

  • 如果配置了Prefix,则新写入的数据和历史数据的同步都会遵循Prefix指定的规则。

父节点:PrefixSet

子节点:无

Action

字符串

ALL

指定可以被复制到目标Bucket的操作。如果配置了Action,则新写入的数据和历史数据的同步都会遵循Action指定的复制操作。

Action允许以下操作类型,您可以指定一项或多项。

取值:

  • ALL(默认值):表示PUT、DELETE、ABORT操作均会被同步到目标Bucket。

  • PUT:表示被同步到目标Bucket的写入操作,包括PutObject、PostObject、AppendObject、CopyObject、PutObjectACL、InitiateMultipartUpload、UploadPart、UploadPartCopy、CompleteMultipartUpload。

父节点:Rule

子节点:无

Destination

容器

不涉及

保存目标Bucket信息的容器。

父节点:Rule

子节点:Bucket和Location

Bucket

字符串

destbucket

指定数据要复制到的目标Bucket。

父节点:Destination

子节点:无

Location

字符串

oss-cn-hangzhou

目标Bucket所处的地域。

父节点:Destination

子节点:无

TransferType

字符串

oss_acc

指定数据复制时使用的数据传输链路。

取值:

  • internal(默认值):OSS默认传输链路。

  • oss_acc:传输加速链路。只有创建跨区域复制规则时才能使用传输加速链路。

父节点:Destination

子节点:无

HistoricalObjectReplication

字符串

disabled

指定是否复制历史数据。即开启数据复制前,是否将源Bucket中的数据复制到目标Bucket。

取值:

  • enabled(默认值):表示复制历史数据。

  • disabled:表示不复制历史数据。即仅复制创建数据复制规则后新写入的数据。

父节点:Rule

子节点:无

SyncRole

字符串

aliyunramrole

授权OSS使用哪个角色来进行数据复制。如果指定使用SSE-KMS加密目标对象,则必须指定该元素。

说明

请确保授予角色AliyunOSSFullAccess的权限,否则可能导致数据无法复制。

SourceSelectionCriteria

容器

不涉及

用于标识要复制的源对象的其他筛选条件的容器。当前OSS仅支持针对SSE-KMS加密的源对象指定筛选条件。

SseKmsEncryptedObjects

容器

不涉及

用于筛选使用SSE-KMS加密对象的容器。如果在数据复制规则中指定了SourceSelectionCriteria,则必须指定该元素。

Status

字符串

Enabled

指定OSS是否复制通过SSE-KMS加密创建的对象。取值范围如下:

  • Enabled:表示复制通过SSE-KMS加密创建的对象。

  • Disabled(默认值):表示不复制通过SSE-KMS加密创建的对象。

EncryptionConfiguration

容器

不涉及

目标对象加密配置。如果指定Status为Enabled,则必须指定该元素。

ReplicaKmsKeyID

字符串

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

指定SSE-KMS密钥ID。如果指定Status为Enabled,则必须指定该元素。

此接口还需要包含Host、Date等公共请求头。更多信息,请参见公共请求头(Common Request Headers)

响应头

此接口仅包含公共响应头。更多信息,请参见公共响应头(Common Response Headers)

示例

  • 请求示例

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>
  • 返回示例

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

错误码

错误码

状态码

描述

InvalidTargetBucket

400 BadRequest

返回此错误的可能原因如下:

  • 目标Bucket名称与源Bucket名称相同。

  • 目标Bucket不存在。

  • 目标Bucket与源Bucket不属于同一个用户。

InvalidTargetLocation

400 BadRequest

目标Bucket所在的Location不是请求XML中指定的Location。

BucketReplicationAlreadyExist

400 BadRequest

源Bucket到目标Bucket已存在复制关系。

如果需要配置新的数据复制规则,请先删除已有的数据复制规则再配置。

BadReplicationLocation

400 BadRequest

选择的目的数据中心不合法。

您可通过GetBucketReplicationLocation来获得合法的可复制到的数据中心。

NoReplicationLocation

400 BadRequest

使用跨区域复制时,源Bucket所在的数据中心没有与之配对的可实施跨区域复制的数据中心。

跨区域复制数据中心的配对关系可通过访问域名和数据中心查看。

TooManyReplicationRules

400 BadRequest

请求中配置的数据复制规则超过一条。

单次请求中只能配置一条数据复制规则。

TooManyIncomingReplication

400 BadRequest

为Bucket配置的数据复制规则个数已达到100条。请删除不再使用的数据复制规则后重试。

单个Bucket支持配置100条数据复制规则。如果业务需求超出数量限制,请提交工单联系我们。

TooManyOutgoingReplication

400 BadRequest

为Bucket配置的数据复制规则个数已达到100条。请删除不再使用的数据复制规则后重试。

单个Bucket支持配置100条数据复制规则。如果业务需求超出数量限制,请提交工单联系我们。

MissingArgument

400 BadRequest

未指定数据传输链路。

InvalidArgument

400 BadRequest

不支持指定的数据传输链路。

ReplicationLocationNotSupportRtc

400 BadRequest

不支持在该地域开启RTC功能。关于支持开启RTC功能的地域信息,请参见RTC地域