动态与公告

新功能发布记录

产品简介

TDMQ 产品系列介绍与选型

什么是消息队列 MQTT 版

应用场景

技术架构

产品系列

MQTT 协议兼容说明

开源对比

高可用

产品约束与使用配额

基本概念

开服地域

购买指南

计费概述

续费说明

查看消费明细

欠费说明

退费说明

快速入门

入门流程指引

准备工作

公网接入

VPC 网络接入

用户指南

使用流程指引

配置账号权限

新建集群

管理 Topic

连接集群

查询消息

管理客户端

管理集群

查看监控和配置告警

数据集成

集成数据到云函数 SCF

集成数据到 CKafka

集成数据到 RocketMQ

开发指南

MQTT 5 高级特性

数据面 HTTP 接口说明

配置自定义域名

配置 SQL 过滤

配置点对点订阅

MQTT over QUIC

管理客户端订阅

消息增强规则

实践教程

MQTT 客户端开发注意事项

可观测能力

Topic 与通配符订阅

API 参考

History

Introduction

API Category

Making API Requests

Cluster APIs

Topic APIs

Authorization Policy APIs

User APIs

Client APIs

Message Enhancement Rule APIs

Message APIs

Data Types

Error Codes

SDK 参考

接入点格式

Java SDK

C SDK

Javascript/Node.JS/小程序

Go SDK

iOS SDK

JavaScript SDK

Dart SDK

Python SDK

.NET

安全与合规

权限管理

常见问题

查询客户端在线状态

PDF

聚焦模式

字号

最后更新时间： 2026-01-30 15:23:29

概述
消息队列 MQTT 版支持通过主动查询和客户端事件两种方式来获取 MQTT 客户端在线状态。
原理介绍
消息队列 MQTT 版提供以下两种方式查询客户端在线状态：
方式
说明
使用场景
差异对比
主动查询
实例开放 RESTful API，实时查询客户端在线状态。
1. 业务流程中需要根据客户端是否在线决定后续运行逻辑。
2. 运维过程需要判断特定客户端当前是否在线。
主动查询是查询当前客户端的实时状态，相比上下线事件通知的方式更精确。
﻿
客户端事件
使用消息通知，在客户端上线和下线事件触发时，MQTT 服务端产生对应事件并发布到对应系统主题中， 业务应用可以根据需要订阅相关事件消息。
该方式属于异步感知客户端的状态，且感知到的是上下线事件，而非在线状态，云端应用需要根据事件发生的时间序列分析出客户端的状态。
1. 业务需要在客户端上线或者下线时触发一些预定义的动作。
2. 业务需要对客户端的上下线数据进行统计分析，并根据客户端的在线状态推送消息。
客户端采用消息解耦，状态判断更加复杂，且误判可能性更大（最终一致性）。虽然存在一定复杂度和误判概率，但更加适合大规模的客户端的状态统计。
使用方法
主动查询
主动查询
客户端事件
请求示例
通过以下 RESTful API 进行查询：
curl --header "Authorization: Basic dXNlcjA6c2VjcmV0MA=="  https://${instance-access-point}/client-id/${client-id}/status
请求参数说明：
变量
语义
示例值
${instance-access-point}
实例接入点地址，从控制台的 集群管理 > 基本信息页面获取。
mqtt-xxxx-gz-public.mqtt.tencenttdmq.com
${client-id}
需要查询的目标 client-id，具体规范定义可参见 
﻿Client Identifier (ClientID)，结果需经过 URL 编码。
VIN0000001
返回的 Status Code 说明：
1. 支持 HTTP Method： GET/POST。
2. 支持 HTTP/HTTPS。
3. 通过 HTTP Basic Authentication实现认证， 参见 Basic Authentication。
4. 认证、授权：用户名和密码必须合法，且该账户必须有 CONNECT 权限。
5. HTTP 响应：
HTTP Status Code（状态码）
描述
200
请求正常。
401
认证失败，用户名或者密码不正确。
403
鉴权失败，缺少 CONNECT 权限。
429
流控，Too Many Requests。
输出示例
如果请求正常处理，返回以下内容：
{"online":true}
输出参数说明：
参数
说明
online
客户端在线状态。
true：在线。
false：不在线。
详细参见 查询客户端事件。
计费说明
查询一次客户端在线状态， 等同于一次 QoS=0 的消息发布，具体可参见 计费概述。查询频率受限于实例 QPS Quota 约束。

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

方式	说明	使用场景	差异对比
主动查询	实例开放 RESTful API，实时查询客户端在线状态。	1. 业务流程中需要根据客户端是否在线决定后续运行逻辑。 2. 运维过程需要判断特定客户端当前是否在线。	主动查询是查询当前客户端的实时状态，相比上下线事件通知的方式更精确。
客户端事件	使用消息通知，在客户端上线和下线事件触发时，MQTT 服务端产生对应事件并发布到对应系统主题中，业务应用可以根据需要订阅相关事件消息。该方式属于异步感知客户端的状态，且感知到的是上下线事件，而非在线状态，云端应用需要根据事件发生的时间序列分析出客户端的状态。	1. 业务需要在客户端上线或者下线时触发一些预定义的动作。 2. 业务需要对客户端的上下线数据进行统计分析，并根据客户端的在线状态推送消息。	客户端采用消息解耦，状态判断更加复杂，且误判可能性更大（最终一致性）。虽然存在一定复杂度和误判概率，但更加适合大规模的客户端的状态统计。

变量	语义	示例值
${instance-access-point}	实例接入点地址，从控制台的集群管理 > 基本信息页面获取。	mqtt-xxxx-gz-public.mqtt.tencenttdmq.com
${client-id}	需要查询的目标 client-id，具体规范定义可参见 Client Identifier (ClientID)，结果需经过 URL 编码。	VIN0000001

HTTP Status Code（状态码）	描述
200	请求正常。
401	认证失败，用户名或者密码不正确。
403	鉴权失败，缺少 CONNECT 权限。
429	流控，Too Many Requests。

参数	说明
online	客户端在线状态。 true：在线。 false：不在线。

tencent cloud

消息队列 MQTT 版

查询客户端在线状态

概述

原理介绍

使用方法

主动查询

请求示例

返回的 Status Code 说明：

输出示例

计费说明

帮助和支持