适用于 Cloud Storage 的 Pub/Sub 通知

设置

本页面简要介绍了适用于 Cloud Storage 的 Pub/Sub 通知。

概览

Pub/Sub 通知功能可以将存储桶中对象的相关更改信息发送到 Pub/Sub，Pub/Sub 随后会将这些信息以消息的形式添加到您选择的 Pub/Sub 主题中。例如，您可以跟踪在存储桶中创建和删除的对象。 每个通知都包含说明触发该通知的事件以及发生更改的对象的信息。

您可以向您具有足够权限的任何项目中的任何 Pub/Sub 主题发送通知。Pub/Sub 主题收到通知后，该主题的订阅者可以收到关联的消息。如需了解如何将 Cloud Storage 存储桶连接到 Pub/Sub 主题，请参阅前提条件。

其他通知选项

如需触发提醒和操作以响应存储桶中的更改，通用方法是订阅 Pub/Sub 通知。您还可以使用以下选项：

  • Cloud Run functions：如果您只想触发轻量级的独立函数来响应事件，并且不想管理 Pub/Sub 主题，可以使用 Cloud Run functions。Cloud Run functions 可让您在存储桶中的对象发生更改时执行 C#、Go、Java、Node.js、Python、PHP 和 Ruby 函数。请注意，您的存储桶必须与 Cloud Run functions 位于同一项目中。如需查看将 Cloud Run functions 与 Cloud Storage 搭配使用的演示，请参阅相关教程。

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

通知配置

通知配置是您附加到存储桶的规则，该规则可以指定以下内容：

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

您可以将多个通知配置附加到存储桶。存储桶最多可以总共有 100 个通知配置，并且最多可将 10 个通知配置设置为针对特定事件触发。

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

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

  • 创建通知配置时。
  • 列出附加到存储桶的通知配置时。
  • 在通知配置触发的每个通知的 notificationConfig 特性 (attribute) 中。

创建和删除通知配置会使存储桶的元数据世代编号递增。

事件类型

Cloud Storage 支持的事件类型的列表如下：

事件类型 说明
OBJECT_FINALIZE 在存储桶中成功创建新对象（或现有对象的新世代）时，将发送此事件。这包括复制、重写或恢复现有对象。上传失败不会触发此事件。
OBJECT_METADATA_UPDATE 在现有对象的元数据发生更改时，将发送此事件。
OBJECT_DELETE 此事件在对象被永久删除时发送。这包括系统根据存储桶的生命周期配置所替换或删除的对象。这不包括非当前对象（请参阅 OBJECT_ARCHIVE）或中止分段上传的对象。
OBJECT_ARCHIVE 仅在存储桶已启用对象版本控制时发送此事件。此事件表明某个对象的当前版本已成为非当前版本，原因可能是该对象已明确设为非当前对象，或者已被新上传的同名对象替换。

对于其他 Cloud Storage 事件（例如存储桶操作或对象读取），您可以在 Cloud Audit Logs 中启用适当的审核日志类型，并使用过滤条件将审核日志路由到 Pub/Sub。

替换对象

使用同名的新对象替换现有对象时，会触发两个独立事件：OBJECT_FINALIZE（针对对象的新版本），以及 OBJECT_ARCHIVE 或 OBJECT_DELETE（针对被替换的对象）。OBJECT_FINALIZE 事件包含 overwroteGeneration 附加特性，该特性提供所替换对象的世代编号。OBJECT_ARCHIVE 或 OBJECT_DELETE 事件包含 overwrittenByGeneration 附加特性，该特性提供新对象的世代编号。

通知格式

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

  • 特性：一组键值对，用于描述事件。
  • 载荷：包含已更改对象的元数据的字符串。

属性

特性是指 Cloud Storage 发送到 Pub/Sub 主题的所有通知中包含的键值对。无论通知的载荷如何，通知始终包含下列一组键值对：

属性名称 示例 说明
notificationConfig projects/_/buckets/foo/notificationConfigs/3 触发此通知的通知配置的标识符。
eventType OBJECT_FINALIZE 刚刚发生的事件的类型。要查看可能的值的列表，请参阅事件类型。
payloadFormat JSON_API_V1 对象负载的格式。要查看可能的值的列表，请参阅载荷。
bucketId foo 包含发生更改的对象的存储桶的名称。
objectId bar 发生更改的对象的名称。
objectGeneration 123456 发生更改的对象的世代编号。
eventTime 2021-01-15T01:30:15.01Z 事件发生的时间，以 RFC 3339 格式表示。

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

属性名称 示例 说明
overwrittenByGeneration 107458 新对象（替换了此通知涉及的对象）的世代编号。如果发生替换，此特性仅出现在 OBJECT_ARCHIVE 或 OBJECT_DELETE 事件中。
overwroteGeneration 352947 被替换的对象（被此通知涉及的对象替换）的世代编号。如果发生替换，此特性仅出现在 OBJECT_FINALIZE 事件中。

除了上述特性外，通知配置还可以最多包含 10 个自定义特性。自定义属性是在创建通知配置时在 gcloud storage 命令中使用 --custom-attributes 或在 POST notificationConfigs JSON 请求正文中使用 custom_attributes 对象定义的。

载荷

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

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

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

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

送达保证

添加通知配置后，Cloud Storage 可能最多需要 30 秒时间，才能开始发送与该配置关联的通知。启动通知配置后，Cloud Storage 保证至少向 Pub/Sub 送达一次通知。Pub/Sub 也会向收件人至少送达一次通知，这意味着，您可能会收到多条消息，这些消息具有多个 ID，但它们均代表同一 Cloud Storage 事件。

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

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

后续步骤