本文档简要介绍了拉取订阅、其工作流以及 相关联的属性
在拉取订阅中,订阅方客户端从 Pub/Sub 服务器。
拉取模式可以使用 Pull 或 StreamingPull 两个服务 API 之一。 如需运行所选 API,您可以选择 Google 提供的高级客户端 库或自动生成的低级客户端库。您还可以选择 异步消息处理和同步消息处理之间的差异。
准备工作
在阅读本文档之前,请确保您熟悉以下内容:
Pub/Sub 的工作原理 以及不同的 Pub/Sub 条款
不同的订阅类型 Pub/Sub 支持的功能,以及 订阅。
拉取订阅工作流
对于拉取订阅,订阅者客户端向 Pub/Sub 服务器检索消息。订阅方客户端使用 以下 API 之一:
大多数订阅者客户端不会直接发出这些请求。相反, 客户端依赖于 Google Cloud 提供的高级客户端库, 在内部执行流式拉取请求并传递消息 异步执行。对于需要更好地控制消息拉取方式的订阅方客户端,Pub/Sub 使用自动生成的低级 gRPC 库。此库发出拉取或流式拉取请求 。这些请求可以是同步请求,也可以是异步请求。
以下两张图片展示了订阅者客户端与 拉取订阅。
拉取工作流
拉取工作流如下所示(参考图 1):
- 订阅方客户端明确调用
pull
方法,该方法会请求 消息进行传送。此请求是PullRequest
,如 图片。 Pub/Sub 服务器返回零条或多条消息进行响应, 确认 ID。不含任何消息或包含错误的响应不会 必须说明没有消息可接收。这个 是上图所示的
PullResponse
。订阅者客户端明确调用
acknowledge
方法。客户 使用返回的确认 ID 来确认消息 且无需再次传送。
对于单个流式拉取请求,一个订阅方客户端可以有多个 因为连接处于打开状态而返回了响应。相比之下,只有一个响应是 每个拉取请求返回的值
拉取订阅的属性
您为拉取订阅配置的属性决定了 向订阅写入消息如需了解详情,请参阅 订阅属性。
Pub/Sub 服务 API
Pub/Sub 拉取订阅可以使用 以下两个用于检索消息的 API:
- 拉取
- StreamingPull
收到消息时使用一元确认和 ModifyAckDeadline RPC 这些 API。有关这两种 Pub/Sub API 的说明,请参见 后续标签页。
StreamingPull API
Pub/Sub 客户端库会尽可能使用 StreamingPull 以实现最大吞吐量和最短延迟时间。尽管您可能永远不会使用 StreamingPull API,我们有必要了解 拉取 API
StreamingPull API 依赖持久双向连接来 及时收到多条消息。以下是 工作流:
客户端向服务器发送请求以建立连接。 如果超出连接配额,服务器将返回已用尽的资源 错误。客户端库会自动重试超出配额的错误。
如果没有错误或连接配额可再次使用,则服务器 持续向连接的客户端发送消息。
如果超出吞吐量配额,服务器将停止发送 消息。不过,连接并未中断。当余额充足时 吞吐量配额再次可用时,数据流将恢复。
客户端或服务器最终关闭连接。
StreamingPull API 会保持打开连接。Pub/Sub 服务器会在一段时间后定期关闭连接,以避免 长期运行的粘性连接客户端库自动重新打开 StreamingPull 连接。
消息可用时,会发送到相应连接。StreamingPull 从而最大限度地缩短延迟时间,提高消息吞吐量。
详细了解 StreamingPull RPC 方法:StreamingPullRequest 和 StreamingPullResponse。
拉取 API
此 API 是基于请求和响应的传统一元 RPC 模型。单个拉取响应对应于单个拉取请求。 工作流程如下:
客户端向服务器发送消息请求。 如果超出吞吐量配额,服务器将返回资源 出现耗尽错误。
如果没有错误或吞吐量配额再次可用,则服务器 包含零个或多个消息和确认 ID 的回复。
使用一元拉取 API 时,响应不含任何消息或包含 错误并不一定表示没有可用的消息 内容。
使用 Pull API 不能保证低延迟和高吞吐量 消息。要使用 Pull API 实现高吞吐量和低延迟, 必须同时有多个未处理的请求。新请求创建完成 旧请求收到响应时触发。设计这样的解决方案 且难以维护。我们建议您使用 用于此类用例的 API。
只有在需要严格时,才使用 Pull API,而不是 StreamingPull API 可以控制以下方面:
- 订阅者客户端可以处理的消息数量
- 客户端内存和资源
如果您的订阅者是以下两者之间的代理,您也可以使用此 API Pub/Sub 和其他服务 编写代码。
详细了解 Pull REST 方法: 方法:projects.subscriptions.pull。
详细了解拉取 RPC 方法: PullRequest 和 PullResponse。
消息处理模式的类型
为您的订阅者客户端选择以下拉取模式之一。
异步拉取模式
异步拉取模式将消息接收与处理 订阅程序客户端中的消息格式该模式是大多数国家/地区的默认模式 订阅者客户端。异步拉取模式可以使用 StreamingPull API 或 一元拉取 API。异步拉取也可以使用高级客户端库 或自动生成的低级客户端库
您可以在本文档的后面部分了解有关客户端库的更多信息。
同步拉取模式
在同步拉取模式下,消息的接收和处理发生在 序列,并且不会相互分离。因此,类似于 StreamingPull 与一元拉取 API,异步处理产品 与同步处理相比,延迟更低,吞吐量更高。
请仅对低延迟、高延迟的应用使用同步拉取模式 与其他一些 要求。例如,某应用可能仅限于使用 同步编程模型。或者,具有资源的 可能要求更精确地控制内存、网络或 CPU。在这种情况下,请将同步模式与单个拉取 API 搭配使用。
Pub/Sub 客户端库
Pub/Sub 为系统自动生成的 客户端库。
高级 Pub/Sub 客户端库
高级客户端库提供了用于控制 确认截止期限。与在订阅级别使用控制台或 CLI 配置确认期限相比,这些选项更精细。高级客户端库还实现了对有序传送、恰好一次传送和流控制等功能的支持。
我们建议将异步拉取和 StreamingPull API 与 高级客户端库并非所有语言都支持 Google Cloud 还支持高级客户端库中的 Pull API。
如需使用高级客户端库,请参阅 Pub/Sub 客户端库。
自动生成的低级 Pub/Sub 客户端库
如果必须使用 直接拉取 API。您可以将同步处理或异步处理与 自动生成的低级客户端库。您必须手动编写功能代码,例如 有序交付、正好一次交付、流控制和租赁管理 。
当您使用低层级 API 时,可以使用同步处理模型, 针对所有支持的语言自动生成的客户端库。您可以使用 自动生成的低级客户端库;在以下情况下, 直接使用拉取 API 是明智之举。例如,您可能已有 依赖于此模型的应用逻辑。
要直接使用自动生成的低级客户端库,请参阅 Pub/Sub API 概览。
客户端库代码示例
StreamingPull 及高级客户端库代码示例
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
使用高级客户端库检索自定义属性
以下示例展示了如何异步拉取消息并检索 元数据中的自定义属性。
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
使用高级客户端库处理错误
以下示例展示了如何处理 订阅消息。
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
一元拉取代码示例
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
协议
请求:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
响应:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
请求:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Pub/Sub 传送消息列表。 如果列表中有多条消息,Pub/Sub 将按照 相同的排序键。 以下是一些重要注意事项:
在请求中为
max_messages
设置值并不能保证max_messages
,即使 积压。Pub/Sub Pull API 返回的内容可能少于max_messages
,以便缩短消息的传送延迟时间 可随时投放不得将附带 0 条消息的拉取响应用作指标 积压消息中没有任何消息。在收到回复时 且后续请求会返回消息。
要通过一元拉取模式实现较低的消息传送延迟时间, 同时拥有许多同时未完成的拉取请求的关键所在。如 主题的吞吐量增加,则需要更多的拉取请求。 StreamingPull 模式通常更适合 对延迟敏感的应用
配额和限制
Pull 和 StreamingPull 连接均受配额和限制的约束。 如需了解详情,请参阅 Pub/Sub 配额和限制。
后续步骤
使用 gcloud CLI 创建或修改订阅。
使用 REST API 创建或修改订阅。
使用 RPC API 创建或修改订阅。