适用于 Cloud Storage 的 Cloud Pub/Sub 通知

本页面概述了适用于 Cloud Storage 的 Cloud Pub/Sub 通知。 如需了解如何设置和使用 Cloud Pub/Sub 通知,请参阅注册对象更改

概览

Cloud Pub/Sub 通知功能可以将存储分区中对象的相关更改信息发送到 Cloud Pub/Sub,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、Python 和 Go 函数。请注意,您的存储分区必须与 Cloud Functions 函数位于同一项目中。 如需查看将 Cloud Functions 与 Cloud Storage 搭配使用的演示,请参阅相关教程

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

通知配置

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

  • 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_DELETE(针对被覆盖的对象)。OBJECT_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 日之后的任何订阅中:

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

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

载荷

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

载荷类型 说明
NONE 通知中不会包含载荷。
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
需要帮助?请访问我们的支持页面