Amazon Simple Storage Service
开发人员指南 (API Version 2006-03-01)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

Amazon S3 清单

Amazon S3 清单是 Amazon S3 提供的用于帮助管理您的存储的工具之一。您可以使用 Amazon S3 清单简化和加快业务工作流和大数据作业,这将有计划地取代 Amazon S3 同步列表 API 操作。Amazon S3 清单将针对 S3 存储桶或共享前缀 (即,其名称以通用字符串开头的对象),每天或每周提供您的对象及其对应元数据的逗号分隔值 (CSV) 平面文件输出。

您可以配置要包含在该清单中的对象元数据,是列出所有对象版本还是仅列出当前版本,要存储清单列表平面文件输出的位置以及是每天还是每周生成该清单。您可以为一个存储桶配置多个清单列表。有关定价的信息,请参阅 Amazon S3 定价

我如何设置 Amazon S3 清单?

本节通过描述清单源存储桶和目标存储桶然后提供设置清单的步骤来介绍如何设置 Amazon S3 清单。

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

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

源存储桶

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

源存储桶:

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

  • 包含清单的配置。

目标存储桶

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

目标存储桶:

  • 包含清单平面文件列表。

  • 包含 manifest.json 文件,该文件列出了存储在目标存储桶中的所有平面文件清单。有关更多信息,请参阅 什么是库存清单?

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

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

  • 可以与源存储桶相同。

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

设置 Amazon S3 清单

Amazon S3 清单将帮助您按预定的计划创建 S3 存储桶中的对象的列表,由此管理存储。清单列表将发布到目标存储桶中的平面文件。

为 S3 存储桶设置 Amazon S3 清单

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

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

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

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

    • 有关如何在 AWS 管理控制台中执行此操作的信息,请参阅如何配置 Amazon S3 清单? (在 Amazon Simple Storage Service 控制台用户指南 中)。

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

Amazon S3 清单中包含了什么?

清单列表平面文件包含源存储桶中的对象的列表以及每个对象的元数据。清单列表将作为使用 GZIP 压缩的逗号分隔值 (CSV) 文件存储在目标存储桶中。

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

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

  • Key name – 唯一地标识存储桶中的对象的对象键名称 (或键)。

  • 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.有关更多信息,请参阅如何查找对象的复制状态

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

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

清单一致性

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

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

清单列表位于何处?

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

Copy
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 为了防止从同一源存储桶发送到同一目标存储桶的多个清单报告发生冲突而添加。

  • YYYY-MM-DDTHH-MMZ 是生成清单列表的日期。例如:2016-11-06T21-32Z

  • manifest.json 是清单文件。

  • manifest.checksum 是 manifest.json 文件的内容的 MD5。

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

Copy
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 是清单列表文件之一。

什么是库存清单?

清单提供了元数据和有关库存列表的其他基本信息,包括源存储桶名称、目标存储桶名称、库存列表的版本、库存列表平面文件的格式和架构以及库存列表文件的实际列表。

每个库存都有一个清单,该清单包含在列出了目标存储桶中的清单列表的 manifest.json 文件中。每当写入 manifest.json 文件后,它都会附带一个 manifest.checksum 文件 (作为 manifest.json 文件的内容的 MD5)。每当新列表写入目标存储桶时,清单就会更新。

下面是 manifest.json 文件的示例。

Copy
{ "sourceBucket": "example-source-bucket", "destinationBucket": "example-inventory-destination-bucket", "version": "2016-11-30", "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 } ] }

我如何知道库存是否完成?

您可以设置 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 处理。

Copy
<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 S3 清单的 REST 操作。