本文档介绍了如何发布消息。
发布者应用会创建消息,然后将其发送到主题。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 }
对于发布端重复项,同一客户端原始消息可能会显示不同的 publishTime
值,即使 messageId
相同也是如此。
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 参考文档。
使用排序键发布消息
如需在订阅方客户端中按顺序接收消息,您必须将发布方客户端配置为发布具有排序键的消息。
如需了解有序键的概念,请参阅对消息排序。
以下是发布商客户端有序消息传递的关键注意事项:
在单个发布方客户端中进行排序:当单个发布方客户端在同一区域发布具有相同排序键的消息时,订阅方客户端会按消息的发布顺序接收这些消息。例如,如果发布方客户端发布消息 1、2 和 3,并使用排序键 A,则订阅方客户端会按 1、2、3 的顺序接收这些消息。
跨多个发布商客户端进行排序:订阅者客户端收到的消息的顺序与消息在同一区域内的发布顺序一致,即使多个发布商客户端使用相同的排序键也是如此。不过,发布商客户端本身不知道此订单。
例如,如果发布方客户端 X 和 Y 各自发布了带有排序键 A 的消息,并且 Pub/Sub 先收到 X 的消息,然后再收到 Y 的消息,那么所有订阅方客户端也都会先收到 X 的消息,然后再收到 Y 的消息。如果需要在不同的发布商客户端之间实现严格的消息顺序,则这些客户端必须实现额外的协调机制,以确保它们不会同时发布具有相同排序键的消息。例如,锁定服务可用于在发布时维护有序键的所有权。
跨区域排序:只有当具有相同排序键的发布操作位于同一区域时,有序传送保证才适用。如果您的发布商应用向不同的区域发布具有相同排序键的消息,则无法强制执行这些发布的顺序。订阅者可以连接到任何区域,并且订购保证仍然有效。
在 Google Cloud 中运行应用时,默认情况下,应用会连接到同一区域中的 Pub/Sub 端点。因此,在 Google Cloud 内的单个区域中运行应用通常可确保您与单个区域进行交互。
在 Google Cloud 之外或在多个区域运行发布方应用时,您可以通过在配置 Pub/Sub 客户端时使用位置端点来确保连接到单个区域。Pub/Sub 的所有位置端点都指向单个区域。如需详细了解位置端点,请参阅 Pub/Sub 端点。如需查看 Pub/Sub 的所有位置端点列表,请参阅位置端点列表。
发布失败:使用排序键发布失败时,发布者中具有相同排序键的已排入队列消息以及此排序键的未来发布请求会失败。发生此类故障时,您必须使用排序键恢复发布。如需查看恢复发布操作的示例,请参阅使用排序键重试请求。
您可以使用 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 资源位置。
如需发布具有架构的消息,请参阅架构概览。
如需了解如何配置高级提交选项,请参阅以下内容: