客户端

GET /api/v4/clients

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

Query String Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1页码
_limitIntegerFalse10000每页显示的数据条数，未指定时由 emqx-management 插件的配置项 max_row_limit 决定

在 4.1 后，支持多条件和模糊查询，其包含的查询参数有：

NameTypeRequiredDescription
clientidStringFalse客户端标识符
usernameStringFalse客户端用户名
zoneStringFalse客户端配置组名称
ip_addressStringFalse客户端 IP 地址
conn_stateEnumFalse客户端当前连接状态，
可取值有：connected,idle,disconnected
clean_startBoolFalse客户端是否使用了全新的会话
proto_nameEnumFalse客户端协议名称，
可取值有：MQTT,CoAP,LwM2M,MQTT-SN
proto_verIntegerFalse客户端协议版本
_like_clientidStringFalse客户端标识符，子串方式模糊查找
_like_usernameStringFalse客户端用户名，子串方式模糊查找
_gte_created_atIntegerFalse客户端会话创建时间，小于等于查找
_lte_created_atIntegerFalse客户端会话创建时间，大于等于查找
_gte_connected_atIntegerFalse客户端连接创建时间，小于等于查找
_lte_connected_atIntegerFalse客户端连接创建时间，大于等于查找

Success Response Body (JSON):

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

Examples:

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients?_page=1&_limit=10"
  3. {"meta":{"page":1,"limit":10,"count":1},"data":[{"zone":"external","recv_cnt":2,"max_mqueue":1000,"node":"emqx@127.0.0.1","username":"test","mqueue_len":0,"max_inflight":32,"is_bridge":false,"mqueue_dropped":0,"inflight":0,"heap_size":2586,"max_subscriptions":0,"proto_name":"MQTT","created_at":"2020-02-19 17:01:26","proto_ver":4,"reductions":3997,"send_msg":0,"ip_address":"127.0.0.1","send_cnt":0,"mailbox_len":1,"awaiting_rel":0,"keepalive":60,"recv_msg":0,"send_pkt":0,"recv_oct":29,"clientid":"example","clean_start":true,"expiry_interval":0,"connected":true,"port":64491,"send_oct":0,"recv_pkt":1,"connected_at":"2020-02-19 17:01:26","max_awaiting_rel":100,"subscriptions_cnt":0}],"code":0}

注：在 4.1 后，返回的 meta 内容做了修改：

  • count：仍表示总数，但在 多条件/模糊查询时，固定为 -1。
  • hasnext：为新增字段，表示是否存在下一页。

GET /api/v4/clients/{clientid}

返回指定客户端的信息

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息，详细请参见
GET /api/v4/clients

Examples:

查询指定客户端

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/example"
  3. {"data":[{"recv_cnt":2,"max_subscriptions":0,"node":"emqx@127.0.0.1","proto_ver":4,"recv_pkt":1,"inflight":0,"max_mqueue":1000,"heap_size":2586,"username":"test","proto_name":"MQTT","subscriptions_cnt":0,"send_pkt":0,"created_at":"2020-02-20 13:38:51","reductions":3978,"ip_address":"127.0.0.1","send_msg":0,"send_cnt":0,"expiry_interval":0,"keepalive":60,"mqueue_dropped":0,"is_bridge":false,"max_inflight":32,"recv_msg":0,"max_awaiting_rel":100,"awaiting_rel":0,"mailbox_len":1,"mqueue_len":0,"recv_oct":29,"connected_at":"2020-02-20 13:38:51","clean_start":true,"clientid":"example","connected":true,"port":54889,"send_oct":0,"zone":"external"}],"code":0}

DELETE /api/v4/clients/{clientid}

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

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

踢除指定客户端

  1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/clients/example"
  3. {"code":0}

GET /api/v4/nodes/{node}/clients

类似 GET /api/v4/clients，返回指定节点下所有客户端的信息，支持分页。

Query String Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1页码
_limitIntegerFalse10000每页显示的数据条数，未指定时由 emqx-management 插件的配置项 max_row_limit 决定

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有客户端的信息，详情请参看 GET /api/v4/clients

Examples:

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients?_page=1&_limit=10"
  3. {"meta":{"page":1,"limit":10,"count":1},"data":[{"recv_cnt":2,"max_subscriptions":0,"node":"emqx@127.0.0.1","proto_ver":4,"recv_pkt":1,"inflight":0,"max_mqueue":1000,"heap_size":2586,"username":"test","proto_name":"MQTT","subscriptions_cnt":0,"send_pkt":0,"created_at":"2020-02-19 18:25:18","reductions":4137,"ip_address":"127.0.0.1","send_msg":0,"send_cnt":0,"expiry_interval":0,"keepalive":60,"mqueue_dropped":0,"is_bridge":false,"max_inflight":32,"recv_msg":0,"max_awaiting_rel":100,"awaiting_rel":0,"mailbox_len":1,"mqueue_len":0,"recv_oct":29,"connected_at":"2020-02-19 18:25:18","clean_start":true,"clientid":"example","connected":true,"port":49509,"send_oct":0,"zone":"external"}],"code":0}

GET /api/v4/nodes/{node}/clients/{clientid}

类似 GET /api/v4/clients/{clientid}，返回指定节点下指定客户端的信息。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject客户端的信息，详细请参见
GET /api/v4/clients

Examples:

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/example"
  3. {"data":[{"recv_cnt":4,"max_subscriptions":0,"node":"emqx@127.0.0.1","proto_ver":4,"recv_pkt":1,"inflight":0,"max_mqueue":1000,"heap_size":2586,"username":"test","proto_name":"MQTT","subscriptions_cnt":0,"send_pkt":3,"created_at":"2020-02-20 13:38:51","reductions":5994,"ip_address":"127.0.0.1","send_msg":0,"send_cnt":3,"expiry_interval":0,"keepalive":60,"mqueue_dropped":0,"is_bridge":false,"max_inflight":32,"recv_msg":0,"max_awaiting_rel":100,"awaiting_rel":0,"mailbox_len":0,"mqueue_len":0,"recv_oct":33,"connected_at":"2020-02-20 13:38:51","clean_start":true,"clientid":"example","connected":true,"port":54889,"send_oct":8,"zone":"external"}],"code":0}

DELETE /api/v4/nodes/{node}/clients/{clientid}

类似 DELETE /api/v4/clients/{clientid}，踢除指定节点下的指定客户端。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

  1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/example"
  3. {"code":0}

GET /api/v4/clients/username/{username}

通过 Username 查询客户端的信息。由于可能存在多个客户端使用相同的用户名的情况，所以可能同时返回多个客户端信息。

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息，详细请参见
GET /api/v4/clients

Examples:

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/username/steve"
  3. {"data":[{"clean_start":true,"awaiting_rel":0,"recv_msg":0,"proto_name":"MQTT","recv_cnt":2,"mailbox_len":0,"node":"emqx@127.0.0.1","mqueue_len":0,"max_subscriptions":0,"created_at":"2020-02-20 13:50:11","is_bridge":false,"heap_size":2586,"proto_ver":4,"subscriptions_cnt":0,"clientid":"example","expiry_interval":0,"send_msg":0,"inflight":0,"reductions":4673,"send_pkt":1,"zone":"external","send_cnt":1,"ip_address":"127.0.0.1","keepalive":60,"max_inflight":32,"recv_oct":29,"recv_pkt":1,"max_awaiting_rel":100,"username":"steve","connected_at":"2020-02-20 13:50:11","connected":true,"port":56429,"send_oct":4,"mqueue_dropped":0,"max_mqueue":1000}],"code":0}

GET /api/v4/nodes/{node}/clients/username/{username}

类似 GET /api/v4/clients/username/{username}，在指定节点下，通过 Username 查询指定客户端的信息。

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息，详细请参见
GET /api/v4/clients

Examples:

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/username/test"
  3. {"data":[{"clean_start":true,"awaiting_rel":0,"recv_msg":0,"proto_name":"MQTT","recv_cnt":6,"mailbox_len":0,"node":"emqx@127.0.0.1","mqueue_len":0,"max_subscriptions":0,"created_at":"2020-02-20 13:50:11","is_bridge":false,"heap_size":1598,"proto_ver":4,"subscriptions_cnt":0,"clientid":"example","expiry_interval":0,"send_msg":0,"inflight":0,"reductions":7615,"send_pkt":5,"zone":"external","send_cnt":5,"ip_address":"127.0.0.1","keepalive":60,"max_inflight":32,"recv_oct":37,"recv_pkt":1,"max_awaiting_rel":100,"username":"test","connected_at":"2020-02-20 13:50:11","connected":true,"port":56429,"send_oct":12,"mqueue_dropped":0,"max_mqueue":1000}],"code":0}

GET /api/v4/clients/{clientid}/acl_cache

查询指定客户端的 ACL 缓存。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsACL 详情
data[0].accessString发布/订阅
data[0].topicStringMQTT 主题
data[0].resultString允许/拒绝
data[0].updated_timeIntegerACL 缓存建立时间

Examples:

查询 ACL 缓存

  1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/example/acl_cache"
  3. {"data":[{"updated_time":1582180824571,"topic":"test","result":"allow","access":"publish"}],"code":0}

DELETE /api/v4/clients/{clientid}/acl_cache

清除指定客户端的 ACL 缓存。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

清除 ACL 缓存

  1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/clients/example/acl_cache"
  3. {"code":0}