构建 Pub/Sub 系统时,载荷解封会有所帮助 连接到不满足特定系统要求的 标准 Pub/Sub 推送端点实现。
载荷解封的一些潜在用例如下:
- 您不希望编写特定于 Pub/Sub 的消息解析代码 。
- 您更希望接收 Pub/Sub 消息元数据作为 HTTP 标头 而不是 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 消息。在这些示例中,消息数据包含
字符串 {"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
:要用作此 API 的端点的网址 订阅。例如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 消息元数据发送到x-goog-pubsub-<KEY>:<VAL>
HTTP 请求的标头。写入 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
标头,请务必明确声明它
与发布的每个消息分别进行更新为此,您必须
首先启用写入元数据。启用写入元数据的结果
如提供的示例中所示。
后续步骤
- 如果您在解除载荷封装时遇到问题,请参阅排查载荷解封问题。