You can call this operation to query the connection information, such as connections and subscriptions, of the specified Message Queue for MQTT client based on the client ID.

Scenarios

OnsMqttQueryClientByClientId is typically used to track the running status of a connected Message Queue for MQTT client and troubleshoot problems with this client. You can enter a client ID to check whether this client is connected, and to query the IP address and current subscriptions of this client.

For more information about client IDs, see Terms.

The Message Queue for MQTT broker performs throttling on frequent calls (30 calls per minute) because APIs are designed for custom management and control. Therefore, do not call this operation in the main service process. To determine whether a Message Queue for MQTT client is connected, use the device online/offline notification function. If a Message Queue for MQTT client is online, this client has been connected to a Message Queue for MQTT broker.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description 
ClientId String   Yes GID_test@@@test

The ID of the Message Queue for MQTT client that you want to query.
InstanceId String   Yes post-cn-0pp12gl****

The ID of the Message Queue for MQTT instance that corresponds to the Message Queue for MQTT client you want to query. This parameter is required for instances with separate namespaces.

Response parameters

Parameter Type Example Description 
RequestId String E4581CCF-62AF-44D9-B5B4-D1DBBC0ED875

The ID of the request, which is a common parameter. Each request has a unique ID to facilitate troubleshooting and fault locating.

MqttClientInfoDo Struct

The structure of information about whether the Message Queue for MQTT client was connected to the Message Queue for MQTT broker.

Online Boolean True

Indicates whether the Message Queue for MQTT client was connected to the Message Queue for MQTT broker. Valid values:

  • true: connected
  • false: not connected
ClientId Integer GID_test@@@test

The client ID of the Message Queue for MQTT client.
SocketChannel Integer /42.120. **. **:50255

The IP address of the MQTT client.
LastTouch Long 1570960847101

The last time when active messages existed.
SubScriptonData Array

The information structure about a subscription of the MQTT client.
ParentTopic Integer test

The parent topic that the MQTT client subscribed to.
SubTopic Integer /testMq4Iot/

The subtopic that the MQTT client subscribed to. The parameter value is NULL if no subtopic exists.

Qos Integer  0

The quality of service (QoS) level of the message that was subscribed. Valid values:

  • 0: The message was sent at most once.
  • 1: The message is received at least once.
  • 2: The message was sent exactly once.

For more information about QoS, see Terms.

Examples

Sample requests

http(s)://[Endpoint]/? Action=OnsMqttQueryClientByClientId
&ClientId=GID_test@@@test
&InstanceId=post-cn-0pp12gl****
&<Common request parameters>

Sample success response

XML format 

<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 format 

{
	"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"
}

Error codes

For a list of error codes, visit the API Error Center.