Amazon Simple Storage Service
开发人员指南 (API 版本 2006-03-01)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

Amazon S3 清单

Amazon S3 清单是 Amazon S3 提供的用于帮助管理您的存储的工具之一。您可以出于业务、合规性和法规要求,使用它来审核和报告对象的复制和加密状态。您还可以使用 Amazon S3 清单简化和加快业务工作流和大数据作业,它可以有计划地取代 Amazon S3 同步 List API 操作。

Amazon S3 清单每天或每周为 S3 存储桶或共享前缀 (即,其名称以通用字符串开头的对象) 提供用于列出您的对象及其对应元数据的逗号分隔值 (CSV) 或 Apache 优化的行列式 (ORC) 输出文件。有关 Amazon S3 清单定价的信息,请参阅 Amazon S3 定价

您可以为存储桶配置多个清单列表。您可以配置要包含在该清单中的对象元数据,是列出所有对象版本还是仅列出当前版本,要存储清单列表文件输出的位置以及是每天还是每周生成该清单。您也可以指定对清单列表文件进行加密。

您可以通过 Amazon Athena、Amazon Redshift Spectrum 和其他工具 (例如 PrestoApache HiveApache Spark) 使用标准 SQL 来查询 Amazon S3 清单。使用 Athena 对您的清单文件运行查询非常简单。您可以在提供 Athena 的所有区域中使用 Athena 查询 Amazon S3 清单。

我如何设置 Amazon S3 清单?

本部分介绍了如何设置清单,包括有关清单源存储桶和目标存储桶的详细信息。

Amazon S3 清单源存储桶和目标存储桶

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

源存储桶

清单列出了源存储桶中存储的对象。您可以获取整个存储桶的清单列表或按 (对象键名称) 前缀筛选过的清单列表。

源存储桶:

  • 包含在清单中列出的对象。

  • 包含清单的配置。

目标存储桶

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

目标存储桶:

  • 包含清单文件列表。

  • 包含 Manifest 文件,其中列出了存储在目标存储桶中的所有文件清单列表。有关更多信息,请参阅 什么是清单 Manifest?

  • 必须具有向 Amazon S3 授予验证存储桶的所有权的权限和将文件写入存储桶的权限的存储桶策略。

  • 必须与源存储桶位于同一 AWS 区域。

  • 可以与源存储桶相同。

  • 可以由与拥有源存储桶的账户不同的 AWS 账户拥有。

设置 Amazon S3 清单

Amazon S3 清单将帮助您按预定的计划创建 S3 存储桶中的对象的列表,由此管理存储。您可以为存储桶配置多个清单列表。清单列表将发布到目标存储桶中的 CSV 或 ORC 文件。

设置清单的最简单方法是使用 AWS 管理控制台,不过您也可以使用 REST API、AWS CLI 或 AWS 开发工具包。控制台将为您执行以下过程的第一步:将存储桶策略添加到目标存储桶。

为 S3 存储桶设置 Amazon S3 清单

  1. 为目标存储桶添加存储桶策略。

    您必须在目标存储桶上创建存储桶策略,以向 Amazon S3 授予将对象写入已定义位置的存储桶的权限。有关策略示例,请参阅向 Amazon S3 清单和 Amazon S3 分析功能授予权限

  2. 配置一个清单以列出源存储桶中的对象并将该列表发布到目标存储桶。

    当您为源存储桶配置清单列表时,您应指定用于存储该列表的目标存储桶,以及是每天还是每周生成一次列表。您还可以配置要包含的对象元数据以及是列出所有对象版本还是仅列出最新版本。

    您可以指定使用 Amazon S3 托管密钥 (SSE-S3) 或 AWS KMS 托管密钥 (SSE-KMS) 来加密清单列表文件。有关 SSE-S3 和 SSE-KMS 的更多信息,请参阅使用服务器端加密保护数据。如果您打算使用 SSE-KMS 加密,请参阅步骤 3。

    • 有关如何使用控制台配置清单列表的信息,请参阅如何配置 Amazon S3 清单? (在 Amazon Simple Storage Service 控制台用户指南 中)。

    • 要使用 Amazon S3 API 来配置清单列表,请使用 PUT Bucket inventory configuration REST API,或者使用 AWS CLI 或 AWS 开发工具包中的等效工具。

  3. 要使用 SSE-KMS 加密清单列表文件,请授予 Amazon S3 使用 AWS KMS 密钥的权限。

    您可以使用 AWS 管理控制台、REST API、AWS CLI 或 AWS 开发工具包,为清单列表文件配置加密。无论选择哪种方式,您都必须授予 Amazon S3 相应权限以使用 AWS KMS 客户主密钥 (CMK) 加密清单文件。可通过修改用于加密清单文件的 AWS KMS CMK 的密钥策略,向 Amazon S3 授予权限。有关更多信息,请参阅下一部分:授予 Amazon S3 使用您的 AWS KMS 密钥进行加密的权限

授予 Amazon S3 使用您的 AWS KMS 密钥进行加密的权限

您必须通过密钥策略授予 Amazon S3 权限,以使用您的 AWS KMS 密钥进行加密。以下过程介绍如何使用 AWS Identity and Access Management (IAM) 控制台修改用于加密清单文件的 AWS KMS CMK 的密钥策略。

授予使用您的 AWS KMS 密钥进行加密的权限

  1. 使用拥有 AWS KMS CMK 的 AWS 账户登录 AWS 管理控制台,然后通过以下网址打开 IAM 控制台:https://console.amazonaws.cn/iam/

  2. 在左侧导航窗格中,选择 Encryption keys

  3. 对于 Region,选择适当的 AWS 区域。请勿使用导航栏中的区域选择器 (右上角)。

  4. 选择您在加密清单时要使用的 CMK 的别名。

  5. 在页面的 Key Policy 部分中,选择 Switch to policy view

  6. 使用 Key Policy 编辑器,将以下密钥策略插入到现有策略中,然后选择 Save Changes。您可能希望将策略复制到现有策略的末尾。

    { "Sid": "Allow Amazon S3 use of the key", "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": [ "kms:GenerateDataKey*" ], "Resource": "*" }

您还可以使用 AWS KMS PUT 密钥策略 API PutKeyPolicy,将密钥策略复制到用于加密清单文件的 CMK 的密钥策略。有关创建和编辑 AWS KMS CMK 的更多信息,请参阅 AWS Key Management Service Developer Guide 中的入门

Amazon S3 清单中包含了什么?

清单列表文件包含源存储桶中对象的列表以及每个对象的元数据。清单列表将在目标存储桶中存储为使用 GZIP 压缩的 CSV 文件,或者经过 Apache 优化的行列式 (ORC) 文件。

清单列表包含 S3 存储桶中的对象的列表以及每个列出的对象的以下元数据:

  • Bucket name – 清单所针对的存储桶的名称。

  • Key name – 唯一地标识存储桶中的对象的对象键名称 (或键)。使用 CSV 文件格式时,键名称采用 URL 编码形式,必须解码然后才能使用。

  • Version ID – 对象版本 ID。在存储桶上启用版本控制后,Amazon S3 会为添加到存储桶的对象指定版本号。有关更多信息,请参阅 对象版本控制。(如果列表仅针对对象的当前版本,则不包含此字段。)

  • IsLatest – 如果对象的版本为最新,则设置为 True。(如果列表仅针对对象的当前版本,则不包含此字段。)

  • Size – 对象大小 (以字节为单位)。

  • Last modified date – 对象创建日期或上次更新日期 (以较晚者为准)。

  • ETag – 实体标签是对象的哈希。ETag 仅反映对对象的内容的更改,而不反映对对象的元数据的更改。ETag 可能是也可能不是对象数据的 MD5 摘要。是与不是取决于对象的创建方式和加密方式。

  • Storage class – 用于存储对象的存储类。有关更多信息,请参阅 存储类别

  • Multipart upload flag – 如果对象以分段上传形式上传,则设置为 True。有关更多信息,请参阅 分段上传概述

  • Delete marker – 如果对象是删除标记,则设置为 True。有关更多信息,请参阅 对象版本控制。(如果列表仅针对对象的当前版本,则不包含此字段。)

  • Replication status – 设置为 PENDINGCOMPLETEDFAILEDREPLICA.有关更多信息,请参阅查看跨区域复制状态

  • Encryption status – 设置为 SSE-S3SSE-CSSE-KMSNOT-SSE。SSE-S3、SSE-KMS 以及客户提供密钥的 SSE (SSE-C) 的服务器端加密状态。NOT-SSE 状态表示对象未使用服务器端加密进行加密。有关更多信息,请参阅 使用加密保护数据

下面是在电子表格应用程序中打开的示例 CSV 清单列表。所示的标题行仅用于帮助阐述示例;不会包含在实际列表中。

 在电子表格应用程序中打开的示例清单列表的屏幕截图。

我们建议创建一个删除旧清单列表的生命周期策略。有关更多信息,请参阅 对象生命周期管理

清单一致性

并非所有对象都会显示每个清单列表中。清单列表提供了新对象和覆盖的 PUT 的最终一致性,并提供了 DELETE 的最终一致性。清单列表是存储桶项的滚动快照,这些项最终是一致的 (即,列表可能不包含最近添加或删除的对象)。

要在对对象执行操作之前验证对象的状态,我们建议您执行 HEAD Object REST API 请求以检索对象的元数据,或在 Amazon S3 控制台中检查对象的属性。您还可以使用 AWS CLI 或 AWS 开发工具包检查对象元数据。有关更多信息,请参阅 Amazon Simple Storage Service API Reference 中的 HEAD 对象

清单列表位于何处?

在清单列表发布后,Manifest 文件将发布到目标存储桶中的以下位置。

destination-prefix/source-bucket/config-ID/YYYY-MM-DDTHH-MMZ/manifest.json destination-prefix/source-bucket/config-ID/YYYY-MM-DDTHH-MMZ/manifest.checksum destination-prefix/source-bucket/config-ID/hive/dt=YYYY-MM-DD-HH-MM/symlink.txt
  • destination-prefix 是清单配置中设置的 (对象键名称) 前缀,可用于对目标存储桶中的公共位置的所有清单列表文件进行分组。

  • source-bucket 是清单列表所针对的源存储桶。添加它是为了防止在将不同的源存储桶中的多个清单发送到同一目标存储桶时发生冲突。

  • config-ID 为了防止从同一源存储桶发送到同一目标存储桶的多个清单报告发生冲突而添加。

  • YYYY-MM-DDTHH-MMZ 是时间戳,包含生成清单报告时开始扫描存储桶的开始时间和日期;例如,2016-11-06T21-32Z。报告中不会出现在此时间戳之后添加的存储。

  • manifest.json 是 Manifest 文件。

  • manifest.checksummanifest.json 文件内容的 MD5。

  • symlink.txt 是与 Apache Hive 兼容的 Manifest 文件。

清单列表每天或每周发布到目标存储桶中的以下位置。

destination-prefix/source-bucket/data/example-file-name.csv.gz ... destination-prefix/source-bucket/data/example-file-name-1.csv.gz
  • destination-prefix 是清单配置中设置的 (对象键名称) 前缀。它可用于对目标存储桶公共位置中的所有清单列表文件进行分组。

  • source-bucket 是清单列表所针对的源存储桶。添加它是为了防止在将不同的源存储桶中的多个清单发送到同一目标存储桶时发生冲突。

  • example-file-name.csv.gz 是 CSV 清单文件之一。ORC 清单名称以文件扩展名 .orc 结尾。

什么是清单 Manifest?

Manifest 文件 manifest.jsonsymlink.txt 描述清单文件的位置。每次交付新的清单列表时,它均带有一组新的 Manifest 文件。

manifest.json 文件中包含的每个 Manifest 均提供了有关清单的元数据和其他基本信息。这些信息包含:

  • 源存储桶名称

  • 目标存储桶名称

  • 清单版本

  • 以纪元日期格式创建时间戳,包含生成清单报告时开始扫描存储桶的开始时间和日期

  • 清单文件的格式和架构

  • 目标存储桶中清单文件的实际列表

每当写入 manifest.json 文件后,它都会附带一个 manifest.checksum 文件 (作为 manifest.json 文件内容的 MD5)。

下面是 CSV 格式清单的 manifest.json 文件中的 Manifest 示例。

{ "sourceBucket": "example-source-bucket", "destinationBucket": "example-inventory-destination-bucket", "version": "2016-11-30", "creationTimestamp" : "1514944800000", "fileFormat": "CSV", "fileSchema": "Bucket, Key, VersionId, IsLatest, IsDeleteMarker, Size, LastModifiedDate, ETag, StorageClass, MultipartUploaded, ReplicationStatus", "files": [ { "key": "Inventory/example-source-bucket/2016-11-06T21-32Z/files/939c6d46-85a9-4ba8-87bd-9db705a579ce.csv.gz", "size": 2147483647, "MD5checksum": "f11166069f1990abeb9c97ace9cdfabc", "inventoriedRecord": 58050695 } ] }

下面是 ORC 格式清单的 manifest.json 文件中的 Manifest 示例。

{ "sourceBucket": "example-source-bucket", "destinationBucket": "arn:aws:s3:::example-destination-bucket", "version": "2016-11-30", "creationTimestamp" : "1514944800000", "fileFormat": "ORC", "fileSchema": "struct<bucket:string,key:string,version_id:string,is_latest:boolean,is_delete_marker:boolean,size:bigint,last_modified_date:timestamp,e_tag:string,storage_class:string,is_multipart_uploaded:boolean,replication_status:string,encryption_status:string>", "files": [ { "key": "inventory/example-source-bucket/data/d794c570-95bb-4271-9128-26023c8b4900.orc", "size": 56291, "MD5checksum": "5925f4e78e1695c2d020b9f6eexample" } ] }

symlink.txt 文件是一个与 Apache Hive 兼容的 Manifest 文件,使 Hive 能够自动发现清单文件及其关联的数据文件。与 Hive 兼容的 Manifest 文件可以用于与 Hive 兼容的服务 Athena 和 Amazon Redshift Spectrum。它还可用于与 Hive 兼容的应用程序,包括 PrestoApache HiveApache Spark 以及许多其他应用程序。

重要

symlink.txt Apache Hive 兼容的 Manifest 文件当前不适用于 AWS Glue。

ORC 格式的清单文件不适用于 Apache HiveApache Spark

清单完成时我如何知道?

您可以设置 Amazon S3 事件通知以在创建清单校验和文件后接收通知,该通知将指示库存列表已添加到目标存储桶。清单是目标位置的所有库存列表的最新列表。

Amazon S3 可以将事件发布到 Amazon Simple Notification Service (Amazon SNS) 主题、Amazon Simple Queue Service (Amazon SQS) 队列或 AWS Lambda 函数。有关更多信息,请参阅 配置 Amazon S3 事件通知

以下通知配置定义了新添加到目标存储桶的所有 manifest.checksum 文件将由 AWS Lambda cloud-function-list-write 处理。

<NotificationConfiguration> <QueueConfiguration> <Id>1</Id> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>destination-prefix/source-bucket</Value> </FilterRule> <FilterRule> <Name>suffix</Name> <Value>checksum</Value> </FilterRule> </S3Key> </Filter> <Cloudcode>arn:aws-cn:lambda:us-west-2:222233334444:cloud-function-list-write</Cloudcode> <Event>s3:ObjectCreated:*</Event> </QueueConfiguration> </NotificationConfiguration>

有关更多信息,请参阅 AWS Lambda Developer Guide 中的将 AWS Lambda 与 Amazon S3 一起使用

使用 Amazon Athena 查询清单

您可以在提供 Athena 的所有区域中通过 Amazon Athena 使用标准 SQL 来查询 Amazon S3 清单。要检查 AWS 区域可用性,请参阅 AWS 区域表

Athena 可以查询 ORC 或 CSV 格式的 Amazon S3 清单文件。当您使用 Athena 查询清单时,我们建议您使用 ORC 格式的清单文件,而不是 CSV。ORC 提供了更快的查询性能并能够降低查询成本。ORC 是自我描述、可感知类型的列式文件格式,专为 Apache Hadoop 而设计。列式格式允许读取器仅读取、解压缩并处理当前查询所需的列。所有 AWS 区域均提供 ORC 格式的 Amazon S3 清单。

开始使用 Athena 查询 Amazon S3 清单

  1. 创建一个 Athena 表。有关创建表的信息,请参阅 Amazon Athena 用户指南 中的入门

    下面的示例查询在清单报告中包含所有可选字段。删除您的清单没有选择的所有可选字段,以便查询对应于您的清单的选定字段。此外,您必须使用您的存储桶名称和位置。位置指向清单的目标路径;例如,s3://destination-prefix/source-bucket/config-ID/hive

    CREATE EXTERNAL TABLE your-table-name( `bucket` string, key string, version_id string, is_latest boolean, is_delete_marker boolean, size bigint, last_modified_date timestamp, e_tag string, storage_class string, is_multipart_uploaded boolean, replication_status string, encryption_status string ) PARTITIONED BY (dt string) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde' STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.SymlinkTextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.IgnoreKeyTextOutputFormat' LOCATION 's3://destination-prefix/source-bucket/config-ID/hive';
  2. 要向表中添加新的清单列表,请使用以下 MSCK REPAIR TABLE 命令。

    MSCK REPAIR TABLE your-table-name;
  3. 在执行前两个步骤后,您可以对自己的清单运行即席查询,如以下示例中所示。

    SELECT encryption_status, count(*) FROM your-table-name GROUP BY encryption_status;

有关使用 Athena 的更多信息,请参阅 Amazon Athena 用户指南

下面是用于 Amazon S3 清单的 REST 操作。