从对象更改通知迁移到 Pub/Sub 通知

本指南面向 Cloud Storage 已弃用的对象更改通知功能的用户。适用于 Cloud Storage 的 Pub/Sub 通知是用于生成可跟踪 Cloud Storage 存储桶中对象更改的通知的建议工具。Pub/Sub 通知在速度、灵活性、设置和成本效益方面都有所改进。本指南将说明对象更改通知与适用于 Cloud Storage 的 Pub/Sub 通知之间的差异，并提供从对象更改通知迁移到 Pub/Sub 通知的迁移步骤。

对象更改通知概览

对象更改通知是 Cloud Storage 中的一种旧版机制，用于向应用通知存储桶中的对象更改。设置对象更改通知后，每当添加、更新或删除对象时，Cloud Storage 都会向指定的应用网址发送 HTTP POST 请求 (webhook)。对象更改通知的建立方式是使用 JSON API、客户端库或 gsutil 通知 watchbucket 命令向 Cloud Storage 发送 watchAll 请求。不存在 pull 机制，您必须拥有由 HTTP 服务器提供支持的可公开访问的域名才能接收 webhook 消息。我们建议对新实现使用适用于 Cloud Storage 的 Pub/Sub 通知，因为它具有可靠性、可扩缩性和灵活性。

如需了解详情，请参阅对象更改通知。

Pub/Sub 通知概览

适用于 Cloud Storage 的 Pub/Sub 通知提供了一种可扩缩且可靠的现代方式，用于将事件信息发送到 Pub/Sub 主题，从而触发操作以响应 Cloud Storage 存储桶中的更改。Pub/Sub 以针对 webhook 的 HTTP POST 请求的形式提供基于推送的消息传送。当创建、更新或删除对象时，Cloud Storage 会将包含对象元数据的消息发布到指定的 Pub/Sub 主题，随后各种订阅方（例如 Cloud Run functions、数据流水线或微服务）可以使用这些消息，从而实现具有至少传送一次功能和强大错误处理功能的灵活的事件驱动型架构。

如需了解详情，请参阅适用于 Cloud Storage 的 Pub/Sub 通知。

将对象更改通知与 Pub/Sub 通知进行比较

下表将对象更改通知与 Pub/Sub 通知功能进行了比较：

功能 对象更改通知 Pub/Sub 通知
用途 当存储桶中的对象发生更改时，通过 HTTP POST 请求 (webhook) 直接通知应用。 将有关 Cloud Storage 存储桶中对象更改的信息发送到 Pub/Sub 主题。
传送机制 发送到指定应用网址的直接 HTTP POST (webhook)。 发布到 Pub/Sub 主题的消息随后可由各种订阅方（例如 Cloud Run functions、其他应用和数据流水线）使用。
可靠性 尝试进行可靠传送，但不保证及时性。通知可能会无限期延迟。 提供“至少传送一次”功能，这意味着消息可能会多次传送，但不会丢失。Pub/Sub 会处理消息持久性和重试。
可伸缩性 可扩缩性较差，因为它依赖于应用需要处理的直接 webhook。 可扩缩性较高，专为大规模事件处理而设计。
灵活性 仅限直接 webhook 集成。 高度灵活。Pub/Sub 消息可以触发 Cloud Run functions、馈送到数据流水线中 (Dataflow)，并由其他微服务使用。
过滤 无 在 Pub/Sub 订阅级提供强大的过滤选项，使订阅方可以仅接收符合特定条件的消息。
安全性 要求您的应用端点可公开访问 (HTTPS)。 Pub/Sub 提供 IAM，可对主题和订阅进行精细访问权限控制。无论您是直接拉取通知，还是将通知推送到公共端点，Pub/Sub 都有助于安全地传送消息。
复杂性 对于基本应用场景，设置可能比较简单，但管理可靠的传送和扩缩可能会变得很复杂。 需要了解 Pub/Sub 概念（主题、订阅），但可为事件驱动型架构提供更强大且更易于管理的解决方案。
弃用状态 已弃用。我们建议对新实现使用 Pub/Sub 通知。 在线。 这是用于 Cloud Storage 通知的主要方法，并且仍在积极开发中。
推荐使用场景 不建议用于新项目。主要用于无法迁移的较为简单的旧版集成。 强烈建议用于构建可应对 Cloud Storage 更改的强大且可扩缩的事件驱动型架构。

为什么要迁移到 Pub/Sub 通知？

从旧版对象更改通知迁移到 Pub/Sub 以接收 Cloud Storage 通知，是实现强大的事件管理的重要一步。建议在 Trusted Cloud中使用 Pub/Sub 实现事件驱动型架构，与对象更改通知相比，它在技术和运营方面具有显著优势。

迁移到 Pub/Sub 通知具有以下优势：

  • 可靠的传送：Pub/Sub 会为每个订阅将发布的每个消息至少传送一次，从而验证事件是否已传送给使用方。可靠的传送可最大限度地减少数据丢失，并提高工作流的可靠性，而对象更改通知的传送模型不如前者可靠。
  • 可扩缩性：Pub/Sub 通知专为高吞吐量而设计，可自动处理大量事件。使用 Pub/Sub 通知时，您可以消除在数据或事件频率增加时可能会遇到的对象更改通知性能瓶颈。
  • 与 Trusted Cloud 服务的集成：Pub/Sub 可与多种 Trusted Cloud 服务无缝集成，让您能够灵活地使用 Cloud Run functions、Cloud Run、Dataflow 构建自动化工作流，并通过 Cloud Logging 和 Cloud Monitoring 增强可观测性。
  • 精细控制：借助 Pub/Sub，您可以在订阅级过滤消息。这样，使用方便可以仅接收相关事件，从而减少不必要的处理和网络流量。
  • 平台支持：Pub/Sub 通知是受支持的通讯服务。迁移有助于您使用可不断获得增强功能、安全更新和全面文档的技术，而已弃用的对象更改通知则无法提供这些内容。

迁移步骤

对象更改通知和 Cloud Storage 的 Pub/Sub 通知有时可能会发送重复的消息。因此，您的使用方代码必须设计为能够安全地处理重复消息。

如需从对象更改通知迁移到 Pub/Sub 通知，请按以下步骤操作：

  1. 除了现有的对象更改通知设置之外，开始使用适用于 Cloud Storage 的 Pub/Sub 通知。如需了解如何配置 Pub/Sub 通知，请参阅配置适用于 Cloud Storage 的 Pub/Sub 通知。

  2. 测试并验证应用的 Pub/Sub 通知处理工作流是否正常运行。如需了解如何监控 Pub/Sub 订阅，请参阅在 Pub/Sub 中监控订阅。

  3. 停止处理从对象更改通知渠道接收的消息。如需停止通知渠道，请发出 stop 请求。

Pub/Sub 推送订阅注意事项

虽然 Pub/Sub 拉取订阅可提供更高的灵活性和控制力，但 Pub/Sub 推送订阅与对象更改通知消息非常相似。因此，推送订阅成为适用于现有对象更改通知用户的更快迁移路径。如需详细比较推送订阅和拉取订阅，请参阅选择订阅类型。

如果您计划使用推送订阅，并计划重复使用现有的通知处理代码，则需要考虑对象更改通知和 Pub/Sub 通知之间的推送请求格式和响应代码解读差异。以下各部分介绍了这些差异。

推送请求格式

本部分介绍了对象更改通知和 Pub/Sub 通知之间的推送请求格式差异。

  • 对象更改通知：对象更改通知以 HTTP POST 请求的形式传送到您的应用网址，格式如下：

    POST /ApplicationUrlPath
Accept: * / *
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
"kind": "storage#object",
"id": "BucketName/ObjectName",
"selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
"name": "ObjectName",
"bucket": "BucketName",
"generation": "1367014943964000",
"metageneration": "1",
"contentType": "application/octet-stream",
"updated": "2013-04-26T22:22:23.832Z",
"size": "10",
"md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
"mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
"owner": {
  "entity": "user-jeffersonloveshiking@gmail.com"
},
"crc32c": "C7+82w==",
"etag": "COD2jMGv6bYCEAE="
}

  • Pub/Sub 通知：Pub/Sub 通知在配置为推送传送时，会以 HTTP POST 请求的形式传送。data 字段包含采用 base64 编码的 Cloud Storage 事件载荷。data 字段进行解码后，会与对象更改通知消息正文相符。

    POST /YourSpecifiedURL
Accept: * / *
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
{
  "deliveryAttempt": 5,
  "message":
    {"attributes":
      {"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"
      },
    "data": "ewogImtpbm",
    "messageId": "2070443601311540",
    "message_id": "2070443601311540",
    "orderingKey": "key",
    "publishTime": "2021-02-26T19:13:55.749Z",
    "publish_time": "2021-02-26T19:13:55.749Z"
    },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

响应代码

下表介绍了对象更改通知和 Pub/Sub 通知之间的响应代码解读差异：

功能 响应代码 解读 操作
对象更改通知
102、200、201、202、204 成功 消息已处理
500、502、503、504 无法处理 稍后重试
超时、连接失败、无响应 无法处理 稍后重试
任何其他 HTTP 代码。例如 404。 永久错误 不重试消息
Pub/Sub 通知
102、200、201、202、204 成功 消息已确认
所有其他响应代码、超时和连接失败 失败 稍后重试

后续步骤