# REST API

EMQ X Cloud API 遵循REST体系结构,您可以通过编程方式访问 EMQ X 的功能。

# API 地址

您可以在部署详情页面下的 API 访问中,获取到 API 访问地址

api-access

假如我们想要获取所有节点的信息,可以这样去调用:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/brokers"
1

# 接口安全

HTTP API 使用 Basic 认证 (opens new window) 方式,id 和 password 须分别填写 AppID 和 AppSecret。 您可以在部署详情页面下的 API 访问中,通过创建应用访问来修改和添加 AppID/AppSecret。

api-app

# 响应码

# HTTP 状态码 (status codes)

接口在调用成功时总是返回 200 OK,响应内容则以 JSON 格式返回。

可能的状态码如下:

Status CodeDescription
200成功,返回的 JSON 数据将提供更多信息
400客户端请求无效,例如请求体或参数错误
401客户端未通过服务端认证,使用无效的身份验证凭据可能会发生
404找不到请求的路径或者请求的对象不存在
500服务端处理请求时发生内部错误

# 返回码 (result codes)

接口的响应消息体为 JSON 格式,其中总是包含返回码 code

可能的返回码如下:

Return CodeDescription
0成功
101RPC 错误
102未知错误
103用户名或密码错误
104空用户名或密码
105用户不存在
106管理员账户不可删除
107关键请求参数缺失
108请求参数错误
109请求参数不是合法 JSON 格式
110插件已开启
111插件已关闭
112客户端不在线
113用户已存在
114旧密码错误
115不合法的主题

# API Endpoints

# Broker 基本信息

# 获取集群下节点的基本信息

GET /brokers/{node}

URL 路径参数

NameTypeRequiredDescription
nodeStringFalse节点名字,如 "emqx@127.0.0.1。 不指定时返回所有节点的信息

成功响应消息元素 (JSON)

NameTypeDescription
codeInteger0
dataObject/Array of Objectsnode 参数存在时返回指定节点信息, 不存在时返回所有节点的信息
data.datetimeString当前时间,格式为 "YYYY-MM-DD HH:mm:ss"
data.nodeString节点名称
data.node_statusString节点状态
data.otp_releaseStringEMQ X 使用的 Erlang/OTP 版本
data.sysdescrString软件描述
data.uptimeStringEMQ X 运行时间,格式为 "H hours, m minutes, s seconds"
data.versionStringEMQ X 版本

示例

获取所有节点的基本信息:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/brokers"

{"data":[{"version":"develop","uptime":"4 hours, 21 minutes, 19 seconds","sysdescr":"EMQ X Broker","otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","datetime":"2020-02-19 15:27:24"}],"code":0}
1
2
3

获取节点 emqx@127.0.0.1 的基本信息:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/brokers/emqx@127.0.0.1"

{"data":{"version":"develop","uptime":"1 minutes, 51 seconds","sysdescr":"EMQ X Broker","otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","datetime":"2020-02-20 14:11:31"},"code":0}
1
2
3

# 节点

# 获取节点的状态

GET /nodes/{node}

URL 路径参数

NameTypeRequiredDescription
nodeStringFalse节点名字,如 "emqx@127.0.0.1。 不指定时返回所有节点的信息

成功响应消息元素 (JSON)

NameTypeDescription
codeInteger0
dataObject/Array of Objectsnode 参数存在时返回指定节点信息, 不存在时以 Array 形式返回所有节点的信息
data.connectionsInteger当前接入此节点的客户端数量
data.load1String1 分钟内的 CPU 平均负载
data.load5String5 分钟内的 CPU 平均负载
data.load15String15 分钟内的 CPU 平均负载
data.max_fdsInteger操作系统的最大文件描述符限制
data.memory_totalStringVM 已分配的系统内存
data.memory_usedStringVM 已占用的内存大小
data.nodeString节点名称
data.node_statusString节点状态
data.otp_releaseStringEMQ X 使用的 Erlang/OTP 版本
data.process_availableInteger可用的进程数量
data.process_usedInteger已占用的进程数量
data.uptimeStringEMQ X 运行时间
data.versionStringEMQ X 版本

示例

获取所有节点的状态:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes"

{"data":[{"version":"develop","uptime":"7 seconds","process_used":315,"process_available":2097152,"otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","memory_used":"96.75M","memory_total":"118.27M","max_fds":10240,"load5":"2.60","load15":"2.65","load1":"2.31","connections":0}],"code":0}
1
2
3

获取指定节点的状态:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1"

{"data":{"version":"develop","uptime":"2 minutes, 21 seconds","process_used":310,"process_available":2097152,"otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","memory_used":101379168,"memory_total":123342848,"max_fds":10240,"load5":"2.50","load15":"2.61","load1":"1.99","connections":0},"code":0}
1
2
3

# 管理认证数据

# 查看已经添加的认证数据

GET /auth_user

URL 查询参数:

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

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有认证数据
data[0].loginString登录用户名
data[0].passwordString登录密码
data[0].is_superuserBoolean是否为超级用户
metaObject分页信息
meta.pageInteger页码
meta.limitInteger每页显示的数据条数
meta.countInteger数据总条数

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user"

{"meta":{"page":1,"limit":10,"count":3},"data":[{"password":"efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7","login":"test1","is_superuser":false},{"password":"efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7","login":"test2","is_superuser":false},{"password":"efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7","login":"test3","is_superuser":false}],"code":0}
1
2
3

# 批量添加认证数据

POST /auth_user

请求消息元素 (json):

NameTypeRequiredDescription
[0].loginStringTrue登录用户名
[0].passwordStringTrue登录密码
[0]is_superuserBooleanTrue是否为超级用户

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects认证数据添加状态,ok 表示对应的认证数据添加成功

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user" -d '[{"login":"test5","password":"public", "is_superuser": false}]'

{"data":{"test5":"ok"},"code":0}
1
2
3

# 更新已添加的认证数据

PUT /auth_user/${login}

请求消息元素 (json):

NameTypeRequiredDescription
passwordStringTrue登录密码
is_superuserBooleanTrue是否为超级用户

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X PUT "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user/test5" -d '{"password":"public1", "is_superuser": false}'

{"code":0}
1
2
3

# 删除认证数据

DELETE /auth_user/${login}

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user/test5"

{"code":0}
1
2
3

# 客户端

# 获取集群下所有客户端的信息

GET /clients

URL 查询参数:

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客户端连接创建时间,大于等于查找

成功响应消息元素 (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", 此字段仅在 connectedfalse 时有效并被返回
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数据总条数

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients?_page=1&_limit=10"

{"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}
1
2
3

注:在 4.1 后,返回的 meta 内容做了修改:

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

# 获取指定客户端的信息

GET /clients/{clientid}

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息,详细请参见 GET /api/clients (opens new window)

示例:

查询指定客户端

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example"

{"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}
1
2
3

# 踢除指定客户端

DELETE /clients/{clientid}

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

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

踢除指定客户端

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example"

{"code":0}
1
2
3

# 获取指定节点下所有客户端的信息

GET /nodes/{node}/clients

URL 查询参数:

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

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有客户端的信息,详情请参看 GET /api/clients (opens new window)

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/clients?_page=1&_limit=10"

{"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}
1
2
3

# 获取指定节点下指定客户端的信息

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

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject客户端的信息,详细请参见 GET /api/clients (opens new window)

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/clients/example"

{"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}
1
2
3

# 通过 Username 查询客户端的信息

GET /clients/username/{username}

由于可能存在多个客户端使用相同的用户名的情况,所以可能同时返回多个客户端信息。

URL 路径参数:

NameTypeRequiredDescription
usernameStringTrueUsername

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息,详细请参见 GET /api/clients (opens new window)

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/username/steve"

{"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}
1
2
3

# 在指定节点下,通过 Username 查询指定客户端的信息

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

URL 路径参数:

NameTypeRequiredDescription
usernameStringTrueUsername

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息,详细请参见 GET /api/clients (opens new window)

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/clients/username/test"

{"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}
1
2
3

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

GET /clients/{clientid}/acl_cache

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

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

示例:

查询 ACL 缓存

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example/acl_cache"

{"data":[{"updated_time":1582180824571,"topic":"test","result":"allow","access":"publish"}],"code":0}
1
2
3

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

DELETE /clients/{clientid}/acl_cache

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

清除 ACL 缓存

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example/acl_cache"

{"code":0}
1
2
3

# 订阅信息

# 获取集群下所有订阅信息

GET /subscriptions

URL 查询参数:

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

在 4.1 版本后,支持多条件和模糊查询,对应的查询参数如下:

NameTypeDescription
clientidString客户端标识符
topicString主题,全等查询
qosEnum可取值为:0,1,2
shareString共享订阅的组名称
_match_topicString主题,匹配查询

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有订阅信息
data[0].nodeString节点名称
data[0].clientidString客户端标识符
data[0].topicString订阅主题
data[0].qosIntegerQoS 等级
metaObject/api/clients

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/subscriptions?_page=1&_limit=10"

{"meta":{"page":1,"limit":10000,"count":2},"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"78082755-e8eb-4a87-bab7-8277541513f0"},{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"7a1dfceb-89c0-4f7e-992b-dfeb09329f01"}],"code":0}
1
2
3

注:在 4.1 后,返回的 meta 内容做了修改:

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

# 获取集群下指定客户端的订阅信息

GET /subscriptions/{clientid}

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject所有订阅信息
data.nodeString节点名称
data.clientidString客户端标识符
data.topicString订阅主题
data.qosIntegerQoS 等级

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/subscriptions/123"

{"data":[{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"123"}],"code":0}
1
2
3

# 获取指定节点下的所有订阅信息

GET /nodes/{node}/subscriptions

URL 查询参数:

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

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有订阅信息
data[0].nodeString节点名称
data[0].clientidString客户端标识符
data[0].topicString订阅主题
data[0].qosIntegerQoS 等级
metaObject/api/clients

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/subscriptions?_page=1&limit=10"

{"meta":{"page":1,"limit":10000,"count":2},"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"78082755-e8eb-4a87-bab7-8277541513f0"},{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"7a1dfceb-89c0-4f7e-992b-dfeb09329f01"}],"code":0}
1
2
3

# 在指定节点下,查询某 clientid 的所有订阅信息

GET /nodes/{node}/subscriptions/{clientid}

URL 路径参数:

NameTypeRequiredDescription
clientidStringTrueClientID

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject所有订阅信息
data.nodeString节点名称
data.clientidString客户端标识符
data.topicString订阅主题
data.qosIntegerQoS 等级

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/subscriptions/sample"

{"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"sample"}],"code":0}
1
2
3

# 路由

# 获取集群下的所有路由信息

GET /routes

URL 查询参数:

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

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有路由信息
data[0].topicStringMQTT 主题
data[0].nodeString节点名称
metaObject/api/clients

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/routes"

{"meta":{"page":1,"limit":10000,"count":2},"data":[{"topic":"a/+/c","node":"emqx@127.0.0.1"},{"topic":"a/b/c","node":"emqx@127.0.0.1"}],"code":0}
1
2
3

# 获取集群下指定主题的路由信息

GET /routes/{topic}

URL 路径参数:

NameTypeRequiredDescription
topicIntegerTrue主题

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject所有路由信息
data.topicStringMQTT 主题
data.nodeString节点名称

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/routes/a%2fb%2fc"

{"data":[{"topic":"a/b/c","node":"emqx@127.0.0.1"}],"code":0}
1
2
3

# 发布订阅 ACL

# 查看已经添加的 ACL 规则

GET /emqx_acl

URL 查询参数:

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

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有认证数据
data[0].topicString指定的主题
data[0].loginString指定的登录用户名
data[0].allowBoolean是否允许
data[0].actionStringACL 规则动作
metaObject分页信息
meta.pageInteger页码
meta.limitInteger每页显示的数据条数
meta.countInteger数据总条数

示例:

curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/emqx_acl"

{"meta":{"page":1,"limit":10,"count":2},"data":[{"topic":"/test1","login":"test1","allow":true,"action":"pubsub"},{"topic":"/test","login":"test2","allow":true,"action":"pubsub"}],"code":0}
1
2
3

# 批量添加 ACL 规则

POST /emqx_acl

请求消息元素 (json):

NameTypeRequiredDescription
data[0].topicStringTrue指定的主题
data[0].loginStringTrue指定的登录用户名
data[0].allowBooleanTrue是否允许
data[0].actionStringTrueACL 规则动作

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsACL 规则添加状态,ok 表示对应的 ACL 规则添加成功

示例:

curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/emqx_acl" -d
'[{"topic":"test","login":"test3","allow":false,"action":"pubsub"}]'

{"data":{"test3":"ok"},"code":0}
1
2
3
4

# 删除 ACL 规则

DELETE /emqx_acl/${login}/${topic}

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/emqx_acl/emqx_acl/test3/test"

{"code":0}
1
2
3

# 消息发布

# 发布 MQTT 消息

POST /mqtt/publish

请求消息元素 (json):

NameTypeRequiredDefaultDescription
topicStringOptional主题,与 topics 至少指定其中之一
topicsStringOptional, 分割的多个主题,使用此字段能够同时发布消息到多个主题
clientidStringRequired客户端标识符
payloadStringRequired消息正文
encodingStringOptionalplain消息正文使用的编码方式,目前仅支持 plainbase64 两种
qosIntegerOptional0QoS 等级
retainBooleanOptionalfalse是否为保留消息

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/publish" -d '{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example"}'

{"code":0}
1
2
3

# 批量发布 MQTT 消息

POST /mqtt/publish_batch

请求消息元素 (json):

NameTypeRequiredDefaultDescription
[0].topicStringOptional主题,与 topics 至少指定其中之一
[0].topicsStringOptional, 分割的多个主题,使用此字段能够同时发布消息到多个主题
[0].clientidStringRequired客户端标识符
[0].payloadStringRequired消息正文
[0].encodingStringOptionalplain消息正文使用的编码方式,目前仅支持 plainbase64 两种
[0].qosIntegerOptional0QoS 等级
[0].retainBooleanOptionalfalse是否为保留消息

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/publish_batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example"},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example"}]'

{"code":0}
1
2
3

# 主题订阅

# 订阅 MQTT 主题

POST /mqtt/subscribe

请求消息元素 (json):

NameTypeRequiredDefaultDescription
topicStringOptional主题,与 topics 至少指定其中之一
topicsStringOptional, 分割的多个主题,使用此字段能够同时订阅多个主题
clientidStringRequired客户端标识符
qosIntegerOptional0QoS 等级

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

同时订阅 a, b, c 三个主题

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/subscribe" -d '{"topics":"a,b,c","qos":1,"clientid":"example"}'

{"code":0}
1
2
3

# 取消订阅

POST /mqtt/unsubscribe

请求消息元素 (json):

NameTypeRequiredDefaultDescription
topicStringRequired主题
clientidStringRequired客户端标识符

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

取消订阅 a 主题

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'

{"code":0}
1
2
3

# 批量订阅 MQTT 主题

POST /mqtt/subscribe_batch

请求消息元素 (json):

NameTypeRequiredDefaultDescription
[0].topicStringOptional主题,与 topics 至少指定其中之一
[0].topicsStringOptional, 分割的多个主题,使用此字段能够同时订阅多个主题
[0].clientidStringRequired客户端标识符
[0].qosIntegerOptional0QoS 等级

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

一次性订阅 a, b, c 三个主题

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/subscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"},{"topic":"c","qos":1,"clientid":"example"}]'

{"code":0}
1
2
3

# 批量取消订阅

POST /mqtt/unsubscribe_batch

请求消息元素 (json):

NameTypeRequiredDefaultDescription
[0].topicStringRequired主题
[0].clientidStringRequired客户端标识符

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

一次性取消订阅 a, b 主题

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/unsubscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"}]'

{"code":0}
1
2
3

# 监听器

# 获取集群下的所有监听器信息

GET /listeners

URL 路径参数:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects各节点的监听器列表
data[0].nodeString节点名称
data[0].listenersArray of Objects监听器列表
data[0].listeners[0].acceptorsIntegerAcceptor 进程数量
data[0].listeners[0].listen_onString监听端口
data[0].listeners[0].protocolString插件描述
data[0].listeners[0].current_connsInteger插件是否启动
data[0].listeners[0].max_connsInteger允许建立的最大连接数量
data[0].listeners[0].shutdown_countArray of Objects连接关闭原因及计数

常见 shutdown_count

NameTypeDescription
normalInteger正常关闭的连接数量,仅在计数大于 0 时返回
kickedInteger被手动踢除的连接数量,仅在计数大于 0 时返回
discardedInteger由于 Clean SessionClean Starttrue 而被丢弃的连接数量
takeoveredInteger由于 Clean SessionClean Startfalse 而被接管的连接数量

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/listeners"

{"data":[{"node":"emqx@127.0.0.1","listeners":[{"shutdown_count":[],"protocol":"mqtt:ssl","max_conns":102400,"listen_on":"8883","current_conns":0,"acceptors":16},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"0.0.0.0:1883","current_conns":13,"acceptors":8},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"127.0.0.1:11883","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:dashboard","max_conns":512,"listen_on":"18083","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:management","max_conns":512,"listen_on":"8081","current_conns":1,"acceptors":2},{"shutdown_count":[],"protocol":"https:dashboard","max_conns":512,"listen_on":"18084","current_conns":0,"acceptors":2},{"shutdown_count":[],"protocol":"mqtt:ws:8083","max_conns":102400,"listen_on":"8083","current_conns":1,"acceptors":4},{"shutdown_count":[],"protocol":"mqtt:wss:8084","max_conns":16,"listen_on":"8084","current_conns":0,"acceptors":4}]}],"code":0}
1
2
3

# 获取指定节点的监听器信息

GET /nodes/{node}/listeners

URL 路径参数:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects各节点的监听器列表
data[0].acceptorsIntegerAcceptor 进程数量
data[0].listen_onString监听端口
data[0].protocolString插件描述
data[0].current_connsInteger插件是否启动
data[0].max_connsInteger允许建立的最大连接数量
data[0].shutdown_countArray of Objects连接关闭原因及计数

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/listeners"

{"data":[{"shutdown_count":[],"protocol":"mqtt:ssl","max_conns":102400,"listen_on":"8883","current_conns":0,"acceptors":16},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"0.0.0.0:1883","current_conns":13,"acceptors":8},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"127.0.0.1:11883","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:dashboard","max_conns":512,"listen_on":"18083","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:management","max_conns":512,"listen_on":"8081","current_conns":1,"acceptors":2},{"shutdown_count":[],"protocol":"https:dashboard","max_conns":512,"listen_on":"18084","current_conns":0,"acceptors":2},{"shutdown_count":[],"protocol":"mqtt:ws:8083","max_conns":102400,"listen_on":"8083","current_conns":1,"acceptors":4},{"shutdown_count":[],"protocol":"mqtt:wss:8084","max_conns":16,"listen_on":"8084","current_conns":0,"acceptors":4}],"code":0}
1
2
3

# 统计指标

# 获取集群下所有统计指标数据

GET /metrics

URL 路径参数:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects各节点上的统计指标列表
data[0].nodeString节点名称
data[0].metricsObject监控指标数据,详见下面的 metrics:

metrics:

NameTypeDescription
actions.failureInteger规则引擎 action 成功失败次数
actions.successInteger规则引擎 action 执行失败次数
bytes.receivedIntegerEMQ X 接收的字节数
bytes.sentIntegerEMQ X 在此连接上发送的字节数
client.authenticateInteger客户端认证次数
client.auth.anonymousInteger匿名登录的客户端数量
client.connectInteger客户端连接次数
client.connackInteger发送 CONNACK 报文的次数
client.connectedInteger客户端成功连接次数
client.disconnectedInteger客户端断开连接次数
client.check_aclIntegerACL 规则检查次数
client.subscribeInteger客户端订阅次数
client.unsubscribeInteger客户端取消订阅次数
delivery.dropped.too_largeInteger发送时由于长度超过限制而被丢弃的消息数量
delivery.dropped.queue_fullInteger发送时由于消息队列满而被丢弃的 QoS 不为 0 的消息数量
delivery.dropped.qos0_msgInteger发送时由于消息队列满而被丢弃的 QoS 为 0 的消息数量
delivery.dropped.expiredInteger发送时由于消息过期而被丢弃的消息数量
delivery.dropped.no_localInteger发送时由于 No Local 订阅选项而被丢弃的消息数量
delivery.droppedInteger发送时丢弃的消息总数
messages.delayedIntegerEMQ X 存储的延迟发布的消息数量
messages.deliveredIntegerEMQ X 内部转发到订阅进程的消息数量
messages.droppedIntegerEMQ X 内部转发到订阅进程前丢弃的消息总数
messages.dropped.expiredInteger接收时由于消息过期而被丢弃的消息数量
messages.dropped.no_subscribersInteger由于没有订阅者而被丢弃的消息数量
messages.forwardInteger向其他节点转发的消息数量
messages.publishInteger除系统消息外发布的消息数量
messages.qos0.receivedInteger接收来自客户端的 QoS 0 消息数量
messages.qos2.receivedInteger接收来自客户端的 QoS 1 消息数量
messages.qos1.receivedInteger接收来自客户端的 QoS 2 消息数量
messages.qos0.sentInteger发送给客户端的 QoS 0 消息数量
messages.qos1.sentInteger发送给客户端的 QoS 1 消息数量
messages.qos2.sentInteger发送给客户端的 QoS 2 消息数量
messages.receivedInteger接收来自客户端的消息数量,等于 messages.qos0.receivedmessages.qos1.receivedmessages.qos2.received 之和
messages.sentInteger发送给客户端的消息数量,等于 messages.qos0.sentmessages.qos1.sentmessages.qos2.sent 之和
messages.retainedIntegerEMQ X 存储的保留消息数量
messages.ackedInteger接收的 PUBACK 和 PUBREC 报文数量
packets.receivedInteger接收的报文数量
packets.sentInteger发送的报文数量
packets.connect.receivedInteger接收的 CONNECT 报文数量
packets.connack.auth_errorInteger接收的认证失败的 CONNECT 报文数量
packets.connack.errorInteger接收的未成功连接的 CONNECT 报文数量
packets.connack.sentInteger发送的 CONNACK 报文数量
packets.publish.receivedInteger接收的 PUBLISH 报文数量
packets.publish.sentInteger发送的 PUBLISH 报文数量
packets.publish.inuseInteger接收的报文标识符已被占用的 PUBLISH 报文数量
packets.publish.auth_errorInteger接收的未通过 ACL 检查的 PUBLISH 报文数量
packets.publish.errorInteger接收的无法被发布的 PUBLISH 报文数量
packets.publish.droppedInteger超出接收限制而被丢弃的消息数量
packets.puback.receivedInteger接收的 PUBACK 报文数量
packets.puback.sentInteger发送的 PUBACK 报文数量
packets.puback.inuseInteger接收的报文标识符已被占用的 PUBACK 报文数量
packets.puback.missedInteger接收的未知报文标识符 PUBACK 报文数量
packets.pubrec.receivedInteger接收的 PUBREC 报文数量
packets.pubrec.sentInteger发送的 PUBREC 报文数量
packets.pubrec.inuseInteger接收的报文标识符已被占用的 PUBREC 报文数量
packets.pubrec.missedInteger接收的未知报文标识符 PUBREC 报文数量
packets.pubrel.receivedInteger接收的 PUBREL 报文数量
packets.pubrel.sentInteger发送的 PUBREL 报文数量
packets.pubrel.missedInteger接收的未知报文标识符 PUBREL 报文数量
packets.pubcomp.receivedInteger接收的 PUBCOMP 报文数量
packets.pubcomp.sentInteger发送的 PUBCOMP 报文数量
packets.pubcomp.inuseInteger接收的报文标识符已被占用的 PUBCOMP 报文数量
packets.pubcomp.missedInteger发送的 PUBCOMP 报文数量
packets.subscribe.receivedInteger接收的 SUBSCRIBE 报文数量
packets.subscribe.errorInteger接收的订阅失败的 SUBSCRIBE 报文数量
packets.subscribe.auth_errorInteger接收的未通过 ACL 检查的 SUBACK 报文数量
packets.suback.sentInteger发送的 SUBACK 报文数量
packets.unsubscribe.receivedInteger接收的 UNSUBSCRIBE 报文数量
packets.unsubscribe.errorInteger接收的取消订阅失败的 UNSUBSCRIBE 报文数量
packets.unsuback.sentInteger发送的 UNSUBACK 报文数量
packets.pingreq.receivedInteger接收的 PINGREQ 报文数量
packets.pingresp.sentInteger发送的 PUBRESP 报文数量
packets.disconnect.receivedInteger接收的 DISCONNECT 报文数量
packets.disconnect.sentInteger发送的 DISCONNECT 报文数量
packets.auth.receivedInteger接收的 AUTH 报文数量
packets.auth.sentInteger发送的 AUTH 报文数量
rules.matchedInteger规则的匹配次数
session.createdInteger创建的会话数量
session.discardedInteger由于 Clean SessionClean Starttrue 而被丢弃的会话数量
session.resumedInteger由于 Clean SessionClean Startfalse 而恢复的会话数量
session.takeoveredInteger由于 Clean SessionClean Startfalse 而被接管的会话数量
session.terminatedInteger终结的会话数量

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/metrics"

{"data":[{"node":"emqx@127.0.0.1","metrics":{"messages.dropped.no_subscribers":0,"packets.connack.sent":13,"bytes.received":805,"messages.received":0,"packets.unsuback.sent":0,"messages.delivered":0,"client.disconnected":0,"packets.puback.sent":0,"packets.subscribe.auth_error":0,"delivery.dropped.queue_full":0,"messages.forward":0,"delivery.dropped.qos0_msg":0,"delivery.dropped.expired":0,"bytes.sent":52,"messages.sent":0,"delivery.dropped.no_local":0,"packets.pubrec.received":0,"packets.pubcomp.received":0,"client.check_acl":0,"packets.puback.received":0,"session.takeovered":0,"messages.dropped.expired":0,"actions.success":0,"messages.qos1.sent":0,"messages.retained":0,"packets.pubcomp.inuse":0,"packets.pubrec.sent":0,"packets.received":13,"messages.acked":0,"session.terminated":0,"packets.sent":13,"packets.unsubscribe.error":0,"client.connect":13,"packets.pubrec.missed":0,"packets.auth.sent":0,"packets.disconnect.received":0,"messages.qos2.sent":0,"client.auth.anonymous":13,"packets.auth.received":0,"packets.unsubscribe.received":0,"packets.publish.auth_error":0,"client.connected":13,"rules.matched":0,"packets.disconnect.sent":0,"session.created":13,"packets.pingreq.received":0,"messages.dropped":0,"actions.failure":0,"packets.publish.sent":0,"session.resumed":0,"packets.connack.auth_error":0,"packets.pubrel.sent":0,"delivery.dropped":0,"packets.pubcomp.sent":0,"messages.qos2.received":0,"messages.qos0.received":0,"packets.publish.inuse":0,"client.unsubscribe":0,"packets.pubrel.received":0,"client.connack":13,"packets.connack.error":0,"packets.publish.dropped":0,"packets.publish.received":0,"client.subscribe":0,"packets.subscribe.error":0,"packets.suback.sent":0,"packets.pubcomp.missed":0,"messages.qos1.received":0,"delivery.dropped.too_large":0,"packets.pingresp.sent":0,"packets.pubrel.missed":0,"messages.qos0.sent":0,"packets.connect.received":13,"packets.puback.missed":0,"packets.subscribe.received":0,"packets.puback.inuse":0,"client.authenticate":13,"messages.publish":0,"packets.pubrec.inuse":0,"packets.publish.error":0,"messages.delayed":0,"session.discarded":0}}],"code":0}
1
2
3

# 获取指定节点下所有监控指标数据

GET /nodes/{node}/metrics

URL 路径参数:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject各节点上的统计指标列表,详见 GET /api/metrics (opens new window)

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/metrics"

{"data":{"bytes.received":0,"client.connected":0,"packets.pingreq.received":0,"messages.delayed":0,"rules.matched":0,"actions.failure":0,"packets.puback.sent":0,"packets.pingresp.sent":0,"packets.publish.auth_error":0,"client.check_acl":0,"delivery.dropped.queue_full":0,"actions.success":0,"packets.publish.error":0,"packets.pubcomp.received":0,"bytes.sent":0,"packets.pubrec.inuse":0,"packets.pubrec.missed":0,"packets.pubrel.sent":0,"delivery.dropped.too_large":0,"packets.pubcomp.missed":0,"packets.subscribe.error":0,"packets.suback.sent":0,"messages.qos2.sent":0,"messages.qos1.sent":0,"packets.pubrel.missed":0,"messages.publish":0,"messages.forward":0,"packets.auth.received":0,"delivery.dropped":0,"packets.sent":0,"packets.puback.inuse":0,"delivery.dropped.qos0_msg":0,"packets.publish.dropped":0,"packets.disconnect.sent":0,"packets.auth.sent":0,"packets.unsubscribe.received":0,"session.takeovered":0,"messages.delivered":0,"client.auth.anonymous":0,"packets.connack.error":0,"packets.connack.sent":0,"packets.subscribe.auth_error":0,"packets.unsuback.sent":0,"packets.pubcomp.sent":0,"packets.publish.sent":0,"client.connack":0,"packets.publish.received":0,"client.subscribe":0,"session.created":0,"delivery.dropped.expired":0,"client.unsubscribe":0,"packets.received":0,"packets.pubrel.received":0,"packets.unsubscribe.error":0,"messages.qos0.sent":0,"packets.connack.auth_error":0,"session.resumed":0,"delivery.dropped.no_local":0,"packets.puback.missed":0,"packets.pubcomp.inuse":0,"packets.pubrec.sent":0,"messages.dropped.expired":0,"messages.dropped.no_subscribers":0,"session.discarded":0,"messages.sent":0,"messages.received":0,"packets.puback.received":0,"messages.qos0.received":0,"messages.acked":0,"client.connect":0,"packets.disconnect.received":0,"client.disconnected":0,"messages.retained":3,"session.terminated":0,"packets.publish.inuse":0,"packets.pubrec.received":0,"messages.qos2.received":0,"messages.dropped":0,"packets.connect.received":0,"client.authenticate":0,"packets.subscribe.received":0,"messages.qos1.received":0},"code":0}
1
2
3

# 状态

# 获取集群下所有状态数据

GET /stats

URL 路径参数:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects各节点上的状态数据列表
data[0].nodeString节点名称
data[0].statsArray状态数据,详见下面的 stats

stats:

NameTypeDescription
connections.countInteger当前连接数量
connections.maxInteger连接数量的历史最大值
channels.countIntegersessions.count
channels.maxIntegersession.max
sessions.countInteger当前会话数量
sessions.maxInteger会话数量的历史最大值
topics.countInteger当前主题数量
topics.maxInteger主题数量的历史最大值
suboptions.countIntegersubscriptions.count
suboptions.maxIntegersubscriptions.max
subscribers.countInteger当前订阅者数量
subscribers.maxInteger订阅者数量的历史最大值
subscriptions.countInteger当前订阅数量,包含共享订阅
subscriptions.maxInteger订阅数量的历史最大值
subscriptions.shared.countInteger当前共享订阅数量
subscriptions.shared.maxInteger共享订阅数量的历史最大值
routes.countInteger当前路由数量
routes.maxInteger路由数量的历史最大值
retained.countInteger当前保留消息数量
retained.maxInteger保留消息的历史最大值

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/stats"

{"data":[{"stats":{"topics.max":0,"topics.count":0,"subscriptions.shared.max":0,"subscriptions.shared.count":0,"subscriptions.max":0,"subscriptions.count":0,"subscribers.max":0,"subscribers.count":0,"suboptions.max":0,"suboptions.count":0,"sessions.max":0,"sessions.count":0,"rules.max":0,"rules.count":0,"routes.max":0,"routes.count":0,"retained.max":3,"retained.count":3,"resources.max":0,"resources.count":0,"connections.max":0,"connections.count":0,"channels.max":0,"channels.count":0,"actions.max":5,"actions.count":5},"node":"emqx@127.0.0.1"}],"code":0}
1
2
3

# 获取指定节点上的状态数据

GET /nodes/{node}/stats

URL 路径参数:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects各节点上的状态数据列表,详见 GET /api/stats (opens new window)

示例:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/stats"

{"data":{"topics.max":0,"topics.count":0,"subscriptions.shared.max":0,"subscriptions.shared.count":0,"subscriptions.max":0,"subscriptions.count":0,"subscribers.max":0,"subscribers.count":0,"suboptions.max":0,"suboptions.count":0,"sessions.max":0,"sessions.count":0,"rules.max":0,"rules.count":0,"routes.max":0,"routes.count":0,"retained.max":3,"retained.count":3,"resources.max":0,"resources.count":0,"connections.max":0,"connections.count":0,"channels.max":0,"channels.count":0,"actions.max":5,"actions.count":5},"code":0}
1
2
3

# 规则

查询规则引擎的动作

# 获取某个规则的详情

GET /rules/{rule_id}

URL 路径参数:

NameTypeRequiredDescription
rule_idStringFalse可选,Rule ID。如不指定 rule_id 则 以数组形式返回所有已创建的规则

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.idStringRule ID
- data.rawsqlStringSQL 语句,与请求中的 rawsql 一致
- data.forStringTopic 列表,表示哪些 topic 可以匹配到此规则
- data.metricsArray统计指标,具体可参看 Dashboard 上的 Rule Metrics
- data.descriptionString规则的描述信息,与请求中的 description 一致
- data.actionsArray动作列表
- data.actions[0].idStringAction ID
- data.actions[0].paramsObject动作参数,与请求中的 actions.params 一致
- data.actions[0].nameString动作名字,与请求中的 actions.name 一致
- data.actions[0].metricsArray统计指标,具体可参看 Dashboard 上的 Rule Metrics

# 创建规则

POST /rules

请求消息元素 (json):

NameTypeRequiredDescription
rawsqlStringTrue规则的 SQL 语句
actionsArrayTrue动作列表
- actions[0].nameStringTrue动作名称
- actions[0].paramsObjectTrue动作参数。参数以 key-value 形式表示。 详情可参看添加规则的示例
descriptionStringFalse可选,规则描述

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject创建成功的规则对象,包含 Rule ID
- data.idStringRule ID
- data.rawsqlStringSQL 语句,与请求中的 rawsql 一致
- data.forStringTopic 列表,表示哪些 topic 可以匹配到此规则
- data.metricsArray统计指标,具体可参看 Dashboard 上的 Rule Metrics
- data.descriptionString规则的描述信息,与请求中的 description 一致
- data.actionsArray动作列表,每个动作是一个 Object
- data.actions[0].idStringAction ID
- data.actions[0].paramsObject动作参数,与请求中的 actions.params 一致
- data.actions[0].nameString动作名字,与请求中的 actions.name 一致
- data.actions[0].metricsArray统计指标,具体可参看 Dashboard 上的 Rule Metrics

# 更新规则

PUT /rules/{rule_id}

请求消息元素 (json):

NameTypeRequiredDescription
rawsqlStringTrue可选,规则的 SQL 语句
actionsArrayTrue可选,动作列表
- actions[0].nameStringTrue可选,动作名称
- actions[0].paramsObjectTrue可选,动作参数。参数以 key-value 形式表示。 详情可参看添加规则的示例
descriptionStringFalse可选,规则描述

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject创建成功的规则对象,包含 Rule ID
- data.idStringRule ID
- data.rawsqlStringSQL 语句,与请求中的 rawsql 一致
- data.forStringTopic 列表,表示哪些 topic 可以匹配到此规则
- data.metricsArray统计指标,具体可参看 Dashboard 上的 Rule Metrics
- data.descriptionString规则的描述信息,与请求中的 description 一致
- data.actionsArray动作列表,每个动作是一个 Object
- data.actions[0].idStringAction ID
- data.actions[0].paramsObject动作参数,与请求中的 actions.params 一致
- data.actions[0].nameString动作名字,与请求中的 actions.name 一致
- data.actions[0].metricsArray统计指标,具体可参看 Dashboard 上的 Rule Metrics

# 删除规则

DELETE /rules/{rule_id}

Parameters:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

添加一个规则,对于所有匹配到主题 "t/a" 的消息,打印其规则运行参数。

$ curl -XPOST -d '{
  "rawsql": "select * from \"t/a\"",
  "actions": [{
      "name": "inspect",
      "params": {
          "a": 1
      }
  }],
  "description": "test-rule"
}' --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules'

{"data":{"rawsql":"select * from \"t/a\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}
1
2
3
4
5
6
7
8
9
10
11
12

使用规则 ID 获取刚才创建的规则详情:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e'

{"data":{"rawsql":"select * from \"t/a\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}
1
2
3

获取所有的规则,注意返回值里的 data 是个规则对象的数组:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules'

{"data":[{"rawsql":"select * from \"t/a\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]}],"code":0}
1
2
3

更新一下规则的 SQL 语句,改为 select * from "t/b":

$ curl -XPUT --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e' -d '{"rawsql":"select * from \"t/b\""}'

{"data":{"rawsql":"select * from \"t/b\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}
1
2
3

停用规则 (disable):

$ curl -XPUT --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e' -d '{"enabled": false}'

{"data":{"rawsql":"select * from \"t/b\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":false,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}
1
2
3

删除规则:

$ curl -XDELETE --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e'

{"code":0}
1
2
3

# 动作

查询规则引擎的动作。注意动作只能由 emqx 提供,不能添加。

# 获取某个动作的详情

GET /actions/{action_name}

URL 路径参数:

NameTypeRequiredDescription
action_nameStringFalse可选,动作名。如不指定 action_name 则 以数组形式返回当前支持的所有动作。

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.typesString指示当前动作从属于那些资源类型
- data.titleObject动作的简述,中英文。
- data.paramsObject动作的参数列表。参数以 key-value 形式表示。 详情可参看后面的示例
- data.descriptionObject动作的描述信息,中英文。
- data.appString动作的提供者

示例:

查询 inspect 动作的详情:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/actions/inspect'

{"data":{"types":[],"title":{"zh":"检查 (调试)","en":"Inspect (debug)"},"params":{},"name":"inspect","for":"$any","description":{"zh":"检查动作参数 (用以调试)","en":"Inspect the details of action params for debug purpose"},"app":"emqx_rule_engine"},"code":0}
1
2
3

查询当前所有的动作:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/actions'

{"data":[{"types":[],"title":{"zh":"空动作 (调试)","en":"Do Nothing (debug)"},"params":{},"name":"do_nothing","for":"$any","description":{"zh":"此动作什么都不做,并且不会失败 (用以调试)","en":"This action does nothing and never fails. It's for debug purpose"},"app":"emqx_rule_engine"}, ...],"code":0}
1
2
3

# 资源类型

查询规则引擎的资源类型。注意资源类型只能由 emqx 提供,不能添加。

# 获取资源类型的详细信息

GET /resource_types/{resource_type_name}

URL 路径参数:

NameTypeRequiredDescription
resource_type_nameStringFalse可选,资源类型名。如不指定 resource_type_name 则 以数组形式返回当前支持的所有资源类型。

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.titleObject资源类型的简述,中英文。
- data.paramsObject资源类型的参数列表。参数以 key-value 形式表示。 详情可参看后面的示例
- data.descriptionObject资源类型的描述信息,中英文。
- data.providerString资源类型的提供者

示例:

查询 web_hook 资源类型的详细信息:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resource_types/web_hook'

{"data":{"title":{"zh":"WebHook","en":"WebHook"},"provider":"emqx_web_hook","params":{"url":{"type":"string","title":{"zh":"请求 URL","en":"Request URL"},"required":true,"format":"url","description":{"zh":"请求 URL","en":"Request URL"}},"method":{"type":"string","title":{"zh":"请求方法","en":"Request Method"},"enum":["PUT","POST"],"description":{"zh":"请求方法","en":"Request Method"},"default":"POST"},"headers":{"type":"object","title":{"zh":"请求头","en":"Request Header"},"schema":{},"description":{"zh":"请求头","en":"Request Header"},"default":{}}},"name":"web_hook","description":{"zh":"WebHook","en":"WebHook"}},"code":0}
1
2
3

查询当前所有的资源类型:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resource_types'

{"data":[{"title":{"zh":"WebHook","en":"WebHook"},"provider":"emqx_web_hook","params":{"url":{"type":"string","title":{"zh":"请求 URL","en":"Request URL"},"required":true,"format":"url","description":{"zh":"请求 URL","en":"Request URL"}},"method":{"type":"string","title":{"zh":"请求方法","en":"Request Method"},"enum":["PUT","POST"],"description":{"zh":"请求方法","en":"Request Method"},"default":"POST"},"headers":{"type":"object","title":{"zh":"请求头","en":"Request Header"},"schema":{},"description":{"zh":"请求头","en":"Request Header"},"default":{}}},"name":"web_hook","description":{"zh":"WebHook","en":"WebHook"}}, ...],"code":0}
1
2
3

# 资源

管理规则引擎的资源。资源是资源类型的实例,用于维护数据库连接等相关资源。

# 获取指定资源的详细信息

GET /resources/{resource_id}

URL 路径参数:

NameTypeRequiredDescription
resource_idStringFalse可选,资源类型 ID。如不指定 resource_id 则 以数组形式返回当前所有的资源。

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.idString资源 ID
- data.typeString资源所从属的资源类型的名字。
- data.configObject资源的配置。参数以 key-value 形式表示。 详情可参看后面的示例
- data.statusArray资源的状态信息。详情请参看 Dashboard 上资源的状态。
- data.descriptionObject资源的描述信息,中英文。

# 获取所有资源信息

POST /resources

请求消息元素 (json):

NameTypeRequiredDescription
typeStringTrue资源类型名。指定要使用哪个资源类型创建资源。
configObjectTrue资源参数。要跟对应的资源类型的 params 里指定的格式相一致。
descriptionStringFalse可选,资源描述

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.idString资源 ID
- data.typeString资源所从属的资源类型的名字。
- data.configObject资源的配置。参数以 key-value 形式表示。 详情可参看后面的示例
- data.descriptionObject资源的描述信息,中英文。

# 删除资源

DELETE /resources/{resource_id}

Parameters:

成功响应消息元素 (JSON):

NameTypeDescription
codeInteger0

示例:

创建一个 webhook 资源,webserver 的 URL 为 http://127.0.0.1:9910 (opens new window)

$ curl -XPOST -d '{
  "type": "web_hook",
  "config": {
      "url": "http://127.0.0.1:9910",
      "headers": {"token":"axfw34y235wrq234t4ersgw4t"},
      "method": "POST"
  },
  "description": "web hook resource-1"
}' --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources'

{"data":{"type":"web_hook","id":"resource:b12d3e44","description":"web hook resource-1","config":{"url":"http://127.0.0.1:9910","method":"POST","headers":{"token":"axfw34y235wrq234t4ersgw4t"}}},"code":0}
1
2
3
4
5
6
7
8
9
10
11

使用资源 ID 查询刚创建的资源:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources/resource:b12d3e44'

{"data":{"type":"web_hook","status":[{"node":"emqx@127.0.0.1","is_alive":false}],"id":"resource:b12d3e44","description":"web hook resource-1","config":{"url":"http://127.0.0.1:9910","method":"POST","headers":{"token":"axfw34y235wrq234t4ersgw4t"}}},"code":0}
1
2
3

查询当前已创建的所有的资源:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources'

{"data":[{"type":"web_hook","id":"resource:b12d3e44","description":"web hook resource-1","config":{"url":"http://127.0.0.1:9910","method":"POST","headers":{"token":"axfw34y235wrq234t4ersgw4t"}}}],"code":0}
1
2
3

删除资源:

$ curl -XDELETE --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources/resource:b12d3e44'

{"code":0}
1
2
3