Cloud Pub/Sub Notifications for Cloud Storage

本页面概述了 Cloud Pub/Sub Notifications for Cloud Storage。要了解如何设置和使用 Cloud Pub / Sub Notifications,请参阅登记对象更改

概览

Cloud Pub/Sub Notifications 将存储分区中对象的相关更改信息发送到 Cloud Pub/Sub(随后,信息以消息的形式添加到您选择的 Cloud Pub/Sub 主题中)。例如,您可以跟踪存储分区中创建和删除的对象。每个通知都包含相应的信息,这些信息说明了触发通知的事件以及发生更改的对象。

您可以向您具有足够权限的任何项目中的任何 Cloud Pub/Sub 主题发送通知。Cloud Pub/Sub 主题收到通知生成的消息后,系统可以将这些消息发送给该主题的任意数量的订阅者。要了解如何将 Cloud Storage 存储分区连接到 Cloud Pub/Sub 主题,请参阅前提条件

其他通知选项

要触发提醒和操作以响应存储分区中的更改,通用的做法是订阅 Cloud Pub/Sub Notifications。您还可以使用以下选项:

  • Cloud Functions:如果您只想触发轻量级的独立函数来响应事件并且不想管理 Cloud Pub/Sub 主题,请使用 Cloud Functions。Cloud Functions 允许您在存储分区中的对象发生更改时执行 JavaScript 函数。请注意,您的存储分区必须与 Cloud Functions 位于同一项目中。要通过演示了解如何结合使用 Cloud Functions 和 Cloud Storage,请参阅相关教程

  • 对象更改通知:对象更改通知是 Cloud Storage 中用于生成通知的独立功能(一种旧功能)。此功能将 HTTPS 消息发送到您单独设置的客户端应用。通常,Cloud Pub/Sub Notifications 更加便宜、更易于使用且更加灵活。

通知配置

通知配置是附加到存储分区上的规则,该规则指定了以下内容:

  • Cloud Pub/Sub 中接收通知的主题。
  • 触发发送通知的事件。
  • 通知中包含的信息。

您可以将多个通知配置附加到存储分区上。对于每个事件,最多可以设置 10 个通知配置来触发通知。

例如,如果您具有一个通知配置(向一个 Cloud Pub/Sub 主题发送删除通知),您可以向存储分区添加第二个通知配置(向另一个主题发送删除通知)。但是,如果您尝试创建 10 个以上执行此操作的通知配置,则会收到错误。除了这些通知配置之外,您还可以创建其他通知配置,以便将其他事件(例如对象创建)的通知发送到删除通知所使用的 Cloud Pub/Sub 主题或其他主题中。

每个通知配置都由一个整数进行标识。在以下情况下,将返回此整数:

  • 创建通知配置时,将返回此整数。
  • 列出附加到存储分区上的通知配置时,将返回此整数。
  • 在通知配置触发的每个通知的 notificationConfig 属性中,将返回此整数。

创建和删除通知配置会增加存储分区的元数据世代编号。

事件类型

Cloud Storage 当前支持的事件类型的列表如下:

事件类型 说明
OBJECT_FINALIZE 在存储分区中成功创建新对象(或现有对象的新世代)时,将发送此事件。这包括复制或重写现有的对象。如果上传失败,则不会触发此事件。
OBJECT_METADATA_UPDATE 在现有对象的元数据发生更改时,将发送此事件。
OBJECT_DELETE 在永久删除对象时,将发送此事件。这包括在存储分区的生命周期配置过程中被覆盖或删除的对象。对于已启用对象版本控制的存储分区,如果某个对象已归档(请参阅 OBJECT_ARCHIVE),则系统不会发送此事件,即使通过 storage.objects.delete 方法进行归档也是如此。
OBJECT_ARCHIVE 仅在存储分区已启用对象版本控制时发送此事件。此事件表明某个对象的当前活动版本已成为归档版本,原因可能是它被归档了,或者有新上传的同名对象导致它被覆盖了。

覆盖对象

使用同名的新对象覆盖现有对象时,会触发两个单独的事件:对于对象的新版本,触发 OBJECT_FINALIZE,对于被覆盖的对象,触发 OBJECT_ARCHIVEOBJECT_DELETEOBJECT_FINALIZE 事件将包含一个额外的属性 overwroteGeneration(提供了被覆盖的对象的世代编号)。OBJECT_ARCHIVEOBJECT_DELETE 事件将包含一个附加属性 overwrittenByGeneration(提供了新对象的世代编号)。

通知格式

发送到 Cloud Pub/Sub 主题的通知由以下两部分组成:

  • 属性:描述事件的一组键值对。
  • 负载:包含已更改对象的元数据的字符串。

属性

属性是指 Cloud Storage 发送到您的 Cloud Pub/Sub 主题的所有通知中包含的键值对。无论通知的负载如何,通知始终包含下列键值对。

属性名称 示例 说明
notificationConfig projects/_/buckets/foo/notificationConfigs/3 触发此通知的通知配置的标识符。
eventType OBJECT_FINALIZE 刚刚发生的事件的类型。要查看可能的值的列表,请参阅事件类型
payloadFormat JSON_API_V1 对象负载的格式。要查看可能的值的列表,请参阅负载
bucketId foo 包含发生更改的对象的存储分区的名称。
objectId bar 发生更改的对象的名称。
objectGeneration 123456 发生更改的对象的世代编号。

无论通知的负载如何,通知有时会包含下列键值对。

属性名称 示例 说明
overwrittenByGeneration 107458 新对象(覆盖了此通知涉及的对象)的世代编号。如果发生覆盖,此属性仅出现在 OBJECT_ARCHIVEOBJECT_DELETE 事件中。
overwroteGeneration 352947 被覆盖的对象(被此通知涉及的对象覆盖)的世代编号。如果发生覆盖,此属性仅出现在 OBJECT_FINALIZE 事件中。

以下键值对已被弃用。系统不会为新订阅显示该属性,2018 年 6 月 1 日之后,该属性不会出现在任何订阅中:

属性名称 示例 说明
资源 projects/_/buckets/foo/objects/bar#123456 发生更改的 Cloud Storage 对象的路径。

除上述属性外,通知还可以包含自定义属性。创建通知配置时,通过在 gsutil notification 命令中使用 -m 标志或在 POST notificationConfigs JSON 请求的正文中使用 custom_attributes 对象定义这些属性。

负载

负载是一个字符串,其中包含发生更改的对象的元数据。当您创建通知配置时,您会指定由该配置触发的通知中包含的负载类型。您可以指定以下类型的负载:

负载类型 说明
通知中不包含负载。
JSON_API_V1 负载是一个 UTF-8 字符串,其中包含以资源表示法显示的对象元数据

对于 OBJECT_DELETE 通知,负载中包含的元数据代表的是删除前的对象元数据,以及附加的 timeDeleted 属性。对于所有其他通知,负载中包含的元数据代表发生更改后的对象元数据。

例如,假设您有一个负责跟踪 OBJECT_METADATA_UPDATE 事件的通知配置。如果用户将对象的 contentType 属性从 binary/octet-stream 更改为 video/mp4,则发送 OBJECT_METADATA_UPDATE 通知,并且负载中的元数据包含 "contentType":"video/mp4"

送达保证

添加通知配置后,Cloud Storage 可能最多需要 30 秒时间,才能开始发送与该配置关联的通知。启动通知配置后,Cloud Storage 保证至少向 Cloud Pub/Sub 送达一次通知。Cloud Pub/Sub 也会向收件人至少送达一次通知,这意味着,您可能会收到多条消息,这些消息具有多个 ID,但它们均代表同一 Cloud Storage 事件。目前我们没有为递送时间提供服务等级协议 (SLA),但通常,通知会在几秒内送达。在极少数情况下,通知可能会延迟很长时间。

我们不保证按照 Cloud Pub/Sub 接收通知的顺序发布通知。如果您计划根据通知修改 Cloud Storage 对象,建议您在更新请求中使用对象的世代编号和元数据世代编号作为前提条件。

如果通知始终无法送达 Cloud Pub/Sub 主题,Cloud Storage 可能会在 7 天后删除通知。当 Cloud Pub/Sub 主题不再存在时、Cloud Storage 不再具有向主题发布通知的权限时或者拥有该主题的项目超出发布配额时,通知可能会递送失败。

后续步骤

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Cloud Storage
需要帮助?请访问我们的支持页面