Amazon S3 清单 - Amazon Simple Storage Service
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

如果我们为英文版本指南提供翻译,那么如果存在任何冲突,将以英文版本指南为准。在提供翻译时使用机器翻译。

Amazon S3 清单

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

Amazon S3 库存提供逗号分隔值(CSV), Apache优化行列列(ORC)帕丁(Parquet) 输出文件,该文件在S3桶或共享前缀(以常用字符串开头的名称开头)的每日或每周基础上列出对象及其对应元数据。如果是每周一次,则在初始报告后的每个星期日(UTC 时区)生成一份报告。有关 Amazon S3 库存定价,请参阅 Amazon S3 定价.

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

您可以查询 Amazon S3 使用标准SQL的库存 Amazon Athena, Amazon Redshift Spectrum以及其他工具,例如 Presto阿帕奇希夫,和 阿帕帕火花. 使用 Athena 对您的清单文件运行查询非常简单。您可以使用 Athena 对于 Amazon S3 所有地区的库存查询 Athena 可用。

我如何设置 Amazon S3 清单?

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

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

库存列出对象的桶称为 源桶. 存储库存列表文件的存储桶称为 目标桶.

源存储桶

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

源存储桶:

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

  • 包含清单的配置。

目标存储桶

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

目标存储桶:

  • 包含清单文件列表。

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

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

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

  • 可以与源存储桶相同。

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

设置 Amazon S3 清单

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

设置库存的最简单方法是使用 AWS 管理控制台,但您也可以使用RESTAPI, AWS CLI、或AWSSDK。控制台将为您执行以下过程的第一步:将存储桶策略添加到目标存储桶。

为 S3 存储桶设置 Amazon S3 清单

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

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

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

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

    您可以通过使用 Amazon S3 管理密钥(SSE-S3)或 AWS Key Management Service (AWS KMS)客户管理客户主密钥(CMK)。有关 SSE-S3 和 SSE-KMS 的更多信息,请参阅使用服务器端加密保护数据. 如果您打算使用 SSE-KMS 加密,请参阅步骤 3。

    • 有关如何使用控制台配置库存列表的信息,请参阅 如何配置 Amazon S3 库存?Amazon Simple Storage Service 控制台用户指南.

    • 使用 Amazon S3 API要配置库存列表,请使用 Put桶库存配置 RESTAPI或等效的 AWS CLI 或 AWS SDK。

  3. 使用SSE-KMS对库存列表文件进行加密 Amazon S3 使用存储在 AWS KMS.

    您可以使用 AWS 管理控制台,RESTAPI, AWS CLI、或AWSSDK。无论您选择哪种方式,您都必须授予 Amazon S3 使用 AWS KMS 客户管理CMK对库存文件加密。可通过修改要用于加密清单文件的客户托管 CMK 的密钥策略,向 Amazon S3 授予权限。有关更多信息,请参阅下一部分:授予 Amazon S3 使用您的 AWS KMS 加密CMK.

授予 Amazon S3 使用您的 AWS KMS 加密CMK

授予 Amazon S3 使用客户管理的权限加密 AWS Key Management Service (AWS KMS)客户主密钥(CMK),您必须使用关键政策。要更新您的密钥策略,以便使用 AWS KMS 客户托管 CMK 加密清单文件,请按照以下步骤操作。

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

  1. 使用拥有客户托管 CMK 的 AWS 账户,登录 。AWS 管理控制台.

  2. https://console.amazonaws.cn/kms 打开 AWS KMS 控制台。

  3. 要更改 AWS 区域,请使用页面右上角的区域选择器。

  4. 在左侧导航窗格中,选择 客户管理密钥.

  5. 下方 客户管理密钥,选择要用来加密库存文件的密钥。CMKS是区域特定的,必须与源磁带架位于同一区域。

  6. 下方 关键政策,选择 切换到策略视图.

  7. 要更新关键策略,请选择 编辑.

  8. 下方 编辑关键政策,将以下关键策略添加至现有关键策略。

    { "Sid": "Allow Amazon S3 use of the CMK", "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": [ "kms:GenerateDataKey" ], "Resource": "*" }
  9. 选择 保存更改.

    有关创建 AWS KMS 客户管理的CMKS和使用关键政策,请参阅以下主题 AWS Key Management Service Developer Guide:

    您还可以使用 AWS KMS 放置关键政策API Putkey政策 要将关键策略复制到要用于加密库存文件的客户管理CMK。

包含在 Amazon S3 库存?

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

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

  • 桶名称 – 库存的名称。

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

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

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

  • 尺寸 – 字节的对象大小。

  • 上次修改日期 – 对象创建日期或最后修改日期,以最新为准。

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

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

  • 智能分层访问层 – 如果存储在智能分层中,则对象的访问级别(频繁或不频繁)。有关详细信息,请参阅 Amazon S3 智能分层.

  • 多零件上传标志 – 设置为 True 如果对象作为多部件上传上传。有关更多信息,请参阅 分段上传概述.

  • 删除标记 – 设置为 True,如果对象是删除标记。有关更多信息,请参阅 对象版本控制. (如果您已将您的报告配置为包含您的对象的所有版本,则此字段将自动添加到报告)。

  • 复制状态 – 设置为 PENDINGCOMPLETEDFAILED,或 REPLICA. 有关详细信息,请参阅 复制状态信息.

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

  • S3 对象锁定 保留到日期 – 锁定对象无法删除的日期。有关更多信息,请参阅 使用S3 对象锁定锁定对象.

  • S3 对象锁定 模式 – 设置为 GovernanceCompliance 对于锁定的对象。有关更多信息,请参阅 使用S3 对象锁定锁定对象.

  • S3 对象锁定 依法保留状态 – 设置为 On 如果某个对象的法律保留已被应用到对象,否则将被设置为 Off...有关详细信息,请参阅 使用S3 对象锁定锁定对象.

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

清单一致性

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

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

清单列表位于何处?

在清单列表发布后,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 已添加以防止与发送至同一个目标桶的同一个源磁带桶的多个库存报告进行碰撞。这些区域有: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/config-ID/example-file-name.csv.gz ... destination-prefix/source-bucket/config-ID/example-file-name-1.csv.gz
  • destination-prefix 是库存配置中设置的(对象密钥名称)前缀。它可用于对目标存储桶公共位置中的所有清单列表文件进行分组。

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

  • example-file-name.csv.gz 是CSV库存文件之一。ORC库存名称用文件名扩展名结束 .orc和Parquet库存名称结尾带有文件名扩展名 .parquet.

什么是清单 Manifest?

清单文件 manifest.jsonsymlink.txt 描述库存文件所在的位置。每次交付新的清单列表时,它均带有一组新的 Manifest 文件。这些文件可能会相互覆盖,并且在启用版本控制的存储桶中,将创建清单文件的新版本。

包含在 manifest.json 文件提供有关库存的元数据和其他基本信息。这些信息包含:

  • 源存储桶名称

  • 目标存储桶名称

  • 清单版本

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

  • 清单文件的格式和架构

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

无论何时 manifest.json 文件的写入方式为 manifest.checksum 文件的内容为 manifest.json 文件。

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

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

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

{ "sourceBucket": "example-source-bucket", "destinationBucket": "arn:aws-cn: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,object_lock_retain_until_date:timestamp,object_lock_mode:string,object_lock_legal_hold_status:string>", "files": [ { "key": "inventory/example-source-bucket/data/d794c570-95bb-4271-9128-26023c8b4900.orc", "size": 56291, "MD5checksum": "5925f4e78e1695c2d020b9f6eexample" } ] }

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

{ "sourceBucket": "example-source-bucket", "destinationBucket": "arn:aws-cn:s3:::example-destination-bucket", "version": "2016-11-30", "creationTimestamp" : "1514944800000", "fileFormat": "Parquet", "fileSchema": "message s3.inventory { required binary bucket (UTF8); required binary key (UTF8); optional binary version_id (UTF8); optional boolean is_latest; optional boolean is_delete_marker; optional int64 size; optional int64 last_modified_date (TIMESTAMP_MILLIS); optional binary e_tag (UTF8); optional binary storage_class (UTF8); optional boolean is_multipart_uploaded; optional binary replication_status (UTF8); optional binary encryption_status (UTF8);}" "files": [ { "key": "inventory/example-source-bucket/data/d754c470-85bb-4255-9218-47023c8b4910.parquet", "size": 56291, "MD5checksum": "5825f2e18e1695c2d030b9f6eexample" } ] }

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

重要

TheThethe symlink.txt ApacheHive兼容的清单文件当前不能与 AWS Glue.

阅读 symlink.txt 带有 阿帕奇希夫阿帕帕火花 不支持ORC和Parquet格式化的库存文件。

清单完成时我如何知道?

您可以设置 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 带有 Amazon S3AWS Lambda Developer Guide.

使用 查询清单Amazon Athena

您可以查询 Amazon S3 使用标准SQL的库存 Amazon Athena 所有地区 Athena 可用。若要查看AWS地区可用性,请参阅 AWS区域表.

Athena 可以查询 ORC、Parquet 或 CSV 格式的 Amazon S3 清单文件。当您使用 Athena 查询清单时,我们建议您使用 ORC 格式或 Parquet 格式的清单文件。ORC 和 Parquet 格式提供了更快的查询性能并能够降低查询成本。ORC和Parquet是专为 ApacheHadoop. 列式格式允许读取器仅读取、解压缩并处理当前查询所需的列。所有 AWS 区域均提供 ORC 和 Parquet 格式的 Amazon S3 清单。确定是否使用ORC或Parquet格式真的取决于您的数据和要求。有关详细信息,请参阅 Athena中的更新和数据格式.

开始使用 Athena 要查询 Amazon S3 库存

  1. 创建一个 Athena 表 有关创建表格的信息,请参阅 创建表格 Amazon AthenaAmazon Athena 用户指南.

    下面的示例查询在 ORC 格式的清单报告中包含所有可选字段。删除您的清单没有选择的所有可选字段,以便查询对应于您的清单的选定字段。此外,您必须使用您的存储桶名称和位置。位置指向清单的目标路径;例如,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, object_lock_retain_until_date timestamp, object_lock_mode string, object_lock_legal_hold_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/';

    使用 Athena 若要查询Parquet格式化的库存报告,请使用以下镶嵌血清器代替ORCSerde ROW FORMAT SERDE 声明。

    ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe'

    使用 Athena 若要查询CSV格式化的库存报告,请使用以下镶嵌血清器代替ORCSerde ROW FORMAT SERDE 声明。

    ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.OpenCSVSerde'
  2. 要向表中添加新的清单列表,请使用以下 MSCK REPAIR TABLE 命令。

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

    # Get list of latest inventory report dates available SELECT DISTINCT dt FROM your-table-name ORDER BY 1 DESC limit 10; # Get encryption status for a provided report date. SELECT encryption_status, count(*) FROM your-table-name WHERE dt = 'YYYY-MM-DD-HH-MM' GROUP BY encryption_status; # Get encryption status for report dates in the provided range. SELECT dt, encryption_status, count(*) FROM your-table-name WHERE dt > 'YYYY-MM-DD-HH-MM' AND dt < 'YYYY-MM-DD-HH-MM' GROUP BY dt, encryption_status;

有关使用 Athena,参见 Amazon Athena 用户指南.

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