帮你快速理解、总结文档立即下载

查询普通消息

最近更新时间:2026-11-13 17:00:42
本文档已由 AI 辅助审校
我的收藏
若您遇到消息生产消费异常,例如消息丢失或消息消费失败等问题,可以在 MQTT 控制台查询异常消息来排查问题。

约束与限制

单次查询最多支持展示 1024 条消息。
消息默认保留时长为 3 天,超过保留时长的消息将被自动清理。

查询消息

1. 登录 MQTT 控制台。
2. 在左侧导航栏单击消息查询,选择好地域后根据页面提示输入查询条件。
当前集群:在下拉框中选择需要查询的 Topic 所在的集群。
查询方式:当前支持按照 Topic 精确查找、按消息 ID 精确查找。
Topic:填写需要查询的 Topic 名称,支持填写 Topic Name 或订阅时的 Topic Filter 。
起始时间:选择需要查找消息的最开始的时间点,支持精确到毫秒。
查询信息条数:按照严格的时间顺序展示所选时间后的 N 条消息,支持100、200、500、1024条。
消息体过滤:支持基于 jq 语法对 JSON 格式的消息体进行过滤。
3. 单击 查询,下方列表会展示所有查询到的结果并分页展示。

4. 找到您希望查看内容或参数的消息,单击操作列的查看详情,即可查看消息的详细信息和轨迹。


获取消息 ID

消息轨迹、消息查询功能中所指的消息 ID,是服务端为每条消息生成的全局唯一标识,并通过 MQTT 5.0 User Property 中的 $__messageId 字段透传给客户端。获取方式如下:
发布消息时:使用 MQTT 5.0 协议发布 QoS 1 / QoS 2 消息后,服务端会在 PUBACK(QoS 1)或 PUBREC(QoS 2)确认报文的 User Property 中返回 $__messageId,即该消息的唯一 ID。您可从该确认报文中取出并保存,用于后续在消息查询、消息轨迹中精确定位该消息。
订阅消息时:使用 MQTT 5.0 协议的订阅客户端,收到的每条 PUBLISH 消息的 User Property 中均携带 $__messageId,取出该字段即可用于查询该消息的轨迹。
说明:
MQTT 3.1.1 协议不支持 User Property,因此 3.1.1 客户端无法直接从报文中获取消息 ID。此类客户端可升级至 MQTT 5.0,或通过消息查询(按 Topic、时间范围等条件)检索目标消息后获得其消息 ID。

消息详情说明

基本信息
参数
说明
消息 ID
消息的标识符,在客户端和服务端之间进行消息确认时用于匹配请求和响应。
Topic
消息所在的 Topic。
生产 Client ID
发布这条消息的客户端唯一标识符,用于追踪消息的来源。
QoS
消息的服务质量等级,决定了消息传递的可靠性和保证程度,包括 0(最多一次)、1(至少一次)、2(恰好一次)。
消息存储时间
消息存储到服务端的时间。
消息体:具体的消息内容。
消息属性
参数
含义
说明
Content Type
内容类型
一个 UTF-8 编码的字符串,用于描述应用消息的内容(Payload)的格式类型,帮助订阅者(接收方)了解如何解析和处理消息的有效载荷。例如一个设备同时发布 JSON 格式和二进制格式的消息,订阅者可以根据 Content Type 来决定是用 JSON.parse() 还是用自定义的二进制解析器来处理数据。
Payload Format Indicator
有效载荷格式指示器
一个单字节的标识符,指明应用消息的有效载荷是 UTF-8 编码的字符数据还是未指定的二进制数据。
0: 字节流(未指定,可能是二进制数据)
1: UTF-8 编码的字符数据
如果此属性设置为 1,接收端的客户端可以尝试将 Payload 当作字符串打印到控制台。
Message Expiry Interval
消息过期间隔
服务端在收到消息后,必须在该时间内将其传递给订阅者,超过此时间后,如果消息还未被投递,服务端会将其丢弃。
Response Topic
响应主题
用于实现请求-响应模式,发布者可以在消息中指定一个主题,接收者(订阅者)将响应消息发送到这个指定的主题上。
Correlation Data
关联数据
一段附加在请求消息中的标识数据,接收方在响应中原样返回,用于将请求与响应配对。
Subscription Identifier
订阅标识符
客户端为订阅分配的一个数字标识符,服务端在转发消息时带回此标识符,使客户端能高效识别消息来源。
User Property
用户属性
可附加在报文上的自定义键值对,用于传递业务元数据,实现消息体与属性的分离,极大扩展协议灵活性。

消息轨迹说明

在消息详情页单击消息轨迹页签,可查看该条消息的生产消费轨迹。如未找到目标消息轨迹,您可以通过精确时间和使用右侧的客户端 ID 搜索来缩小查找范围。消息轨迹的详细说明请参考消息轨迹说明。

导出消息

在消息查询页面查询到某条消息后,您可以单击操作列的导出消息,将该条消息的 ID、子级 Topic、QoS、时间属性等信息导出。同时,您可以批量选择当前页面内的消息,批量导出多条消息。将消息导出到本地后,用户可以根据需要对消息进行一些处理,如复制消息体或者进行时间排序等操作。


重发消息

在消息查询页面查询到某条历史消息后,您可以单击操作列的重发消息,向指定客户端重新下发一次 MQTT 消息,触发消息重新消费。
说明:
重发消息是重新投递,原消息在消息查询中的存储记录不会被修改或复制,重发成功后也不会在消息列表中产生新的消息条目和消息 ID。
重发消息的 QoS 固定为 0:无论原消息使用何种 QoS 等级,重发后将以 QoS 0 投递(at most once),不保证送达。如需可靠投递,请改用原发布流程。


字段
是否必填
说明
消息 ID
-
系统自动展示待重发的原始消息 ID,仅作信息确认,不可修改
Topic
-
系统自动展示原始消息的 Topic,不可修改
目标客户端 ID
是
输入接收该重发消息的客户端 Client ID。需为当前集群内已连接且订阅了对应 Topic 的客户端。