构建 Pub/Sub 系统时,载荷解封装可帮助您连接到不遵循标准 Pub/Sub 推送端点实现的所有系统要求的其他系统。
载荷解封装的一些可能用例如下:
- 您不想为 HTTP 推送端点编写特定于 Pub/Sub 的消息解析代码。
- 您希望以 HTTP 标头的形式接收 Pub/Sub 消息元数据,而不是在 HTTP POST 正文中接收元数据。
- 您想发送 Pub/Sub 消息并排除 Pub/Sub 元数据,例如在向第三方 API 发送数据时。
载荷解封的工作原理
载荷解封是一项功能,可剥离 Pub/Sub 消息中的所有消息元数据(消息数据除外)。通过发送原始消息数据,订阅者无需遵守 Pub/Sub 的任何系统要求,即可处理消息。
- 通过载荷展开,消息数据会直接作为 HTTP 正文传送。
- 如果不解封载荷,Pub/Sub 会传送包含多个消息元数据字段和消息数据字段的 JSON 对象。在这种情况下,必须解析 JSON 以检索消息数据,然后进行 base64 解码。
写入元数据
启用载荷解封后,您可以使用写入元数据选项,将之前移除的消息元数据添加到请求标头中。
- 已启用元数据写入权限。将消息元数据重新添加到请求标头中。还会传送已解码的原始消息数据。
- 写入元数据已停用。仅传送已解码的原始消息数据。
写入元数据通过 Pub/Sub、Google Cloud CLI 参数 --push-no-wrapper-write-metadata
和 API 属性 NoWrapper
公开。默认情况下,此值为 null。
准备工作
封装和未封装消息的示例
以下示例说明了发送封装的 HTTP 消息与未封装的 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 参考文档。
在邮件中设置 content-type 标头
启用载荷解封装后,Pub/Sub 不会在请求中自动设置媒体类型标头字段。如果您未明确设置 Content-Type
标头字段,处理您请求的 Web 服务器可能会设置默认值 application/octet-stream
,或者以意外的方式解读请求。
如果您需要 Content-Type
标头,请务必在发布时为每个要发布的消息明确声明该标头。为此,您必须先启用写入元数据。提供的示例中显示了启用写入元数据的结果。
后续步骤
- 如果您在解封载荷时遇到问题,请参阅排查载荷解封问题。