Amazon Simple Storage Service
开发人员指南 (API 版本 2006-03-01)

复制配置概述

Amazon S3 以 XML 形式存储复制配置。在复制配置 XML 文件中,您将指定一个 AWS Identity and Access Management (IAM) 角色以及一个或多个规则。

<ReplicationConfiguration> <Role>IAM-role-ARN</Role> <Rule> ... </Rule> <Rule> ... </Rule> ... </ReplicationConfiguration>

Amazon S3 无法在未经您的许可的情况下复制对象。您将向复制配置中指定的 IAM 角色授予权限。Amazon S3 将担任该 IAM 角色以代表您复制对象。您必须先向 IAM 角色授予必要的权限。有关管理权限的更多信息,请参阅设置跨区域复制的权限

在以下场景的复制配置中添加一个规则:

  • 您希望复制所有对象。

  • 您希望复制对象子集。通过在规则中添加一个筛选器,可标识对象子级。在该筛选器中,指定对象键前缀、标签或二者的组合以标识要向其应用规则的对象子集。

如果要选择其他对象子集,请在复制配置中添加多个规则。在每个规则中,指定一个选择不同对象子集的筛选器。例如,您可能选择了键前缀为 tax/ document/ 的副本对象。您将添加两个规则,在一个规则中指定 tax/ 键前缀筛选器,并在另一个规则中指定 document/ 键前缀筛选器。

以下各节提供了更多信息。

基本规则配置

每个规则必须包含规则的状态和优先级,并指示是否复制删除标记。

  • Status 指示规则是启用还是禁用。如果规则处于禁用状态,则 Amazon S3 不会执行规则中指定的操作。

  • Priority 指示在向对象应用多个规则时哪个规则具有优先级。

  • 目前,不复制删除标记,因此您必须将 DeleteMarkerReplication 设置为 Disabled

在目标配置中,您必须提供希望 Amazon S3 将对象复制到其中的存储桶的名称。

以下代码显示针对规则的最低要求:

... <Rule> <ID>Rule-1</ID> <Status>rule-Enabled-or-Diasbled</Status> <Priority>integer</Priority> <DeleteMarkerReplication> <Status>Disabled</Status> </DeleteMarkerReplication> <Destination>       <Bucket>arn:aws:s3:::bucket-name</Bucket> </Destination> </Rule> <Rule> ... </Rule> ... ...

您也可以指定其他配置选项。例如,您可能选择了将一个存储类用于对象副本,将另一个存储类用于源对象。

可选:指定筛选器

要选择规则应用于的对象子集,请添加一个可选筛选器。可按对象键前缀、对象标签或二者的组合进行筛选。如果您同时按键前缀和对象标签进行筛选,Amazon S3 会使用逻辑 AND 运算符组合这些筛选器。换句话中,规则会应用于具有特定键前缀和特定标签的对象子集。

要指定具有基于对象键前缀的筛选器的规则,请使用以下代码。只能指定一个前缀。

<Rule> ... <Filter> <Prefix>key-prefix</Prefix> </Filter> ... </Rule> ...

要指定具有基于对象标签的筛选器的规则,请使用以下代码。可以指定一个或多个对象标签。

<Rule> ... <Filter> <And> <Tag> <Key>key1</Key> <Value>value1</Value> </Tag> <Tag> <Key>key2</Key> <Value>value2</Value> </Tag> ... </And> </Filter> ... </Rule> ...

要指定具有基于键前缀和对象标签组合的规则筛选器,请使用此代码。您需要将这些筛选器包含在 AND 父元素中。Amazon S3 会执行逻辑 AND 运算以组合这些筛选器。换句话中,规则会应用于具有特定键前缀和特定标签的对象子集。

<Rule> ... <Filter> <And> <Prefix>key-prefix</Prefix> <Tag> <Key>key1</Key> <Value>value1</Value> </Tag> <Tag> <Key>key2</Key> <Value>value2</Value> </Tag> ... </Filter> ... </Rule> ...

其他目标配置

在目标配置中,指定您希望 Amazon S3 将对象复制到其中的存储桶。您可以配置 CRR 以将对象从一个源存储桶复制到一个目标存储桶。如果在复制配置中添加多个规则,则所有规则必须标识相同的目标存储桶。

... <Destination> <Bucket>arn:aws:s3:::destination-bucket</Bucket> </Destination> ...

您有以下选项可添加到 <Destination> 元素中:

  • 您可以为对象副本指定存储类。默认情况下,Amazon S3 使用源对象的存储类来创建对象副本,如以下示例所示。

    ... <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> <StorageClass>storage-class</StorageClass> </Destination> ...
  • 当源存储桶和目标存储桶不是由相同的 AWS 账户拥有时,您可以通过添加 AccessControlTranslation 元素,将副本的所有权更改为拥有目标存储桶的 AWS 账户。

    ... <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> <Account>destination-bucket-owner-account-id</Account> <AccessControlTranslation> <Owner>Destination</Owner> </AccessControlTranslation> </Destination> ...

    如果您没有将此元素添加到复制配置中,则副本由拥有源对象的同一 AWS 账户拥有。有关更多信息,请参阅 CRR 的其他配置:更改副本拥有者

  • 源存储桶可能包含使用 AWS KMS 托管密钥通过服务器端加密创建的对象。默认情况下,Amazon S3 不会复制这些对象。您可以选择指示 Amazon S3 复制这些对象,方法是:首先通过添加 SourceSelectionCriteria 元素来显式选择使用此功能,然后再提供 AWS KMS 键(用于目标存储桶的 AWS 区域)以用于对对象副本进行加密。

    ... <SourceSelectionCriteria> <SseKmsEncryptedObjects> <Status>Enabled</Status> </SseKmsEncryptedObjects> </SourceSelectionCriteria> <Destination> <Bucket>arn:aws:s3:::dest-bucket-name</Bucket> <EncryptionConfiguration> <ReplicaKmsKeyID>AWS KMS key IDs to use for encrypting object replicas</ReplicaKmsKeyID> </EncryptionConfiguration> </Destination> ...

    有关更多信息,请参阅 CRR 其他配置:复制使用 AWS KMS 托管加密密钥通过服务器端加密 (SSE) 创建的对象

复制配置示例

首先,您可以根据需要将以下复制配置示例添加到存储桶。

重要

要向存储桶添加复制配置,您必须具有 iam:PassRole 权限。此权限允许您传递向 Amazon S3 授予复制权限的 IAM 角色。通过提供复制配置 XML 中 Role 元素中使用的 Amazon 资源名称 (ARN),可指定 IAM 角色。有关更多信息,请参阅IAM 用户指南中的向用户授予将角色传递给 AWS 服务的权限

例 1:包含一个规则的复制配置

以下基本复制配置指定一个规则。该规则指定 Amazon S3 可担任的一个 IAM 角色以及用于对象副本的目标存储桶。该规则 Status 指示该规则是有效的。

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::AcctID:role/role-name</Role> <Rule> <Status>Enabled</Status> <Destination><Bucket>arn:aws:s3:::destinationbucket</Bucket></Destination> </Rule> </ReplicationConfiguration>

要选择要复制的对象子集,可添加一个筛选器。在以下配置中,该筛选器指定一个对象键前缀。此规则将应用于其键名中带有前缀 Tax/ 的对象。

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::AcctID:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>Tax/</Prefix> </Filter> <Destination><Bucket>arn:aws:s3:::destinationbucket</Bucket></Destination> </Rule> </ReplicationConfiguration>

如果您指定 Filter 元素,则还必须包含 PriorityDeleteMarkerReplication 元素。在此示例中,由于只有一个规则,因此优先级无关紧要。

在以下配置中,筛选器指定一个前缀和两个标签。规则将应用于具有指定键前缀和标签的对象子级。具体来说,规则将应用于键名前缀为 Tax/ 并具有指定对象标签的对象。由于只有一个规则,因此优先级不适用。

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::AcctID:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <And> <Prefix>Tax/</Prefix> <Tag> <Tag> <Key>tagA</Key> <Value>valueA</Value> </Tag> </Tag> <Tag> <Tag> <Key>tagB</Key> <Value>valueB</Value> </Tag> </Tag> </And> </Filter> <Destination><Bucket>arn:aws:s3:::destinationbucket</Bucket></Destination> </Rule> </ReplicationConfiguration>

您可以为对象副本指定存储类,如下所示:

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> <StorageClass>storage-class</StorageClass> </Destination> </Rule> </ReplicationConfiguration>

您可以指定 Amazon S3 支持的任何存储类。

例 2:包含两个规则的复制配置

在以下复制配置中:

  • 每个规则按不同的键前缀进行筛选,以便每个规则应用于不同的对象子集。Amazon S3 复制键名为 Tax/doc1.pdfProject/project1.txt 的对象,但是它不复制键名为 PersonalDoc/documentA 的对象。

  • 由于规则应用于两个不同的对象子级,因此规则优先级无关紧要。下一示例将说明应用规则优先级时会发生的情况。

  • 第二个规则为对象副本指定存储类。Amazon S3 对这些对象副本使用指定的存储类。

  • 两个规则指定了同一个目标存储桶。您只能指定一个目标存储桶,而不管指定多少个规则。

<?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::account-id:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>Tax</Prefix> </Filter> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> </Destination> ... </Rule> <Rule> <Status>Enabled</Status> <Priority>2</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>Project</Prefix> </Filter> <Status>Enabled</Status> <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> <StorageClass>STANDARD_IA</StorageClass> </Destination> ... </Rule> </ReplicationConfiguration>

例 3:包含两个具有重叠前缀的规则的复制配置

在此配置中,两个规则指定具有重叠键前缀 star/starship 的筛选器。两个规则应用于键名称为 starship-x 的对象。在此示例中,Amazon S3 使用规则优先级确定要应用哪个规则。

<ReplicationConfiguration> <Role>arn:aws:iam::AcctID:role/role-name</Role> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>star</Prefix> </Filter> <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> </Destination> </Rule> <Rule> <Status>Enabled</Status> <Priority>1</Priority> <DeleteMarkerReplication> <Status>string</Status> </DeleteMarkerReplication> <Filter> <Prefix>starship</Prefix> </Filter> <Destination> <Bucket>arn:aws:s3:::destinationbucket</Bucket> </Destination> </Rule> </ReplicationConfiguration>

例 4:示例演练

有关演练示例,请参阅 跨区域复制 (CRR) 演练

有关复制配置的 XML 结构的更多信息,请参阅 Amazon Simple Storage Service API Reference 中的 PutBucketReplication

向后兼容

复制配置 XML 的最新版本为 V2。为了向后兼容,Amazon S3 仍继续支持 V1 配置。如果您已使用复制配置 XML V1,请考虑影响向后兼容性的以下问题:

  • 复制配置 XML V2 包含规则的 Filter 元素。通过 Filter 元素,您可以指定基于对象键前缀和/或标签的对象筛选器,以确定规则要应用于的范围。支持复制配置 XML V1 的筛选仅基于键前缀。在这种情况下,您直接添加 Prefix 作为 Rule 元素的子元素,如以下示例所示。

    <?xml version="1.0" encoding="UTF-8"?> <ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Role>arn:aws:iam::AcctID:role/role-name</Role> <Rule> <Status>Enabled</Status> <Prefix>key-prefix</Prefix> <Destination><Bucket>arn:aws:s3:::destinationbucket</Bucket></Destination> </Rule> </ReplicationConfiguration>

    为了向后兼容,Amazon S3 仍继续支持 V1 配置。

  • 当您从源存储桶中删除对象而不指定对象版本 ID 时,Amazon S3 会添加一个删除标记。如果使用复制配置 XML V1,Amazon S3 会复制因用户操作产生的删除标记。换句话说,是用户删除了对象,而不是 Amazon S3 因为对象已在生命周期操作期间过期而将其删除。在 V2 中,Amazon S3 不复制删除标记,因此您必须将 DeleteMarkerReplication 元素设置为 Disabled

    ... <Rule> <ID>Rule-1</ID> <Status>rule-Enabled-or-Diasbled</Priority> <Priority>integer</Status> <DeleteMarkerReplication> <Status>Disabled</Status> </DeleteMarkerReplication> <Destination> <Bucket>arn:aws:s3:::bucket-name</Bucket> </Destination> </Rule> ...