# 使用 S3 清单对数据进行编目和分析
<a name="storage-inventory"></a>

您可以使用 Amazon S3 清单来帮助管理您的存储。例如，您可以出于业务、合规性和法规需要，使用该清单来审核和报告对象的复制和加密状态。您还可以使用 Amazon S3 清单简化和加快业务工作流和大数据任务，此清单可以有计划地取代 Amazon S3 同步 `List` API 操作。Amazon S3 清单不使用 `List` API 操作来审计对象且不会影响存储桶的请求速率。

Amazon S3 清单每天或每周为 S3 存储桶或具有共享前缀的对象（即，其名称以通用字符串开头的对象），提供用于列出您的对象及其对应元数据的逗号分隔值（CSV）、[Apache 优化的行列式（ORC）](https://orc.apache.org/)或 [https://parquet.apache.org/](https://parquet.apache.org/) 输出文件。如果您设置每周清单，则在初始报告后的每个星期日（UTC 时区）生成一份报告。有关 Amazon S3 清单定价的信息，请参阅 [Amazon S3 定价](https://www.amazonaws.cn/s3/pricing/)。

您可以为存储桶配置多个清单列表。配置清单列表时，可以指定以下内容：
+ 清单中应包含哪些对象元数据
+ 是列出所有对象版本，还是仅列出当前版本
+ 在哪里存储清单列表文件输出
+ 是每天生成清单，还是每周生成清单
+ 是否加密清单列表文件

您可以通过 [Amazon Athena](https://docs.amazonaws.cn/athena/latest/ug/what-is.html)、[Amazon Redshift Spectrum](https://docs.amazonaws.cn/redshift/latest/dg/c-getting-started-using-spectrum.html) 以及其他工具（如 [https://prestodb.io/](https://prestodb.io/)、[https://hive.apache.org/](https://hive.apache.org/) 和 [https://databricks.com/spark/about/](https://databricks.com/spark/about/)）使用标准 SQL 查询 Amazon S3 清单。有关使用 Athena 查询清单文件的更多信息，请参阅[使用 Amazon Athena 查询 Amazon S3 清单](storage-inventory-athena-query.md)。

**注意**  
Amazon S3 交付第一份清单报告可能需要长达 48 小时。

**注意**  
删除清单配置后，Amazon S3 可能仍会在系统处理删除操作的短暂过渡期内再提交一份清单报告。

## 源存储桶和目标存储桶
<a name="storage-inventory-buckets"></a>

由清单列出其对象的存储桶称为*源存储桶*。在其中存储清单列表文件的存储桶称为*目标存储桶*。

**源存储桶**

清单列出了源存储桶中存储的对象。您可以获得整个存储桶的清单列表，也可以通过对象键名称前缀筛选此列表。

源存储桶：
+ 包含在清单中列出的对象
+ 包含清单的配置

**目标存储桶**

Amazon S3 清单列表文件将写入目标存储桶。要对目标存储桶内公共位置中的所有清单列表文件进行分组，您可以在清单配置中指定目标前缀。

目标存储桶：
+ 包含清单文件列表。
+ 包含清单文件，其中列出了存储在目标存储桶中的所有清单列表文件。有关更多信息，请参阅 [清单 Manifest](storage-inventory-location.md#storage-inventory-location-manifest)。
+ 必须具有向 Amazon S3 授予验证存储桶的所有权的权限和将文件写入存储桶的权限的存储桶策略。
+ 必须与源存储桶位于同一 Amazon Web Services 区域。
+ 可以与源存储桶相同。
+ 可以由与拥有源存储桶的账户不同的 Amazon Web Services 账户 拥有。

## Amazon S3 清单列表
<a name="storage-inventory-contents"></a>

清单列表文件包含源存储桶中对象的列表以及每个对象的元数据。清单列表文件按以下格式之一存储在目标存储桶中：
+ 作为使用 GZIP 压缩的 CSV 文件
+ 作为使用 ZLIB 压缩的 Apache 优化行列式（ORC）文件
+ 作为使用 Snappy 压缩的 Apache Parquet 文件

**注意**  
不能保证会以任何顺序对 Amazon S3 清单报告中的对象排序。

清单列表文件包含源存储桶中对象的列表以及每个所列对象的元数据。始终包含以下默认字段：
+ **Bucket name (存储桶名称)** – 清单所针对的存储桶的名称。
+ **ETag** – 实体标签（ETag）是对象的哈希。ETag 仅反映对于对象的内容的更改，而不反映对于对象的元数据的更改。ETag 可能是对象数据的 MD5 摘要。是与不是取决于对象的创建方式和加密方式。有关更多信息，请参阅《Amazon Simple Storage Service API 参考》**中的 [https://docs.amazonaws.cn/AmazonS3/latest/API/API_Object.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_Object.html)。
+ **键名称** – 唯一地标识存储桶中的对象的对象键名（或键）。当您使用 CSV 文件格式时，键名称采用 URL 编码形式，必须解码，然后才能使用。
+ **Last modified date (上次修改日期)** – 对象创建日期或上次修改日期（以较晚者为准）。
+ **大小** - 以字节为单位的对象大小，不包括未完成的分段上传、对象元数据和删除标记的大小。
+ **存储类** – 用于存储对象的存储类。设置为 `STANDARD`、`REDUCED_REDUNDANCY`、`STANDARD_IA`、`ONEZONE_IA`、`INTELLIGENT_TIERING`、`GLACIER`、`DEEP_ARCHIVE`、`OUTPOSTS`、`GLACIER_IR` 或 `SNOW`。有关更多信息，请参阅 [了解和管理 Amazon S3 存储类](storage-class-intro.md)。
**注意**  
S3 清单不支持 S3 Express One Zone。

您可以选择在报告中包括以下其它元数据字段：
+ **校验和算法** – 表示用于创建对象的校验和的算法。有关更多信息，请参阅 [使用支持的校验和算法](checking-object-integrity-upload.md#using-additional-checksums)。
+ **加密状态** – 服务器端加密状态，具体取决于使用哪种加密密钥：采用 Amazon S3 托管式密钥的服务器端加密（SSE-S3）、采用 Amazon Key Management Service（Amazon KMS）密钥的服务器端加密（SSE-KMS）、采用 Amazon KMS 密钥的双层服务器端加密（DSSE-C）或采用客户提供的密钥的服务器端加密（SSE-C）。设置为 `SSE-S3`、`SSE-KMS`、`DSSE-KMS`、`SSE-C` 或 `NOT-SSE`。`NOT-SSE` 状态表示对象未使用服务器端加密进行加密。有关更多信息，请参阅 [利用加密来保护数据](UsingEncryption.md)。
+ **S3 Intelligent-Tiering 访问层** – 如果对象存储在 S3 Intelligent-Tiering 存储类中，则为对象的访问层（频繁或不频繁）。设置为 `FREQUENT`、`INFREQUENT`、`ARCHIVE_INSTANT_ACCESS`、`ARCHIVE` 或 `DEEP_ARCHIVE`。有关更多信息，请参阅 [用于自动优化访问模式不断变化或未知的数据的存储类](storage-class-intro.md#sc-dynamic-data-access)。
+ **S3 对象锁定保留截止日期** – 在此日期之前无法删除锁定的对象。有关更多信息，请参阅 [使用对象锁定以锁定对象](object-lock.md)。
+ **S3 对象锁定保留模式** – 对于已锁定的对象，设置为 `Governance` 或 `Compliance`。有关更多信息，请参阅 [使用对象锁定以锁定对象](object-lock.md)。
+ **S3 对象锁定依法保留状态** – 如果依法保留已应用于对象，则设置为 `On`。否则，其设置为 `Off`。有关更多信息，请参阅 [使用对象锁定以锁定对象](object-lock.md)。
+ **版本 ID** – 对象版本 ID。在存储桶上启用版本控制后，Amazon S3 会为添加到存储桶的对象指定版本号。有关更多信息，请参阅 [使用 S3 版本控制保留对象的多个版本](Versioning.md)。（如果仅为对象的当前版本配置列表，则不包括此字段。）
+ **IsLatest** – 如果对象的版本为最新，则设置为 `True`。（如果仅为对象的当前版本配置列表，则不包括此字段。）
+ **删除标记** – 如果对象是删除标记，则设置为 `True`。有关更多信息，请参阅 [使用 S3 版本控制保留对象的多个版本](Versioning.md)。（如果您已将您的报告配置为包含您的对象的所有版本，则此字段将自动添加到报告）。
+ **Multipart upload flag (分段上传标记)** – 如果对象以分段上传形式上传，则设置为 `True`。有关更多信息，请参阅 [在 Amazon S3 中使用分段上传来上传和复制对象](mpuoverview.md)。
+ **对象拥有者**：对象拥有者的规范用户 ID。有关更多信息，请参阅《Amazon 账户管理参考指南》**中的 [Find the canonical user ID for your Amazon account](https://docs.amazonaws.cn/accounts/latest/reference/manage-acct-identifiers.html#FindCanonicalId)。
+ **复制状态** – 设置为 `PENDING`、`COMPLETED`、`FAILED` 或 `REPLICA`。有关更多信息，请参阅 [获取复制状态信息](replication-status.md)。
+ **S3 存储桶密钥状态** – 设置为 `ENABLED` 或者 `DISABLED`。指示对象是否将 S3 存储桶密钥用于 SSE-KMS。有关更多信息，请参阅 [使用 Amazon S3 存储桶密钥](bucket-key.md)。
+ **对象访问控制列表** – 每个对象的访问控制列表（ACL），用于定义哪个 Amazon Web Services 账户或组被授予对此对象的访问权限以及授予的访问权限类型。“对象 ACL”字段以 JSON 格式定义。S3 清单报告包括与源存储桶中的对象关联的 ACL，即使已为该存储桶禁用了 ACL 仍会包括。有关更多信息，请参阅[使用“对象 ACL”字段](objectacl.md)和[访问控制列表 (ACL) 概述](acl-overview.md)。
**注意**  
“对象 ACL”字段以 JSON 格式定义。清单报告将“对象 ACL”字段的值显示为以 base64 编码的字符串。  
例如，假设您有以下采用 JSON 格式的“对象 ACL”字段：  

  ```
  {
          "version": "2022-11-10",
          "status": "AVAILABLE",
          "grants": [{
              "canonicalId": "example-canonical-user-ID",
              "type": "CanonicalUser",
              "permission": "READ"
          }]
  }
  ```
“对象 ACL”字段经过编码并显示为以下以 base64 编码的字符串：  

  ```
  eyJ2ZXJzaW9uIjoiMjAyMi0xMS0xMCIsInN0YXR1cyI6IkFWQUlMQUJMRSIsImdyYW50cyI6W3siY2Fub25pY2FsSWQiOiJleGFtcGxlLWNhbm9uaWNhbC11c2VyLUlEIiwidHlwZSI6IkNhbm9uaWNhbFVzZXIiLCJwZXJtaXNzaW9uIjoiUkVBRCJ9XX0=
  ```
要以 JSON 格式获取“对象 ACL”字段的解码值，可以在 Amazon Athena 中查询此字段。有关示例查询，请参阅[使用 Amazon Athena 查询 Amazon S3 清单](storage-inventory-athena-query.md)。
+ **生命周期到期日期**：设置为对象的生命周期到期时间戳。只有当对象应按照适用的生命周期规则到期时，才会填充此字段。在其他情况下，字段为空。具有 `FAILED` 复制状态的对象不会填充到期日期，因为 S3 生命周期会在复制成功之前阻止对这些对象执行到期和转换操作。有关更多信息，请参阅 [即将过期的对象](lifecycle-expire-general-considerations.md)。

**注意**  
在对象根据其生命周期配置的生存期结束后，Amazon S3 会将该对象加入移除队列并异步移除它。因此，过期日期和 Amazon S3 删除对象的日期之间可能会有一段延迟。清单报告包括已过期但尚未移除的对象。有关 S3 生命周期中的过期操作的更多信息，请参阅[即将过期的对象](lifecycle-expire-general-considerations.md)。

以下是清单报告示例，其中包含由四条记录组成的其它元数据字段。

```
amzn-s3-demo-bucket1    example-object-1    EXAMPLEDC8l.XJCENlF7LePaNIIvs001    TRUE        1500    2024-08-15T15:28:26.0004    EXAMPLE21e1518b92f3d92773570f600    STANDARD    FALSE    COMPLETED    SSE-KMS    2025-01-25T15:28:26.000Z    COMPLIANCE    Off        ENABLED        eyJ2ZXJzaW9uIjoiMjAyMi0xMS0xMCIsInN0YXR1cyI6IkFWQUlMQUJMRSIsImdyYW50cyI6W3sicGVybWlzc2lvbiI6IkZVTExfQ09OVFJPTCIsInR5cGUiOiJDYW5vbmljYWxVc2VyIiwiY2Fub25pY2FsSWQiOiJFWEFNUExFNzY2ZThmNmIxMTVkOTNkNDFkZjJlYWM0MjBhYTRhNDY1ZDE3N2MxMzk4YmM2YTA4OGM3NmI3MDAwIn1dfQ==    EXAMPLE766e8f6b115d93d41df2eac420aa4a465d177c1398bc6a088c76b7000
amzn-s3-demo-bucket1    example-object-2    EXAMPLEDC8l.XJCENlF7LePaNIIvs002    TRUE        200    2024-08-21T15:28:26.000Z    EXAMPLE21e1518b92f3d92773570f601    INTELLIGENT_TIERING    FALSE    COMPLETED    SSE-KMS    2025-01-25T15:28:26.000Z    COMPLIANCE    Off    INFREQUENT    ENABLED    SHA-256    eyJ2ZXJzaW9uIjoiMjAyMi0xMS0xMCIsInN0YXR1cyI6IkFWQUlMQUJMRSIsImdyYW50cyI6W3sicGVybWlzc2lvbiI6IkZVTExfQ09OVFJPTCIsInR5cGUiOiJDYW5vbmljYWxVc2VyIiwiY2Fub25pY2FsSWQiOiJFWEFNUExFNzY2ZThmNmIxMTVkOTNkNDFkZjJlYWM0MjBhYTRhNDY1ZDE3N2MxMzk4YmM2YTA4OGM3NmI3MDAwIn1dfQ==    EXAMPLE766e8f6b115d93d41df2eac420aa4a465d177c1398bc6a088c76b7001
amzn-s3-demo-bucket1    example-object-3    EXAMPLEDC8l.XJCENlF7LePaNIIvs003    TRUE        12500    2023-01-15T15:28:30.000Z    EXAMPLE21e1518b92f3d92773570f602    STANDARD    FALSE    REPLICA    SSE-KMS    2025-01-25T15:28:26.000Z    GOVERNANCE    On        ENABLED        eyJ2ZXJzaW9uIjoiMjAyMi0xMS0xMCIsInN0YXR1cyI6IkFWQUlMQUJMRSIsImdyYW50cyI6W3sicGVybWlzc2lvbiI6IkZVTExfQ09OVFJPTCIsInR5cGUiOiJDYW5vbmljYWxVc2VyIiwiY2Fub25pY2FsSWQiOiJFWEFNUExFNzY2ZThmNmIxMTVkOTNkNDFkZjJlYWM0MjBhYTRhNDY1ZDE3N2MxMzk4YmM2YTA4OGM3NmI3MDAwIn1dfQ==    EXAMPLE766e8f6b115d93d41df2eac420aa4a465d177c1398bc6a088c76b7002
amzn-s3-demo-bucket1    example-object-4    EXAMPLEDC8l.XJCENlF7LePaNIIvs004    TRUE        100    2021-02-15T15:28:27.000Z    EXAMPLE21e1518b92f3d92773570f603    STANDARD    FALSE    COMPLETED    SSE-KMS    2025-01-25T15:28:26.000Z    COMPLIANCE    Off        ENABLED        eyJ2ZXJzaW9uIjoiMjAyMi0xMS0xMCIsInN0YXR1cyI6IkFWQUlMQUJMRSIsImdyYW50cyI6W3sicGVybWlzc2lvbiI6IkZVTExfQ09OVFJPTCIsInR5cGUiOiJDYW5vbmljYWxVc2VyIiwiY2Fub25pY2FsSWQiOiJFWEFNUExFNzY2ZThmNmIxMTVkOTNkNDFkZjJlYWM0MjBhYTRhNDY1ZDE3N2MxMzk4YmM2YTA4OGM3NmI3MDAwIn1dfQ==    EXAMPLE766e8f6b115d93d41df2eac420aa4a465d177c1398bc6a088c76b7003
```

我们建议创建一个删除旧清单列表的生命周期策略。有关更多信息，请参阅 [管理对象的生命周期](object-lifecycle-mgmt.md)。

`s3:PutInventoryConfiguration` 权限允许用户在配置清单列表时选择之前为每个对象列出的所有元数据字段，也可以指定存储清单的目标存储桶。对目标存储桶中的对象具有读取权限的用户可以访问清单列表中提供的所有对象元数据字段。要限制对于清单报告的访问权限，请参阅[向 S3 清单和 S3 分析功能授予权限](example-bucket-policies.md#example-bucket-policies-s3-inventory-1)。

### 清单一致性
<a name="storage-inventory-contents-consistency"></a>

并非所有对象都会显示每个清单列表中。清单列表提供了（新对象和覆盖）的 `PUT` 请求的最终一致性，并提供了 `DELETE` 请求的最终一致性。存储桶的每个清单列表都是存储桶项目的快照。这些列表最终是一致的（也就是说，列表可能不包括最近添加或删除的对象）。

要在对于对象执行操作之前验证对象的状态，我们建议您执行 `HeadObject` REST API 请求以检索对象的元数据，或在 Amazon S3 控制台中检查对象的属性。您还可以使用 Amazon CLI 或 Amazon SDK 检查对象元数据。有关更多信息，请参阅《Amazon Simple Storage Service API 参考》**中的 [https://docs.amazonaws.cn/AmazonS3/latest/API/RESTObjectHEAD.html](https://docs.amazonaws.cn/AmazonS3/latest/API/RESTObjectHEAD.html)。

有关使用 Amazon S3 清单的更多信息，请参阅以下主题。

**Topics**
+ [源存储桶和目标存储桶](#storage-inventory-buckets)
+ [Amazon S3 清单列表](#storage-inventory-contents)
+ [配置 Amazon S3 清单](configure-inventory.md)
+ [查找清单列表](storage-inventory-location.md)
+ [设置清单完成时的 Amazon S3 事件通知](storage-inventory-notification.md)
+ [使用 Amazon Athena 查询 Amazon S3 清单](storage-inventory-athena-query.md)
+ [将 Amazon S3 库存报告中的空版本 ID 字符串转换为空字符串](inventory-configure-bops.md)
+ [使用“对象 ACL”字段](objectacl.md)