Skip to content

客户端 API

本页 API 文档提供了与管理 MQTT 客户端相关的各种操作信息,包括查看所有客户端信息、查看指定客户端信息,以及踢除客户端。

查看所有客户端

URI

GET /clients

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

查询参数:

参数类型描述
_pageInteger页码
_limitInteger每页显示的数据条数
clientidString客户端标识符
usernameString客户端用户名
zoneString客户端配置组名称
ip_addressString客户端 IP 地址
conn_stateEnum客户端当前连接状态, 可取值有:connected,idle,disconnected
clean_startBool客户端是否使用了全新的会话
proto_nameEnum客户端协议名称, 可取值有:MQTT,CoAP,MQTT-SN
proto_verInteger客户端协议版本
_like_clientidString客户端标识符,子串方式模糊查找
_like_usernameString客户端用户名,子串方式模糊查找
_gte_created_atInteger客户端会话创建时间,小于等于查找
_lte_created_atInteger客户端会话创建时间,大于等于查找
_gte_connected_atInteger客户端连接创建时间,小于等于查找
_lte_connected_atInteger客户端连接创建时间,大于等于查找

请求消息

响应消息

名称类型描述
codeInteger0
dataArray of Objects所有客户端的信息
data[].nodeString客户端所连接的节点名称
data[].clientidString客户端标识符
data[].usernameString客户端连接时使用的用户名
data[].proto_nameString客户端协议名称
data[].proto_verInteger客户端使用的协议版本
data[].ip_addressString客户端的 IP 地址
data[].portInteger客户端的端口
data[].is_bridgeBoolean指示客户端是否通过桥接方式连接
data[].connected_atString客户端连接时间,格式为 "YYYY-MM-DD HH:mm:ss"
data[].disconnected_atString客户端离线时间,格式为 "YYYY-MM-DD HH:mm:ss", 此字段仅在 connectedfalse 时有效并被返回
data[].connectedBoolean客户端是否处于连接状态
data[].zoneString指示客户端使用的配置组
data[].keepaliveInteger保持连接时间,单位:秒
data[].clean_startBoolean指示客户端是否使用了全新的会话
data[].expiry_intervalInteger会话过期间隔,单位:秒
data[].created_atString会话创建时间,格式为 "YYYY-MM-DD HH:mm:ss"
data[].subscriptions_cntInteger此客户端已建立的订阅数量
data[].max_subscriptionsInteger此客户端允许建立的最大订阅数量
data[].inflightInteger飞行队列当前长度
data[].max_inflightInteger飞行队列最大长度
data[].mqueue_lenInteger消息队列当前长度
data[].max_mqueueInteger消息队列最大长度
data[].mqueue_droppedInteger消息队列因超出长度而丢弃的消息数量
data[].awaiting_relInteger未确认的 PUBREC 报文数量
data[].max_awaiting_relInteger允许存在未确认的 PUBREC 报文的最大数量
data[].recv_octIntegerEMQX Broker(下同)接收的字节数量
data[].recv_cntInteger接收的 TCP 报文数量
data[].recv_pktInteger接收的 MQTT 报文数量
data[].recv_msgInteger接收的 PUBLISH 报文数量
data[].send_octInteger发送的字节数量
data[].send_cntInteger发送的 TCP 报文数量
data[].send_pktInteger发送的 MQTT 报文数量
data[].send_msgInteger发送的 PUBLISH 报文数量
data[].mailbox_lenInteger进程邮箱大小
data[].heap_sizeInteger进程堆栈大小,单位:字节
data[].reductionsIntegerErlang reduction
metaObject分页信息
meta.pageInteger页码
meta.limitInteger每页显示的数据条数
meta.countInteger数据总条数

请求示例

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

响应示例

JSON
{
  "meta": {
    "page": 1,
    "limit": 10000,
    "hasnext": false,
    "count": 1
  },
  "data": [
    {
      "recv_cnt": 45,
      "send_pkt": 44,
      "clean_start": true,
      "expiry_interval": 0,
      "proto_ver": 4,
      "recv_msg": 0,
      "connected_at": "2021-03-18 02:15:57",
      "recv_oct": 164,
      "is_bridge": false,
      "connected": true,
      "max_awaiting_rel": 100,
      "heap_size": 610,
      "mqueue_dropped": 0,
      "recv_pkt": 2,
      "ip_address": "127.0.0.1",
      "max_subscriptions": 0,
      "created_at": "2021-03-18 02:15:57",
      "awaiting_rel": 0,
      "mountpoint": "undefined",
      "node": "emqx@10.12.50.91",
      "proto_name": "MQTT",
      "mailbox_len": 0,
      "send_msg": 2,
      "clientid": "emqx_c_1",
      "mqueue_len": 0,
      "inflight": 0,
      "max_mqueue": 1000,
      "subscriptions_cnt": 4,
      "keepalive": 60,
      "reductions": 35471,
      "zone": "external",
      "send_cnt": 44,
      "username": "test",
      "send_oct": 159,
      "port": 3107,
      "max_inflight": 32
    }
  ],
  "code": 0
}

查看指定客户端的信息

URI

GET /clients/{clientid}

返回指定客户端的信息

参数:

参数类型描述
clientidStringclientid

请求信息

响应信息

名称类型描述
codeInteger0
dataArray of Objects客户端的信息,详细请参见 GET /clients

请求示例

查询指定客户端

bash
$ curl -u app_id:app_ssecret -X GET {api}/clients/emqx_c_1

响应示例

JSON
{
  "data": [
    {
      "recv_cnt": 49,
      "send_pkt": 48,
      "clean_start": true,
      "expiry_interval": 0,
      "proto_ver": 4,
      "recv_msg": 0,
      "connected_at": "2021-03-18 02:15:57",
      "recv_oct": 172,
      "is_bridge": false,
      "connected": true,
      "max_awaiting_rel": 100,
      "heap_size": 610,
      "mqueue_dropped": 0,
      "recv_pkt": 2,
      "ip_address": "127.0.0.1",
      "max_subscriptions": 0,
      "created_at": "2021-03-18 02:15:57",
      "awaiting_rel": 0,
      "mountpoint": "undefined",
      "node": "emqx@10.12.50.91",
      "proto_name": "MQTT",
      "mailbox_len": 0,
      "send_msg": 2,
      "clientid": "emqx_c_1",
      "mqueue_len": 0,
      "inflight": 0,
      "max_mqueue": 1000,
      "subscriptions_cnt": 4,
      "keepalive": 60,
      "reductions": 38501,
      "zone": "external",
      "send_cnt": 48,
      "username": "test",
      "send_oct": 167,
      "port": 3107,
      "max_inflight": 32
    }
  ],
  "code": 0
}

踢除客户端

URI

DELETE /clients/{clientid}

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

参数:

参数类型描述
clientidStringclientid

请求信息

响应消息

名称类型描述
codeInteger0

请求示例

bash
$ curl -u app_id:app_secret -X DELETE {api}/clients/emqx_c_1

响应示例

JSON
{
  "code": 0
}