本文档介绍了如何发布消息。
发布者应用会创建消息,然后将其发送到主题。Pub/Sub 为现有订阅者提供至少一次消息传送和尽力排序功能。
发布者应用的一般流程如下所示:
- 创建一条包含您的数据的消息。
- 向 Pub/Sub 服务器发送请求,将消息发布到指定主题。
准备工作
在配置发布工作流之前,请确保您已完成以下任务:
所需的角色
如需获取将消息发布到主题所需的权限,请让管理员授予您对该主题的 Pub/Sub Publisher (roles/pubsub.publisher
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。
您需要其他权限才能创建或更新主题和订阅。
消息格式
消息由包含消息数据和元数据的字段组成。在消息中至少指定以下内容之一:
Pub/Sub 服务将以下字段添加到消息中:
- 主题专属的消息 ID
- Pub/Sub 服务接收消息的时间的时间戳
如需详细了解消息,请参阅消息格式。
发布消息
您可以使用 Google Cloud 控制台、Google Cloud CLI、Pub/Sub API 和客户端库发布消息。客户端库可以异步发布消息。
以下示例演示了如何向主题发布消息。
控制台
要发布消息,请执行以下操作
在 Google Cloud 控制台中,转到 Pub/Sub 主题页面。
点击主题 ID。
在主题详情页面的消息下,点击发布消息。
在消息正文字段中,输入消息数据。
点击发布。
gcloud
要发布消息,请使用 gcloud pubsub topics publish 命令:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
替换以下内容:
- TOPIC_ID:主题的 ID
- MESSAGE_DATA:包含消息数据的字符串
- KEY:消息属性的键
- VALUE:消息属性的键对应的值
REST
要发布消息,请发送如下所示的 POST 请求:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
替换以下内容:
- PROJECT_ID:包含主题的项目的 ID
- TOPIC_ID:主题的 ID
在请求正文中指定以下字段:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
替换以下内容:
- KEY:消息属性的键
- VALUE:消息属性的键对应的值
- MESSAGE_DATA:包含消息数据的 base64 编码字符串
消息必须包含非空的数据字段或至少一个特性。
如果请求成功,则响应是一个包含消息 ID 的 JSON 对象。以下是包含消息 ID 的响应:
{ "messageIds": [ "19916711285", ] }
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 参考文档。
PHP
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
发布消息后,Pub/Sub 服务将消息 ID 返回给发布者。
使用特性发布消息
您可以将自定义属性作为元数据嵌入到 Pub/Sub 消息中。属性用于提供有关消息的更多信息,例如其优先级、出发地或目的地。属性还可用于过滤订阅的消息。
在邮件中使用属性时,请遵循以下准则:
属性可以是文本字符串或字节字符串。
每条消息最多可以有 100 个属性。
属性键不得以
goog
开头,并且不得超过 256 个字节。属性值不得超过 1024 个字节。
消息架构可通过以下方式表示:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
对于发布端重复项,即使 messageId
相同,同一客户端原始消息也可能会看到不同的 publishTime
值。
PubsubMessage
JSON 架构作为 REST 和 RPC 文档的一部分发布。您可以对事件时间戳使用自定义属性。
以下示例演示了如何向主题发布带有属性的消息。
控制台
如需发布包含属性的消息,请按以下步骤操作:
在 Google Cloud 控制台中,前往主题页面。
点击要为其发布消息的主题。
在主题详情页面中,点击消息。
点击发布消息。
在消息正文字段中,输入消息数据。
在邮件属性下,点击添加属性。
输入键值对。
根据需要添加更多属性。
点击发布。
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
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 参考文档。
使用排序键发布消息
如需在订阅者客户端中按顺序接收消息,您必须将发布者客户端配置为使用排序键发布消息。
如需了解对键进行排序的概念,请参阅为消息排序。
下面列出了在对发布商客户端有序消息传递时的关键注意事项:
在单个发布者客户端中排序:当单个发布者客户端在同一区域中发布具有相同排序键的消息时,订阅者客户端会按照发布消息的确切顺序接收这些消息。例如,如果发布者客户端使用排序键 A 发布消息 1、2 和 3,则订阅者客户端会按顺序 1、2、3 接收这些消息。
跨多个发布者客户端排序:订阅者客户端接收消息的顺序与消息在同一区域中发布的顺序一致,即使多个发布者客户端使用相同的排序键也是如此。但是,发布商客户端本身并不知道此订单。
例如,如果发布者客户端 X 和 Y 分别发布具有排序键 A 的消息,并且 Pub/Sub 先于 Y 接收 X 的消息,则所有订阅者客户端都会在 Y 之前收到 X 的消息。如果不同发布者客户端需要严格的消息顺序,则这些客户端必须实现额外的协调机制,以确保它们不会同时发布具有相同排序键的消息。例如,锁定服务可用于在发布时保留对排序键的所有权。
跨区域排序:只需对在同一区域中发布的消息进行排序。因此,请确保您的发布者客户端使用位置信息服务端点针对同一排序键将消息发布到同一区域。然后,订阅者客户端可以按顺序接收这些消息。
发布失败:使用排序键发布时失败,发布者中同一排序键的排入队列的消息会失败,包括此排序键的后续发布请求。如果发生此类失败,您必须使用排序键继续发布。如需查看恢复发布操作的示例,请参阅使用排序键重试请求。
您可以使用 Google Cloud 控制台、Google Cloud CLI、Pub/Sub API 或客户端库发布带有排序键的消息。
控制台
如需发布包含属性的消息,请按以下步骤操作:
在 Google Cloud 控制台中,前往主题页面。
点击要为其发布消息的主题。
在主题详情页面中,点击消息。
点击发布消息。
在消息正文字段中,输入消息数据。
在消息排序字段中,输入排序键。
点击发布。
gcloud
如需发布带有排序键的消息,请使用 gcloud pubsub topics publish
命令和 --ordering-key
标志:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
替换以下内容:
- TOPIC_ID:主题的 ID
- MESSAGE_DATA:包含消息数据的字符串
- ORDERING_KEY:带有排序键的字符串
REST
如需发布带有排序键的消息,请发送如下所示的 POST 请求:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
替换以下内容:
- PROJECT_ID:包含主题的项目的 ID
- TOPIC_ID:主题的 ID
在请求正文中指定以下字段:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
替换以下内容:
- KEY:消息属性的键
- VALUE:消息属性的键对应的值
- MESSAGE_DATA:包含消息数据的 base64 编码字符串
- ORDERING_KEY:带有排序键的字符串
消息必须包含非空的数据字段或至少一个特性。
如果请求成功,则响应是一个包含消息 ID 的 JSON 对象。以下是包含消息 ID 的响应:
{ "messageIds": [ "19916711285", ] }
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 参考文档。
监控发布商
Cloud Monitoring 提供了多种用于监控主题的指标。
如需监控主题并使发布者保持良好的健康状况,请参阅使发布者保持良好的健康状况。
后续步骤
如需限制 Pub/Sub 存储消息数据的位置,请参阅限制 Pub/Sub 资源位置。
如需发布包含架构的消息,请参阅架构概览。
如需了解如何配置高级传送选项,请参阅以下内容: