客户端 API

本页 API 文档提供了与管理 MQTT 客户端相关的各种操作信息，包括查看客户端信息、为客户端订阅和取消订阅主题，以及断开客户端连接。

查看所有客户端

URI

GET /clients

返回集群下所有客户端的信息，支持分页。

查询参数:

参数	类型	描述
_page	Integer	页码
_limit	Integer	每页显示的数据条数
clientid	String	客户端标识符
username	String	客户端用户名
zone	String	客户端配置组名称
ip_address	String	客户端 IP 地址
conn_state	Enum	客户端当前连接状态，可取值有：`connected`,`idle`,`disconnected`
clean_start	Bool	客户端是否使用了全新的会话
proto_name	Enum	客户端协议名称，可取值有：`MQTT`,`CoAP`,`MQTT-SN`
proto_ver	Integer	客户端协议版本
_gte_created_at	Integer	客户端会话创建时间，小于等于查找
_lte_created_at	Integer	客户端会话创建时间，大于等于查找
_gte_connected_at	Integer	客户端连接创建时间，小于等于查找
_lte_connected_at	Integer	客户端连接创建时间，大于等于查找

请求消息

无

响应消息

名称	类型	描述
data	Array of Objects	所有客户端的信息
data[].node	String	客户端所连接的节点名称
data[].clientid	String	客户端标识符
data[].username	String	客户端连接时使用的用户名
data[].proto_name	String	客户端协议名称
data[].proto_ver	Integer	客户端使用的协议版本
data[].ip_address	String	客户端的 IP 地址
data[].port	Integer	客户端的端口
data[].is_bridge	Boolean	指示客户端是否通过桥接方式连接
data[].connected_at	String	客户端连接时间，格式为 "YYYY-MM-DD HH:mm:ss"
data[].disconnected_at	String	客户端离线时间，格式为 "YYYY-MM-DD HH:mm:ss"，此字段仅在 `connected` 为 `false` 时有效并被返回
data[].connected	Boolean	客户端是否处于连接状态
data[].zone	String	指示客户端使用的配置组
data[].keepalive	Integer	保持连接时间，单位：秒
data[].clean_start	Boolean	指示客户端是否使用了全新的会话
data[].expiry_interval	Integer	会话过期间隔，单位：秒
data[].created_at	String	会话创建时间，格式为 "YYYY-MM-DD HH:mm:ss"
data[].subscriptions_cnt	Integer	此客户端已建立的订阅数量
data[].max_subscriptions	Integer	此客户端允许建立的最大订阅数量
data[].inflight	Integer	飞行队列当前长度
data[].max_inflight	Integer	飞行队列最大长度
data[].mqueue_len	Integer	消息队列当前长度
data[].max_mqueue	Integer	消息队列最大长度
data[].mqueue_dropped	Integer	消息队列因超出长度而丢弃的消息数量
data[].awaiting_rel	Integer	未确认的 PUBREC 报文数量
data[].max_awaiting_rel	Integer	允许存在未确认的 PUBREC 报文的最大数量
data[].recv_oct	Integer	EMQX Broker（下同）接收的字节数量
data[].recv_cnt	Integer	接收的 TCP 报文数量
data[].recv_pkt	Integer	接收的 MQTT 报文数量
data[].recv_msg	Integer	接收的 PUBLISH 报文数量
data[].send_oct	Integer	发送的字节数量
data[].send_cnt	Integer	发送的 TCP 报文数量
data[].send_pkt	Integer	发送的 MQTT 报文数量
data[].send_msg	Integer	发送的 PUBLISH 报文数量
data[].mailbox_len	Integer	进程邮箱大小
data[].heap_size	Integer	进程堆栈大小，单位：字节
data[].reductions	Integer	Erlang reduction
meta	Object	分页信息
meta.page	Integer	页码
meta.limit	Integer	每页显示的数据条数
meta.count	Integer	数据总条数

请求示例

bash

curl -u app_id:app_secret -X GET {api}/clients?_page=1&_limit=50

响应示例

JSON

{
  "meta": {
    "page": 1,
    "limit": 50,
    "hasnext": false,
    "count": 1
  },
  "data": [
    {
        "peersni": "qe92461d.dev-ala.cn-hangzhou.mqttce.com",
        "reductions": 10276,
        "expiry_interval": 0,
        "clean_start": true,
        "send_msg.dropped.expired": 0,
        "recv_msg.qos0": 3,
        "mqueue_dropped": 0,
        "recv_cnt": 9,
        "send_cnt": 3,
        "keepalive": 60,
        "recv_oct": 257,
        "heap_size": 987,
        "recv_pkt": 6,
        "recv_msg.dropped.await_pubrel_timeout": 0,
        "proto_ver": 5,
        "inflight_max": 32,
        "send_msg.dropped": 0,
        "created_at": "2023-09-15T09:36:20.871+00:00",
        "awaiting_rel_max": 100,
        "inflight_cnt": 0,
        "ip_address": "115.236.21.86",
        "mqueue_len": 0,
        "send_msg.qos2": 0,
        "send_pkt": 3,
        "subscriptions_cnt": 0,
        "send_msg.dropped.too_large": 0,
        "recv_msg": 3,
        "send_msg.dropped.queue_full": 0,
        "send_msg": 0,
        "node": "emqxsl-dev@10.66.128.31",
        "awaiting_rel_cnt": 0,
        "listener": "tcp:default",
        "connected": true,
        "username": "aip_user2",
        "recv_msg.qos1": 0,
        "proto_name": "MQTT",
        "port": 13312,
        "send_msg.qos1": 0,
        "is_persistent": false,
        "enable_authn": true,
        "mailbox_len": 0,
        "subscriptions_max": 10,
        "recv_msg.qos2": 0,
        "connected_at": "2023-09-15T09:36:20.871+00:00",
        "tenant_id_from": "peersni",
        "is_bridge": false,
        "clientid": "mqttx_07cb8109",
        "send_oct": 25,
        "send_msg.qos0": 0,
        "mqueue_max": 1000,
        "cn": null,
        "recv_msg.dropped": 0,
        "dn": null
    }
  ]
}

查看指定客户端的信息

URI

GET /clients/{clientid}

返回指定客户端的信息

参数:

参数	类型	描述
clientid	String	clientid

请求信息

无

响应信息

名称	类型	描述
data	Array of Objects	客户端的信息，详细请参见 `GET /clients`

请求示例

查询指定客户端

bash

curl -u app_id:app_ssecret -X GET {api}/clients/client_1

响应示例

JSON

// HTTP status response code
200
// HTTP response body
{
    "peersni": "qe92461d.dev-ala.cn-hangzhou.mqttce.com",
    "reductions": 21041,
    "expiry_interval": 0,
    "clean_start": true,
    "send_msg.dropped.expired": 0,
    "recv_msg.qos0": 5,
    "mqueue_dropped": 0,
    "recv_cnt": 18,
    "send_cnt": 10,
    "keepalive": 60,
    "recv_oct": 361,
    "heap_size": 987,
    "recv_pkt": 15,
    "recv_msg.dropped.await_pubrel_timeout": 0,
    "proto_ver": 5,
    "inflight_max": 32,
    "send_msg.dropped": 0,
    "created_at": "2023-09-15T09:36:20.871+00:00",
    "awaiting_rel_max": 100,
    "inflight_cnt": 0,
    "ip_address": "115.236.21.86",
    "mqueue_len": 0,
    "send_msg.qos2": 0,
    "send_pkt": 10,
    "subscriptions_cnt": 0,
    "send_msg.dropped.too_large": 0,
    "recv_msg": 5,
    "send_msg.dropped.queue_full": 0,
    "send_msg": 0,
    "node": "emqxsl-dev@10.66.128.31",
    "awaiting_rel_cnt": 0,
    "listener": "tcp:default",
    "connected": true,
    "username": "aip_user2",
    "recv_msg.qos1": 0,
    "proto_name": "MQTT",
    "port": 13312,
    "send_msg.qos1": 0,
    "is_persistent": false,
    "enable_authn": true,
    "mailbox_len": 0,
    "subscriptions_max": 10,
    "recv_msg.qos2": 0,
    "connected_at": "2023-09-15T09:36:20.871+00:00",
    "tenant_id_from": "peersni",
    "is_bridge": false,
    "clientid": "mqttx_07cb8109",
    "send_oct": 39,
    "send_msg.qos0": 0,
    "mqueue_max": 1000,
    "cn": null,
    "recv_msg.dropped": 0,
    "dn": null
}

踢除客户端

URI

DELETE /clients/{clientid}

踢除指定客户端。注意踢除客户端操作会将连接与会话一并终结。

请求信息

无

响应消息

状态码

请求示例

bash

curl -u app_id:app_secret -X DELETE {api}/clients/client_1

响应示例

HTTP

// HTTP status response code
204

指定客户端订阅主题

URI

POST /clients/{client_id}/subscribe

请求消息

名称	类型	描述
topic	String	需要订阅的主题
qos	Integer	QoS
nl	Integer	No Local
rap	Integer	Retain as Published
rh	Integer	Retain Handling

响应消息

名称	类型	描述
clientid	String	Clientid
topic	String	订阅的主题
qos	Integer	QoS
node	String	节点信息
nl	Integer	No Local
rap	Integer	Retain as Published
rh	Integer	Retain Handling

请求示例

bash

curl -u app_id:app_secret -X POST -H 'Content-Type: application/json' -d '{"topic": "t/a","qos": 1}' {api}/clients/client_1/subscribe

响应示例

JSON

// HTTP status response code
200
// HTTP response body
{
  "clientid": "client_1",
  "topic": "t/a",
  "qos": 1,
  "nl": 0,
  "node": "emqxsl-dev@10.66.128.31",
  "qos": 0,
  "rap": 0,
  "rh": 0,
}

指定客户端取消订阅主题

URI

POST /clients/{client_id}/unsubscribe

请求消息

名称	类型	描述
topic	String	需要取消订阅的主题

响应消息

状态码

请求示例

bash

curl -u app_id:app_secret -X POST -H 'Content-Type: application/json' -d '{"topic": "t/a"}' {api}/clients/client_1/unsubscribe'

响应示例

HTTP

// HTTP status response code
204

指定客户端批量订阅主题

URI

POST /clients/{client_id}/subscribe/bulk

请求消息

名称	类型	描述
[].topic	String	需要订阅的主题
[].qos	Integer	QoS 等级

响应消息

名称	类型	描述
data	Array of Objects	所有订阅信息
data[].clientid	String	clientid
data[].topic	String	订阅主题

请求示例

bash

curl -u app_id:app_secret -X POST -H 'Content-Type: application/json' -d '[{"topic": "t/a", "qos": 1}, {"topic": "t/b", "qos": 0}]' {api}/clients/client_1/subscribe/bulk

响应示例

JSON

// HTTP status response code
200
// HTTP response body
{
    "data": [
        {
            "topic": "t/a",
            "clientid": "client_1",
            "nl": 0,
            "node": "emqxsl-dev@10.66.128.31",
            "qos": 1,
            "rap": 0,
            "rh": 0,
        },
        {
            "topic": "t/b",
            "clientid": "client_1",
            "nl": 0,
            "node": "emqxsl-dev@10.66.128.31",
            "qos": 0,
            "rap": 0,
            "rh": 0,
        }
    ]
}

指定客户端批量取消订阅主题

URI

POST /clients/{client_id}/unsubscribe/bulk

请求消息

名称	类型	描述
[].topic	String	需要取消订阅的主题

响应消息

状态码

请求示例

bash

curl -u app_id:app_secret -X POST -H 'Content-Type: application/json' -d '[{"topic": "t/a"},{"topic": "t/b"}]' {api}/clients/client_1/unsubscribe/bulk

响应示例

HTTP

// HTTP status response code
204

客户端 API ​

查看所有客户端 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

查看指定客户端的信息 ​

URI ​

请求信息 ​

响应信息 ​

请求示例 ​

响应示例 ​

踢除客户端 ​

URI ​

请求信息 ​

响应消息 ​

请求示例 ​

响应示例 ​

指定客户端订阅主题 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

指定客户端取消订阅主题 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

指定客户端批量订阅主题 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

指定客户端批量取消订阅主题 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

客户端 API

查看所有客户端

URI

请求消息

响应消息

请求示例

响应示例

查看指定客户端的信息

URI

请求信息

响应信息

请求示例

响应示例

踢除客户端

URI

请求信息

响应消息

请求示例

响应示例

指定客户端订阅主题

URI

请求消息

响应消息

请求示例

响应示例

指定客户端取消订阅主题

URI

请求消息

响应消息

请求示例

响应示例

指定客户端批量订阅主题

URI

请求消息

响应消息

请求示例

响应示例

指定客户端批量取消订阅主题

URI

请求消息

响应消息

请求示例

响应示例