构建 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"} |
配置载荷解封
您可以使用 Trusted Cloud 控制台的订阅详情页面、Google Cloud CLI 或客户端库为订阅启用载荷解封装推送传送。
控制台
在 Trusted 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 客户端库的主要版本 (v2)。如果您仍在使用 v1 库,请参阅迁移到 v2 的指南。如需查看 v1 代码示例的列表,请参阅 已弃用的代码示例。
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 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
标头,请确保在发布时向每条已发布的单独消息明确声明该标头。为此,您必须先启用写入元数据。启用写入元数据后的结果如提供的示例所示。
后续步骤
- 如果您在解封装载荷时遇到问题,请参阅排查载荷解封装问题。