推送订阅

本文档简要介绍了推送订阅、其工作流以及关联属性。

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

推送订阅可最大限度地减少对 Pub/Sub 专用客户端库和身份验证机制的依赖。它们还非常适合无服务器和自动扩缩服务技术,例如 Cloud Functions、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 正文发送。

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

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% 且平均推送请求延迟时间不到 1 秒的订阅,推送窗口应该能够满足任何发布吞吐量的需求。

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

在每个区域发送 3,000 条未完成消息后,此窗口会线性增加,以防止推送端点接收过多消息。如果平均延迟时间超过 1 秒或订阅者确认的请求未超过 99%,该窗口会降低至 3000 条未完成消息的下限。

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

配额和限制

推送订阅受一组quotas资源限制的约束。

后续步骤

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

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

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

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