调用 OnsMqttQueryClientByClientId 根据 Client ID 查询指定设备的连接信息,包含在线信息、订阅关系等。

使用场景

OnsMqttQueryClientByClientId 接口一般用于线上追踪单个设备的运行状态及排查问题。输入 Client ID 即可查到对应设备是否在线、设备地址、当前的订阅关系等信息。

Client ID 的详细信息,请参见名词解释

使用限制

由于 OpenAPI 面向的场景是用户自定义管控开发,服务端会对过快的调用进行限流(每分钟 30 次),因此不要在业务的主流程中使用本接口。如需判断设备是否在线,请使用设备上下线通知功能。设备状态信息详情请参见获取 MQTT 客户端在线状态

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String OnsMqttQueryClientByClientId

系统规定参数。取值:OnsMqttQueryClientByClientId。

ClientId String GID_test@@@test

需要查询的目标 Client ID

InstanceId String post-cn-0pp12gl****

需查询的设备所对应的 MQTT 实例 ID。针对无独立命名空间的实例,该参数为可选。

返回数据

名称 类型 示例值 描述
MqttClientInfoDo Struct

设备在线信息数据结构

ClientId String GID_test@@@test

设备的 Client ID

LastTouch Long 1570960847101

最后更新时间

Online Boolean true

设备是否在线,取值说明如下:

  • true:在线
  • false:不在线
SocketChannel String /42.120.**.**:50255

设备连接的 IP 地址

SubScriptonData Array

该设备当前的订阅关系集合

SubscriptionDo
ParentTopic String test

MQTT 的父级 Topic

Qos Integer 0

订阅关系的 QoS 级别,取值说明如下:

  • 0:最多分发一次
  • 1:至少达到一次
  • 2:仅分发一次

QoS 的详细信息,请参见名词解释

SubTopic String /testMq4Iot/

MQTT 的多级子 Topic,如果没有则为 NULL

RequestId String E4581CCF-62AF-44D9-B5B4-D1DBBC0ED875

为公共参数,每个请求的 ID 都是唯一的,可用于排查定位问题。

示例

请求示例

http(s)://[Endpoint]/?Action=OnsMqttQueryClientByClientId
&ClientId=GID_test@@@test
&InstanceId=post-cn-0pp12gl****
&<公共请求参数>

正常返回示例

XML 格式

<OnsMqttQueryClientByClientIdResponse>
  <MqttClientInfoDo>
        <SubScriptonData>
              <SubscriptionDo>
                    <SubTopic>/testMq4Iot/</SubTopic>
                    <Qos>0</Qos>
                    <ParentTopic>test</ParentTopic>
              </SubscriptionDo>
        </SubScriptonData>
        <LastTouch>1570960847101</LastTouch>
        <SocketChannel>/42.120.**.**:50255</SocketChannel>
        <Online>true</Online>
        <ClientId>GID_test@@@test</ClientId>
  </MqttClientInfoDo>
  <RequestId>E4581CCF-62AF-44D9-B5B4-D1DBBC0ED875</RequestId>
</OnsMqttQueryClientByClientIdResponse>

JSON 格式

{
	"MqttClientInfoDo": {
		"SubScriptonData": {
			"SubscriptionDo": [
				{
					"SubTopic": "/testMq4Iot/",
					"Qos": 0,
					"ParentTopic": "test"
				}
			]
		},
		"LastTouch": 1570960847101,
		"SocketChannel": "/42.120.**.**:50255",
		"Online": true,
		"ClientId": "GID_test@@@test"
	},
	"RequestId": "E4581CCF-62AF-44D9-B5B4-D1DBBC0ED875"
}

错误码

访问错误中心查看更多错误码。