# 获取复制状态信息
<a name="replication-status"></a>

复制状态可以帮助您确定正在复制的对象的当前状态。源对象的复制状态将返回 `PENDING`、`COMPLETED`、或 `FAILED`。副本的复制状态将返回 `REPLICA`。

在创建 S3 批量复制任务时，也可以使用复制状态值。例如，可以使用这些状态值来复制从未复制过或复制失败的对象。有关将这些值与批量复制结合使用的更多信息，请参阅[将复制状态信息和批量复制任务结合使用](#replication-status-batch-replication)。

**Topics**
+ [复制状态概述](#replication-status-overview)
+ [复制到多个目标存储桶时的复制状态](#replication-status-multiple-destinations)
+ [启用了 Amazon S3 副本修改同步时的复制状态](#replication-status-replica-mod-syn)
+ [将复制状态信息和批量复制任务结合使用](#replication-status-batch-replication)
+ [查找复制状态](#replication-status-usage)

## 复制状态概述
<a name="replication-status-overview"></a>

在复制中，您有一个源存储桶（对它配置复制）和一个或多个目标存储桶（Amazon S3 将对象复制到其中）。当您请求这些存储桶中的对象（使用 `GetObject`）或对象元数据（使用 `HeadObject`）时，Amazon S3 将在响应中返回 `x-amz-replication-status` 标头：
+ 如果请求源存储桶中的对象，Amazon S3 将返回 `x-amz-replication-status` 标头（如果请求中的对象符合复制条件）。

  例如，假设您在复制配置中指定了对象前缀 `TaxDocs`，以指示 Amazon S3 仅复制键名前缀为 `TaxDocs` 的对象。您上传的具有此键名前缀的任何对象（例如 `TaxDocs/document1.pdf`）都将复制。对于具有此键名前缀的对象请求，Amazon S3 会返回其对象复制状态为以下值之一的 `x-amz-replication-status` 标头：`PENDING`、`COMPLETED` 或 `FAILED`。
**注意**  
如果在上传对象后对象复制失败，您无法重试复制。必须再次上传该对象，或者必须使用 S3 批量复制来复制任何失败的对象。有关使用批量复制的更多信息，请参阅[使用批量复制以复制现有对象](s3-batch-replication-batch.md)。  
对象会因缺少复制角色权限、AWS Key Management Service（AWS KMS）权限或存储桶权限等问题而转换为 `FAILED` 状态。对于临时性故障（例如，在存储桶或区域不可用的情况下），复制状态将不会转换为 `FAILED`，而保持 `PENDING`。在资源重新联机后，Amazon S3 将继续复制这些对象。
+ 当请求目标存储桶中的对象时，如果请求中的对象是 Amazon S3 创建的副本，Amazon S3 会返回值为 `REPLICA` 的 `x-amz-replication-status` 标头。

**注意**  
在从启用了复制的源存储桶中删除对象之前，请检查该对象的复制状态，以确保已复制了该对象。  
如果对源存储桶启用了 S3 生命周期配置，则 Amazon S3 将暂停生命周期操作，直到它将对象的状态标记为 `COMPLETED` 或 `FAILED`。

## 复制到多个目标存储桶时的复制状态
<a name="replication-status-multiple-destinations"></a>

将对象复制到多个目标存储桶时，`x-amz-replication-status` 标头的作用有所不同。仅当向所有目标的复制都成功时，源对象的标头才返回 `COMPLETED` 值。在完成所有目标的复制之前，标头将保持 `PENDING` 值。如果一个或多个目标复制失败，则标头返回 `FAILED`。

## 启用了 Amazon S3 副本修改同步时的复制状态
<a name="replication-status-replica-mod-syn"></a>

当您的复制规则启用了 Amazon S3 副本修改同步时，副本可能报告 `REPLICA` 以外的状态。如果元数据更改正在复制过程中，`x-amz-replication-status` 标头返回 `PENDING`。如果副本修改同步无法复制元数据，则标头返回 `FAILED`。如果正确复制元数据，则副本将返回标头 `REPLICA`。

## 将复制状态信息和批量复制任务结合使用
<a name="replication-status-batch-replication"></a>

在创建批量复制任务时，可以选择指定其它筛选条件，例如对象创建日期和复制状态，来缩小任务的范围。

您可以通过提供以下一个或多个值基于 `ObjectReplicationStatuses` 值筛选要复制的对象：
+ `"NONE"` – 表示 Amazon S3 之前从未尝试过复制对象。
+ `"FAILED"` – 表示 Amazon S3 之前尝试过，但未成功复制对象。
+ `"COMPLETED"` – 表示 Amazon S3 之前已成功复制对象。
+ `"REPLICA"` – 表示这是 Amazon S3 已从另一个源复制的副本对象。

有关将这些复制状态与批量复制结合使用的更多信息，请参阅[分批复制任务的筛选条件](s3-batch-replication-batch.md#batch-replication-filters)。

## 查找复制状态
<a name="replication-status-usage"></a>

要获取存储桶中对象的复制状态，可以使用 Amazon S3 清单工具。Amazon S3 会向目标存储桶发送一个您在清单配置中指定的 CSV 文件。您还可以使用 Amazon Athena 在清单报告中查询复制状态。有关 Amazon S3 清单的更多信息，请参阅 [使用 S3 清单对数据进行编目和分析](storage-inventory.md)。

还可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）或 AWS SDK 来查找对象复制状态。

### 使用 S3 控制台
<a name="replication-status-console"></a>

在 Amazon S3 控制台中，可以在对象的详细信息页面上查看对象的复制状态。

1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。

1. 在左侧导航窗格中，选择**存储桶**。

1. 在**通用存储桶**列表中，选择复制源存储桶的名称。

1. 在 **Objects (对象)** 列表中，请选择对象名称。此时将显示对象的详细信息页面。

1. 在**属性**选项卡上，向下滚动至**对象管理概述**部分。在**管理配置**下，查看**复制状态**下的值。

### 使用 AWS CLI
<a name="replication-status-cli"></a>

使用以下 AWS Command Line Interface（AWS CLI）`head-object` 命令检索对象元数据，如以下示例所示。将 `amzn-s3-demo-source-bucket1` 替换为复制源存储桶的名称，并将另一个 `user input placeholders` 替换为您自己的信息。

```
aws s3api head-object --bucket amzn-s3-demo-source-bucket1 --key object-key --version-id object-version-id           
```

该命令会返回对象元数据（包括 `ReplicationStatus`），如以下示例响应所示。

```
{
   "AcceptRanges":"bytes",
   "ContentType":"image/jpeg",
   "LastModified":"Mon, 23 Mar 2015 21:02:29 GMT",
   "ContentLength":3191,
   "ReplicationStatus":"COMPLETED",
   "VersionId":"jfnW.HIMOfYiD_9rGbSkmroXsFj3fqZ.",
   "ETag":"\"6805f2cfc46c0f04559748bb039d69ae\"",
   "Metadata":{

   }
}
```

### 使用 AWS SDK
<a name="replication-status-sdk"></a>

以下代码段分别使用适用于 Java 的 AWS SDK 和适用于 .NET 的 AWS SDK 获取复制状态。

------
#### [ Java ]

```
GetObjectMetadataRequest metadataRequest = new GetObjectMetadataRequest(bucketName, key);
ObjectMetadata metadata = s3Client.getObjectMetadata(metadataRequest);

System.out.println("Replication Status : " + metadata.getRawMetadataValue(Headers.OBJECT_REPLICATION_STATUS));
```

------
#### [ .NET ]

```
GetObjectMetadataRequest getmetadataRequest = new GetObjectMetadataRequest
    {
         BucketName = sourceBucket,
         Key        = objectKey
    };

GetObjectMetadataResponse getmetadataResponse = client.GetObjectMetadata(getmetadataRequest);
Console.WriteLine("Object replication status: {0}", getmetadataResponse.ReplicationStatus);
```

------