推送订阅

本文档简要介绍了推送订阅、其工作流程和关联的媒体资源。

在推送传送模式下，Pub/Sub 向订阅者应用发起请求来传送消息。消息会传送到可公开寻址的服务器或 Webhook（例如 HTTPS POST 请求）。

推送订阅可最大限度地减少对 Pub/Sub 专用客户端库和身份验证机制的依赖。它们还能与无服务器和自动扩缩服务技术（例如 Cloud Run 函数、Cloud Run 和 Google Kubernetes Engine）完美配合。

准备工作

在阅读本文档之前，请确保您熟悉以下内容：

推送订阅工作流

在推送订阅中，Pub/Sub 服务器向订阅方客户端发起请求以传递消息。

下图显示了订阅方客户端与推送订阅之间的工作流。

推送订阅的消息流
图 3. 推送订阅的工作流程

下面简要介绍了引用图 3 的工作流：

  1. Pub/Sub 服务器将每条消息作为 HTTPS 请求发送到预配置端点上的订阅者客户端。此请求在图片中显示为 PushRequest。
  2. 端点通过返回 HTTP 成功状态代码来确认消息。不成功响应表示 Pub/Sub 必须重新发送消息。此响应在图片中显示为 PushResponse。
  3. Pub/Sub 将根据收到成功响应的速率来动态调整推送请求的速率。

推送订阅的属性

您为推送订阅配置的属性决定了您将消息写入订阅的方式。如需了解详情，请参阅订阅属性。

推送端点如何接收消息

当 Pub/Sub 将消息传送到推送端点时，您可以选择以封装或未封装的方式发送消息。默认情况下，消息会以封装形式发送。

  • 已封装。Pub/Sub 会在 POST 请求的 JSON 正文中发送消息。
  • 未封装。Pub/Sub 会直接将原始消息数据作为 HTTP 正文发送。

以下示例展示了发送到推送端点的 JSON POST 请求的封装正文，其中 message.data 字段包含字符串 Hello there

POST 请求的正文是一个 JSON 对象。消息数据位于 message.data 字段中，采用 base64 编码。

使用最小值的请求示例

  {
      "message": {
          "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
          "messageId": "2070443601311540",
          "message_id": "2070443601311540",
          "publishTime": "2021-02-26T19:13:55.749Z",
          "publish_time": "2021-02-26T19:13:55.749Z"
      },
    "subscription": "projects/myproject/subscriptions/mysubscription"
  }

包含最大值的请求示例

请注意，此示例显示的是当前的最大值，这些值可能会随时间而变化。此外，属性映射可以包含各种值。

  {
      "deliveryAttempt": 5,
      "message": {
          "attributes": {
              "key": "value"
          },
          "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
          "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 发送到推送端点的 POST 请求。如需详细了解如何在 App Engine 中处理这些 POST 请求，请参阅编写和响应 Pub/Sub 消息。

收到推送请求后，返回 HTTP 状态代码。要确认该消息，请返回以下状态代码之一：

  • 102
  • 200
  • 201
  • 202
  • 204

要发送此消息的否定确认，请返回其他任何状态代码。如果您发送否定确认或确认时限到期，Pub/Sub 会重新发送该消息。您无法修改从推送订阅收到的个别消息的确认时限。

推送订阅身份验证

如果推送订阅使用身份验证，则 Pub/Sub 服务会签署 JWT 并在推送请求的授权标头中发送 JWT。

如需详细了解如何设置身份验证，请参阅对推送请求进行身份验证。

停止和恢复消息传送

要暂时阻止 Pub/Sub 将请求发送到推送端点，请将订阅更改为拉取。更改可能需要几分钟才能生效。

要恢复推送传送，请再次将网址设置为有效端点。要永久停止传送，请删除订阅。

推送退避算法

如果推送订阅者发送的否定确认过多，Pub/Sub 可能会开始使用推送退避算法传送消息。当 Pub/Sub 使用推送退避算法时，它会停止传送消息一段时间。此时间跨度可以介于 100 毫秒到 60 秒之间。时间过后，Pub/Sub 会再次开始传送消息。

推送退避算法使用指数退避算法来确定 Pub/Sub 在发送消息之间使用的延迟时间。此时间段的计算依据是推送订阅者发送的否定确认条数。

例如，如果推送订阅者每秒接收 5 条消息，并且每秒发送一条否定确认，则 Pub/Sub 大约每 500 毫秒传送一次消息。或者，如果推送订阅者每秒发送 5 条否定确认，Pub/Sub 会每隔 30 到 60 秒传送一次消息。

请注意以下有关推送延迟的注意事项：

  • 您无法开启或关闭推送延迟功能，也无法修改用于计算延迟时间的值。
  • 在执行以下操作时推送回退触发器：
    • 收到否定确认时。
    • 消息的确认截止期限到期。
  • 推送延迟会应用于订阅中的所有消息（全局）。

传送速率

Pub/Sub 使用慢启动算法来调整并发推送请求的数量。推送窗口是允许的最大并发推送请求数。推送窗口在传送成功时会增大，在传送失败时会减小。系统会从一个小窗口（单个数字）开始。

当订阅者确认消息时，窗口大小以指数方式增加。对于订阅者确认的消息超过 99% 且平均推送请求延迟时间少于一秒的订阅，推送窗口应扩大到足以跟上任何发布吞吐量。

推送请求延迟时间包含以下内容：

每种区域有 3,000 多条未完成消息后，窗口大小会以线性方式增加，以防止推送端点接收过多消息。如果平均延迟时间超过一秒，或订阅者确认的请求少于 99%，则窗口会减少到 3,000 条未完成消息的下限。

如需详细了解可用于监控推送传送的指标，请参阅监控推送订阅。

配额和限制

推送订阅受一组配额和资源限制的约束。

后续步骤

  • 为您的主题创建推送订阅。

  • 使用 gcloud CLI 创建或修改订阅。

  • 使用 REST API 创建或修改订阅。

  • 使用 RPC API 创建或修改订阅。