构建 Pub/Sub 系统时,载荷解封可以帮助您连接到不遵循标准 Pub/Sub 推送端点实现的所有系统要求的其他系统。
载荷解封的一些潜在用例如下:
- 您不希望为 HTTP 推送端点编写特定于 Pub/Sub 的消息解析代码。
- 您更希望将 Pub/Sub 消息元数据作为 HTTP 标头接收,而不是在 HTTP POST 正文中接收元数据。
- 您希望发送 Pub/Sub 消息并排除 Pub/Sub 元数据,例如在向第三方 API 发送数据时。
载荷解封的工作原理
载荷解封是一项功能,可剥离除消息数据以外的所有其他消息元数据。通过发送原始消息数据,订阅者可以处理消息,而无需遵循 Pub/Sub 的任何系统要求。
- 通过载荷解封,消息数据将作为 HTTP 正文直接传送。
- 在未解封载荷的情况下,Pub/Sub 会传送一个包含多个消息元数据字段和一个消息数据字段的 JSON 对象。在这种情况下,必须解析 JSON 以检索消息数据,然后进行 base64 解码。
写入元数据
启用载荷解封后,您可以使用写入元数据选项,将先前移除的消息元数据添加到请求标头中。
- 已启用写入元数据。将消息元数据重新添加到请求标头中。还会传递已解码的原始消息数据。
- 已停用写入元数据。仅传送已解码的原始消息数据。
写入元数据通过 Pub/Sub、Google Cloud CLI 参数 --push-no-wrapper-write-metadata
和 API 属性 NoWrapper
公开。默认情况下,此值为 null。
准备工作
已封装和未封装的消息示例
以下示例说明了发送已封装和未封装的 HTTP 消息之间的区别。在这些示例中,消息数据包含字符串 {"status": "Hello there"}
。
在此示例中,订阅在启用载荷解封功能的情况下创建,并将消息发布到 mytopic
。它使用值为 some-key
的排序键,并且媒体类型声明为 application/json
。
gcloud pubsub topics publish mytopic --message='{"status": "Hello there"}' --ordering-key="some-key" --attribute "Content-Type=application/json"
以下部分展示了封装消息和解封装消息之间的区别。
已封装的消息
以下示例展示了一条标准 Pub/Sub 封装的消息。在这种情况下,未启用载荷解封。
发布 | 推送端点接收 |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 361 Content-Type: application/json User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com { "message": { "attributes": { "Content-Type": "application/json" }, "data": "eyJzdGF0dXMiOiAiSGVsbG8gdGhlcmUifQ==", // Base64 - {"status": "Hello there"} "messageId": "2070443601311540", "message_id": "2070443601311540", "publishTime": "2021-02-26T19:13:55.749Z", "publish_time": "2021-02-26T19:13:55.749Z" }, "subscription": "projects/myproject/..." } |
已解除封装的消息,且写入元数据已停用
以下示例展示了停用了“写入元数据”选项的未封装消息。在这种情况下,不包括 x-goog-pubsub-*
标头和邮件属性。
发布 | 推送端点接收 |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 25 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
已启用写入元数据的未封装消息
以下示例展示了启用了写入元数据选项的解封装消息。在这种情况下,包含 x-goog-pubsub-*
标头和消息属性。
发布 | 推送端点接收 |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
x-goog-pubsub-subscription-name: "projects/myproject/..." x-goog-pubsub-message-id: "2070443601311540" x-goog-pubsub-publish-time: "2021-02-26T19:13:55.749Z" x-goog-pubsub-ordering-key: "some-key" Content-Type: application/json Content-Length: 12 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
配置载荷解封
您可以使用 Google Cloud 控制台订阅详情页面、Google Cloud CLI 或客户端库为订阅启用载荷解封推送传送。
控制台
在 Google Cloud 控制台中,进入订阅页面。
点击创建订阅。
在订阅 ID 字段中,输入一个名称。
如需了解如何为订阅命名,请参阅主题或订阅命名准则。
从下拉菜单中选择主题。订阅会从主题接收消息。
对于传送类型,选择推送。
如需启用载荷解封,请选择启用载荷解封。
(可选)如需保留请求标头中的消息元数据,请选择写入元数据。您必须启用此选项才能为消息设置 Content-Type 标头。
指定端点网址。
保留所有其他默认值。
点击创建。
gcloud
如需配置订阅的载荷解封(包含标准 HTTP 标头),请运行以下 gcloud pubsub subscriptions create
命令:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
替换以下内容:
SUBSCRIPTION
:您的拉取订阅的名称或 ID。TOPIC
:主题的 ID。PUSH_ENDPOINT
:要用作此订阅端点的网址。例如https://myproject.appspot.com/myhandler
--push-no-wrapper
:直接传递消息数据作为 HTTP 正文。
如需配置带有载荷解封的订阅并控制 x-goog-pubsub-*
标头的使用,请运行以下命令:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
--push-no-wrapper-write-metadata
:如果为 true,则将 Pub/Sub 消息元数据写入 HTTP 请求的x-goog-pubsub-<KEY>:<VAL>
标头。将 Pub/Sub 消息属性写入 HTTP 请求的<KEY>:<VAL>
标头。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
在邮件中设置内容类型标头
启用载荷解封后,Pub/Sub 不会在您的请求中自动设置媒体类型标头字段。如果您未明确设置 Content-Type
标头字段,则处理请求的 Web 服务器可能会设置默认值 application/octet-stream
或以非预期方式解释该请求。
如果您需要使用 Content-Type
标头,请务必在发布时对每条发布的消息进行明确声明。为此,您必须先启用写入元数据。提供的示例显示了启用写入元数据的这一结果。
后续步骤
- 如果您在载荷解封时遇到问题,请参阅对载荷解封进行问题排查。