调用 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"
}

错误码

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