本页面简要介绍了适用于 Cloud Storage 的 Pub/Sub 通知。
概览
Pub/Sub 通知功能可以将存储分区中对象的相关更改信息发送到 Pub/Sub，Pub/Sub 随后会将这些信息以消息的形式添加到您选择的 Pub/Sub 主题中。例如，您可以跟踪在存储分区中创建和删除的对象。 每个通知都包含说明触发该通知的事件以及发生更改的对象的信息。
您可以向您具有足够权限的任何项目中的任何 Pub/Sub 主题发送通知。Pub/Sub 主题收到通知后，该主题的订阅者可以收到关联的消息。如需了解如何将 Cloud Storage 存储分区连接到 Pub/Sub 主题，请参阅前提条件。
其他通知选项
如需触发提醒和操作以响应存储分区中的更改，通用方法是订阅 Pub/Sub 通知。您还可以使用以下选项：
- Cloud Functions：如果您只想触发轻量级的独立函数来响应事件，并且不想管理 Pub/Sub 主题，可以使用 Cloud Functions。Cloud Functions 可让您在存储桶中的对象发生更改时执行 C#、Go、Java、Node.js、Python、PHP 和 Ruby 函数。请注意，您的存储桶必须与 Cloud Functions 函数位于同一项目中。 如需查看将 Cloud 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 不再具有向主题发布通知的权限时或者拥有该主题的项目超出发布配额时，通知可能会递送失败。
后续步骤
- 配置适用于 Cloud Storage 的 Pub/Sub 通知
- 详细了解 Pub/Sub。
- 使用 Cloud Functions 函数通过 Cloud Storage 触发器传递事件。
- 使用 Pub/Sub 通知在 Cloud Storage 存储桶之间执行事件驱动型转移。