Amazon Simple Storage Service
开发人员指南 (API Version 2006-03-01)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

配置 Amazon S3 事件通知

通过 Amazon S3 通知功能,您可以在存储桶中发生某些事件时接收通知。要启用通知,您必须首先添加通知配置,标识希望 Amazon S3 发布的事件以及希望 Amazon S3 将事件通知发送到的目的地。您可以将此配置存储在与存储桶关联的通知子资源中 (请参阅 存储桶配置选项)。Amazon S3 提供了一个 API,用于管理此子资源。

概述

目前,Amazon S3 可以发布以下事件:

  • 新对象创建事件 - Amazon S3 支持多个创建对象的 API。您可以在仅使用特定 API (例如 s3:ObjectCreated:Put) 时请求通知,或在创建对象时使用通配符 (例如 s3:ObjectCreated:*) 请求通知,而不管使用的 API 是什么。

  • 对象删除事件 - Amazon S3 支持对受版本控制和不受版本控制的对象的删除。有关对象版本控制的更多信息,请参阅对象版本控制使用版本控制

    您可以使用 s3:ObjectRemoved:Delete 事件类型请求在删除对象或永久删除受版本控制的对象时收到通知。或者,也可以使用 s3:ObjectRemoved:DeleteMarkerCreated 请求在为受版本控制的对象创建删除标记时收到通知。您还可以使用通配符 s3:ObjectRemoved:* 来请求在每次删除对象时收到通知。有关删除受版本控制的对象的信息,请参阅删除数据元版本

  • 低冗余存储 (RRS) 对象丢失事件 - Amazon S3 在检测到 RRS 存储类别的对象已丢失时发送通知消息。

有关受支持的事件类型的列表,请参阅受支持的事件类型

Amazon S3 支持它可以在其中发布事件的以下目标:

  • Amazon Simple Notification Service (Amazon SNS) 主题

    Amazon SNS 是一项灵活且完全托管的消息推送服务。使用此服务,您可以将消息推送到移动设备或分布式服务。通过 SNS,您只需要发布一次消息,就能将其发送无数遍。SNS 主题是收件人可动态订阅以接收事件通知的接入点。有关 SNS 的更多信息,请参阅 Amazon SNS 产品详细信息页。

  • Amazon Simple Queue Service (Amazon SQS) 队列

    Amazon SQS 是一项可扩展且完全托管的消息排队服务。您可以使用 SQS 来传输任何容量的数据,而不需要其他服务始终可用。在您的通知配置中,您可以请求 Amazon S3 将事件发布到 SQS 队列。有关 SQS 的更多信息,请参阅 Amazon SQS 产品详细信息页。

  • AWS Lambda

    AWS Lambda 是一项计算服务,它使您可以轻松地构建快速响应新信息的应用程序。AWS Lambda 运行您的代码以响应事件,例如图像上传、应用程序内活动、网站单击或连接设备的输出。您可以使用 AWS Lambda 通过自定义逻辑扩展其他 AWS 服务,或创建您自己的按 AWS 规模、性能和安全性运行的后端。通过 AWS Lambda,您可以轻松创建单独的事件驱动的应用程序,这些应用程序仅在需要时执行并可自动从每天几个请求扩展到每秒数千个请求。

    AWS Lambda 可以运行自定义代码以响应 Amazon S3 存储桶事件。您将自定义代码上传到 AWS Lambda 并创建所谓的 Lambda 函数。当 Amazon S3 检测到特定类型的事件 (例如,对象创建的事件) 时,它可以将该事件发布到 AWS Lambda 并在 Lambda 中调用您的函数。作为响应,AWS Lambda 将执行您的函数。有关更多信息,请参阅 AWS Lambda 产品详细信息页。

以下部分提供有关如何在存储桶上启用事件通知的更多详细信息。副主题还提供了示例演练以帮助您探索通知功能。

如何启用事件通知

启用通知是存储桶级别的操作;即,您将通知配置信息存储在与存储桶关联的通知 子资源中。您可以使用以下任意方法来管理通知配置:

  • 使用 Amazon S3 控制台

    控制台 UI 允许您在存储桶上设置通知配置,而无需编写任何代码。有关说明,请参阅如何为 S3 存储桶启用和配置事件通知? (在 Amazon Simple Storage Service 控制台用户指南 中)。

  • 使用 AWS 开发工具包以编程方式管理

    注意

    如果需要,也可以直接从代码中调用 Amazon S3 REST API。但是,这可能会比较繁琐,因为需要您编写代码对请求进行身份验证。

    在内部,控制台和开发工具包都调用 Amazon S3 REST API 来管理与存储桶关联的通知 子资源。有关使用 AWS 开发工具包管理通知配置的示例,请参阅前一部分中提供的演练链接。

    无论您使用哪种方法,Amazon S3 都将通知配置作为 XML 存储在与存储桶关联的通知 子资源中。有关存储桶子资源的信息,请参阅存储桶配置选项。默认情况下,不为任何类型的事件启用通知。因此,通知 子资源最初存储空配置。

    Copy
    <NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> </NotificationConfiguration>

    要为特定类型的事件启用通知,请将 XML 替换为适当的配置,该配置可标识您希望 Amazon S3 发布的事件类型和您希望将事件发布到的目标。对于每个目标,添加相应的 XML 配置。例如:

    • 将事件消息发布到 SQS 队列 一 要将 SQS 队列设置为一个或多个事件类型的通知目标,请添加 QueueConfiguration

      Copy
      <NotificationConfiguration> <QueueConfiguration> <Id>optional-id-string</Id> <Queue>sqs-queue-arn</Queue> <Event>event-type</Event> <Event>event-type</Event> ... </QueueConfiguration> ... </NotificationConfiguration>
    • 将事件消息发布到 SNS 主题 一 要将 SNS 主题设置为特定事件类型的通知目标,请添加 TopicConfiguration

      Copy
      <NotificationConfiguration> <TopicConfiguration> <Id>optional-id-string</Id> <Topic>sns-topic-arn</Topic> <Event>event-type</Event> <Event>event-type</Event> ... </TopicConfiguration> ... </NotificationConfiguration>
    • 调用 AWS Lambda 函数并提供一个事件消息作为参数 - 要将 Lambda 函数设置为特定事件类型的通知目标,请添加 CloudFunctionConfiguration

      Copy
      <NotificationConfiguration> <CloudFunctionConfiguration>    <Id>optional-id-string</Id>    <Cloudcode>cloud-function-arn</Cloudcode>         <Event>event-type</Event>       <Event>event-type</Event>       ...   </CloudFunctionConfiguration> ... </NotificationConfiguration>

    要移除存储桶上配置的所有通知,请在通知 子资源中保存一个空 <NotificationConfiguration/> 元素。

    当 Amazon S3 检测到特定类型的事件时,它会发布包含事件信息的消息。有关更多信息,请参阅 事件消息结构

事件通知类型和目标

本部分介绍 Amazon S3 支持的事件通知类型和可在其中发布通知的目标的类型。

受支持的事件类型

Amazon S3 可以发布以下类型的事件。您在通知配置中指定这些事件类型。

事件类型 描述

s3:ObjectCreated:*

s3:ObjectCreated:Put

s3:ObjectCreated:Post

s3:ObjectCreated:Copy

s3:ObjectCreated:CompleteMultipartUpload

诸如 PUT、POST 和 COPY 之类的 Amazon S3 API 可以创建对象。使用这些事件类型,您可以在使用特定 API 创建对象时启用通知,也可以使用 s3:ObjectCreated:* 事件类型请求通知,而无论使用什么 API 创建对象。

您不会从失败的操作收到事件通知。

s3:ObjectRemoved:*

s3:ObjectRemoved:Delete

s3:ObjectRemoved:DeleteMarkerCreated

通过使用 ObjectRemoved 事件类型,您可以在从存储桶中删除一个对象或一批对象时启用通知。

您可以使用 s3:ObjectRemoved:Delete 事件类型请求在删除对象或永久删除受版本控制的对象时收到通知。或者,也可以使用 s3:ObjectRemoved:DeleteMarkerCreated 请求在为受版本控制的对象创建删除标记时收到通知。有关删除受版本控制的对象的信息,请参阅删除数据元版本。您还可以使用通配符 s3:ObjectRemoved:* 来请求在每次删除对象时收到通知。

您不会从生命周期策略中的自动删除或失败的操作收到事件通知。

s3:ReducedRedundancyLostObject 您可以使用此事件类型来请求 Amazon S3 在 Amazon S3 检测到 RRS 存储类别的对象丢失时发送通知消息。

受支持的目标

Amazon S3 可以将事件通知消息发送到以下目标。您在通知配置中指定这些目标的 ARN 值。

  • 将事件消息发布到 Amazon Simple Notification Service (Amazon SNS) 主题

  • 将事件消息发布到 Amazon Simple Queue Service (Amazon SQS) 队列

    注意

    目前,S3 只支持不启用服务器端加密 (SSE) 的标准 SQS 队列。

  • 通过调用 Lambda 函数并提供事件消息作为参数来将事件消息发布到 AWS Lambda

您必须授予 Amazon S3 将消息发布到 Amazon SNS 主题或 Amazon SQS 队列的权限。您还必须授予 Amazon S3 权限以代表您调用 AWS Lambda 函数。有关授予这些权限的信息,请参阅授予将事件通知消息发布到目标的权限

使用对象键名称筛选配置通知

您可以将通知配置为按对象的键名称的前缀和后缀进行筛选。例如,您可以设置一个配置,以便仅在将带有“.jpg”扩展名的图像文件添加到存储桶时收到通知。或者,您也可以设置一个配置,该配置仅在将带有前缀“images/”的对象添加到存储桶时将通知发送到 Amazon SNS 主题,同时将同一存储桶中带有前缀“logs/”的对象的通知发送到 AWS Lambda 函数。

您可以在 Amazon S3 控制台中以及通过 AWS 开发工具包使用 Amazon S3 API 或直接使用 REST API,设置使用对象键名称筛选的通知配置。有关使用控制台 UI 在存储桶上的设置通知配置的信息,请参阅如何为 S3 存储桶启用和配置事件通知? (在 Amazon Simple Storage Service 控制台用户指南 中)。

Amazon S3 在与存储桶关联的通知子资源中以 XML 形式存储通知配置,如如何启用事件通知 中所述。您使用 Filter XML 结构定义要按对象键名称的前缀和后缀进行筛选的通知的规则。有关 Filter XML 结构的详细信息,请参阅 Amazon Simple Storage Service API Reference 中的 PUT Bucket 通知

使用 Filter 的通知配置无法定义采用重叠前缀、重叠后缀或前缀和后缀重叠的筛选规则。以下部分包含采用对象键名称筛选的有效通知配置的示例以及因前缀/后缀重叠而失效的通知配置的示例。

采用对象键名称筛选的有效通知配置的示例

以下通知配置包含用于标识 Amazon S3 的 Amazon SQS 队列以发布 s3:ObjectCreated:Put 类型的事件的队列配置。每当具有前缀 images/ 和后缀 jpg 的对象被放置 (PUT) 到存储桶时,就会发布这些事件。

Copy
<NotificationConfiguration> <QueueConfiguration> <Id>1</Id> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>images/</Value> </FilterRule> <FilterRule> <Name>suffix</Name> <Value>jpg</Value> </FilterRule> </S3Key> </Filter> <Queue>arn:aws-cn:sqs:us-west-2:444455556666:s3notificationqueue</Queue> <Event>s3:ObjectCreated:Put</Event> </QueueConfiguration> </NotificationConfiguration>

以下通知配置有多个非重叠前缀。该配置做出以下定义:images/ 文件夹中针对 PUT 请求的通知将进入队列 A,logs/ 文件夹中针对 PUT 请求的通知将进入队列 B。

Copy
<NotificationConfiguration> <QueueConfiguration> <Id>1</Id> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>images/</Value> </FilterRule> </S3Key> </Filter> <Queue>arn:aws-cn:sqs:us-west-2:444455556666:sqs-queue-A</Queue> <Event>s3:ObjectCreated:Put</Event> </QueueConfiguration> <QueueConfiguration> <Id>2</Id> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>logs/</Value> </FilterRule> </S3Key> </Filter> <Queue>arn:aws-cn:sqs:us-west-2:444455556666:sqs-queue-B</Queue> <Event>s3:ObjectCreated:Put</Event> </QueueConfiguration> </NotificationConfiguration>

以下通知配置有多个非重叠后缀。该配置做出以下定义:所有新添加到存储桶的 .jpg 图像都由 Lambda 云函数 A 处理,所有新添加的 .png 图像都由云函数 B 处理。后缀 .png 和 .jpg 是不重叠的,即使它们的最后一个字母相同。如果某个给定的字符串能够以这两个后缀结尾,则将它们视为重叠。一个字符串无法同时以 .png 和 .jpg 结尾,因此示例配置中的后缀不是重叠后缀。

Copy
<NotificationConfiguration> <CloudFunctionConfiguration> <Id>1</Id> <Filter> <S3Key> <FilterRule> <Name>suffix</Name> <Value>.jpg</Value> </FilterRule> </S3Key> </Filter> <Cloudcode>arn:aws-cn:lambda:us-west-2:444455556666:cloud-function-A</Cloudcode> <Event>s3:ObjectCreated:Put</Event> </CloudFunctionConfiguration> <CloudFunctionConfiguration> <Id>2</Id> <Filter> <S3Key> <FilterRule> <Name>suffix</Name> <Value>.png</Value> </FilterRule> </S3Key> </Filter> <Cloudcode>arn:aws-cn:lambda:us-west-2:444455556666:cloud-function-B</Cloudcode> <Event>s3:ObjectCreated:Put</Event> </CloudFunctionConfiguration> </NotificationConfiguration>

使用 Filter 的通知配置不能使用重叠前缀为相同的事件类型定义筛选规则,除非重叠前缀与不重叠的后缀一起使用。以下示例配置显示了如何将使用通用前缀和非重叠后缀创建的对象传递到其他目标。

Copy
<NotificationConfiguration> <CloudFunctionConfiguration> <Id>1</Id> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>images</Value> </FilterRule> <FilterRule> <Name>suffix</Name> <Value>.jpg</Value> </FilterRule> </S3Key> </Filter> <Cloudcode>arn:aws-cn:lambda:us-west-2:444455556666:cloud-function-A</Cloudcode> <Event>s3:ObjectCreated:Put</Event> </CloudFunctionConfiguration> <CloudFunctionConfiguration> <Id>2</Id> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>images</Value> </FilterRule> <FilterRule> <Name>suffix</Name> <Value>.png</Value> </FilterRule> </S3Key> </Filter> <Cloudcode>arn:aws-cn:lambda:us-west-2:444455556666:cloud-function-B</Cloudcode> <Event>s3:ObjectCreated:Put</Event> </CloudFunctionConfiguration> </NotificationConfiguration>

采用无效前缀/后缀重叠的通知配置的示例

在大多数情况下,使用 Filter 的通知配置无法使用重叠前缀、重叠后缀或前缀和后缀的重叠组合为相同的事件类型定义筛选规则。 (只要后缀不重叠,您就可以采用重叠前缀。有关示例,请参阅 使用对象键名称筛选配置通知。)

您可以将重叠对象键名称筛选用于不同的事件类型。例如,您可以创建一个通知配置,该配置将前缀 image/ 用于 ObjectCreated:Put 事件类型并将前缀 image/ 用于 ObjectDeleted:* 事件类型。

在使用 AWS Amazon S3 控制台或 Amazon S3 API 时,如果您尝试保存具有对相同的活动类型无效的重叠名称筛选的通知配置,则会出现错误。此部分显示了因重叠名称筛选而失效的通知配置的示例。

任何现有通知配置规则都被假定为具有与任何其他前缀和后缀分别匹配的默认前缀和后缀。以下通知配置因具有重叠前缀而失效,其中的根前缀与任何其他前缀重叠。(如果我们在此示例中使用后缀而不是前缀,则会发生同样的情况。根后缀与任何其他后缀重叠。)

Copy
<NotificationConfiguration> <TopicConfiguration> <Topic>arn:aws-cn:sns:us-west-2:444455556666:sns-notification-one</Topic> <Event>s3:ObjectCreated:*</Event> </TopicConfiguration> <TopicConfiguration> <Topic>arn:aws-cn:sns:us-west-2:444455556666:sns-notification-two</Topic> <Event>s3:ObjectCreated:*</Event> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>images</Value> </FilterRule> </S3Key> </Filter> </TopicConfiguration> </NotificationConfiguration>

由于具有重叠后缀,以下通知配置无效。如果某个给定的字符串能够以这两个后缀结尾,则将它们视为重叠。一个字符串能够以 jpgpg 结尾,因此后缀是重叠的。(对于前缀,此结论也成立,如果给定字符串能够以两个前缀开头,则认为它们是重叠的。)

Copy
<NotificationConfiguration> <TopicConfiguration> <Topic>arn:aws-cn:sns:us-west-2:444455556666:sns-topic-one</Topic> <Event>s3:ObjectCreated:*</Event> <Filter> <S3Key> <FilterRule> <Name>suffix</Name> <Value>jpg</Value> </FilterRule> </S3Key> </Filter> </TopicConfiguration> <TopicConfiguration> <Topic>arn:aws-cn:sns:us-west-2:444455556666:sns-topic-two</Topic> <Event>s3:ObjectCreated:Put</Event> <Filter> <S3Key> <FilterRule> <Name>suffix</Name> <Value>pg</Value> </FilterRule> </S3Key> </Filter> </TopicConfiguration> </NotificationConfiguration

由于具有重叠前缀和后缀,以下通知配置无效。

Copy
<NotificationConfiguration> <TopicConfiguration> <Topic>arn:aws-cn:sns:us-west-2:444455556666:sns-topic-one</Topic> <Event>s3:ObjectCreated:*</Event> <Filter> <S3Key> <FilterRule> <Name>prefix</Name> <Value>images</Value> </FilterRule> <FilterRule> <Name>suffix</Name> <Value>jpg</Value> </FilterRule> </S3Key> </Filter> </TopicConfiguration> <TopicConfiguration> <Topic>arn:aws-cn:snsus-west-2:444455556666:sns-topic-two</Topic> <Event>s3:ObjectCreated:Put</Event> <Filter> <S3Key> <FilterRule> <Name>suffix</Name> <Value>jpg</Value> </FilterRule> </S3Key> </Filter> </TopicConfiguration> </NotificationConfiguration>

授予将事件通知消息发布到目标的权限

在 Amazon S3 可以将消息发布到目标之前,您必须授予 Amazon S3 委托人调用相关 API 以将消息发布到 SNS 主题、SQS 队列或 Lambda 函数所需的权限。

授予调用 AWS Lambda 函数的权限

Amazon S3 通过调用 Lambda 函数并提供事件消息作为参数来将事件消息发布到 AWS Lambda。

使用 Amazon S3 控制台在 Amazon S3 存储桶上为 Lambda 函数配置事件通知时,Amazon S3 控制台将在 Lambda 函数上设置必要的权限以便 Amazon S3 有权从存储桶调用函数。有关更多信息,请参阅如何为 S3 存储桶启用和配置事件通知? (在 Amazon Simple Storage Service 控制台用户指南 中)。

您还可以从 AWS Lambda 授予 Amazon S3 权限以调用您的 Lambda 函数。有关更多信息,请参阅 AWS Lambda Developer Guide 中的教程:将 AWS Lambda 与 Amazon S3 一起使用

授予将消息发布到 SNS 主题或 SQS 队列的权限

将 IAM 策略附加到目标 SNS 主题或 SQS 队列以授予 Amazon S3 将消息发布到 SNS 主题或 SQS 队列的权限。

附加到目标 SNS 主题的 IAM 策略示例。

Copy
{ "Version": "2008-10-17", "Id": "example-ID", "Statement": [ { "Sid": "example-statement-ID", "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": [ "SNS:Publish" ], "Resource": "SNS-ARN", "Condition": { "ArnLike": {         "aws:SourceArn": "arn:aws-cn:s3:*:*:bucket-name" } } } ] }

附加到目标 SQS 队列的 IAM 策略示例。

Copy
{ "Version": "2008-10-17", "Id": "example-ID", "Statement": [ { "Sid": "example-statement-ID", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "SQS:SendMessage" ], "Resource": "SQS-ARN", "Condition": { "ArnLike": {         "aws:SourceArn": "arn:aws-cn:s3:*:*:bucket-name" } } } ] }

请注意,对于 Amazon SNS 和 Amazon SQS IAM 策略,您可以在策略中指定 StringLike 条件而不是 ArnLike 条件。

Copy
"Condition": {        "StringLike": {         "aws:SourceArn": "arn:aws-cn:s3:*:*:bucket-name"        } }

有关如何将策略附加到 SNS 主题或 SQS 队列的示例,请参阅 示例演练 1:为存储桶配置通知 (消息目标:SNS 主题和 SQS 队列)

有关权限的更多信息,请参阅以下主题: