HTTP API

EMQX 的 HTTP API 服务默认监听 8081 端口，可通过 配置文件修改监听端口，或启用 HTTPS 监听。EMQX 4.0.0 (opens new window) 以后的所有 API 调用均以 api/v4 开头。

EMQX 的 HTTP API 使用 Basic 认证 (opens new window) 方式，id 和 password 须分别填写 AppID 和 AppSecret。 默认的 AppID 和 AppSecret 是：admin/public。你可以在 Dashboard 的左侧菜单栏里，选择 “管理” -> “应用” 来修改和添加 AppID/AppSecret。

响应码

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

可能的状态码如下：

返回码 (result codes)

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

可能的返回码如下：

API Endpoints

健康检查

GET /status

作为节点的健康检查。 返回一个纯文本的响应，描述节点的状态。

如果 EMQX 应用程序已经启动并运行，返回状态代码 200，否则返回 503。

Examples:

应用程序正在运行。

当 EMQX 还没有完成启动，或者由于加入或离开集群时重新启动时：

$ curl "http://localhost:8081/status"
Node emqx@127.0.0.1 is started
emqx is not_running

/api/v4

GET /api/v4

返回 EMQX 支持的所有 Endpoints。

Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4"
{"data":[{"path":"/auth_clientid","name":"list_clientid","method":"GET","descr":"List available clientid in the cluster"}, ...],"code":0}

Broker 基本信息

GET /api/v4/brokers/{node}

返回集群下所有节点的基本信息。

Path Parameters:

Success Response Body (JSON):

Examples:

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

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers"
{"data":[{"version":"develop","uptime":"4 hours, 21 minutes, 19 seconds","sysdescr":"EMQX 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}

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

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers/emqx@127.0.0.1"
{"data":{"version":"develop","uptime":"1 minutes, 51 seconds","sysdescr":"EMQX 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}

节点

GET /api/v4/nodes/{node}

返回节点的状态。

Path Parameters:

Success Response Body (JSON):

Examples:

获取所有节点的状态：

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

获取指定节点的状态：

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

客户端

GET /api/v4/clients

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

Query String Parameters:

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

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

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

GET /api/v4/clients/{clientid}

返回指定客户端的信息

Path Parameters:

Success Response Body (JSON):

Examples:

查询指定客户端

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

DELETE /api/v4/clients/{clientid}

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

Path Parameters:

Success Response Body (JSON):

Examples:

踢除指定客户端

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

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

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

Query String Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

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

Path Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

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

Path Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

类似 ，在指定节点下，通过 Username 查询指定客户端的信息。

Path Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

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

Path Parameters:

Success Response Body (JSON):

Examples:

查询 ACL 缓存

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

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

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

Path Parameters:

Success Response Body (JSON):

Examples:

清除 ACL 缓存

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

PUT /api/v4/clients/{clientid}/keepalive

设置指定客户端的keepalive时间（秒）。

Path Parameters:

Query String Parameters:

Success Response Body (JSON):

Examples:

更新指定客户端（example）keepalive为10秒

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/clients/example/keepalive?interval=10"
{"code":0}

除了通过 Query String 传参外，还可以使用 Body 。

curl   -u admin:public -X 'PUT' http://127.0.0.1:18083/api/v4/clients/test/keepalive -d '{"interval": 10}'
{"code":0}

订阅信息

GET /api/v4/subscriptions

返回集群下所有订阅信息，支持分页机制。

Query String Parameters:

在 4.1 版本后，支持多条件和模糊查询：

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

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

GET /api/v4/subscriptions/{clientid}

返回集群下指定客户端的订阅信息。

Path Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions/123"
{"data":[{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"123"}],"code":0}

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

类似 GET /api/v4/subscriptions，返回指定节点下的所有订阅信息，支持分页机制。

Query String Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

类似 GET /api/v4/subscriptions/{clientid}，在指定节点下，查询某 clientid 的所有订阅信息，支持分页机制。

Path Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/subscriptions/sample"
{"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"sample"}],"code":0}

路由

GET /api/v4/routes

返回集群下的所有路由信息，支持分页机制。

Query String Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

GET /api/v4/routes/{topic}

返回集群下指定主题的路由信息。

Path Parameters:

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/routes/a%2fb%2fc"
{"data":[{"topic":"a/b/c","node":"emqx@127.0.0.1"}],"code":0}

POST /api/v4/mqtt/publish

发布 MQTT 消息。

Parameters (json):

Properties取值：

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish" -d \
'{"topic":"a/b/c", "payload":"Hello World", "qos":1, "retain":false, "clientid":"example", "properties": {"user_properties": { "id": 10010, "name": "emqx", "foo": "bar"}, "content_type": "text/plain"}}'
{"code":0}

主题订阅

POST /api/v4/mqtt/subscribe

订阅 MQTT 主题。

Parameters (json):

Success Response Body (JSON):

Examples:

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

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/subscribe" -d '{"topics":"a,b,c","qos":1,"clientid":"example"}'
{"code":0}

POST /api/v4/mqtt/unsubscribe

取消订阅。

Parameters (json):

Success Response Body (JSON):

Examples:

取消订阅 a 主题

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'
{"code":0}

消息批量发布

POST /api/v4/mqtt/publish_batch

批量发布 MQTT 消息。

Parameters (json):

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish_batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example","properties": {"user_properties":{"id": 10010, "name": "emqx", "foo": "bar"}}},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example","properties":{"user_properties": { "id": 10010, "name": "emqx", "foo": "bar"},"content_type": "text/plain"}}]'
{"data":[{"topic":"a/b/c","code":0},{"topic":"a/b/c","code":0}],"code":0}

主题批量订阅

POST /api/v4/mqtt/subscribe_batch

批量订阅 MQTT 主题。

Parameters (json):

Success Response Body (JSON):

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

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/subscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"},{"topic":"c","qos":1,"clientid":"example"}]'
{"code":0}

POST /api/v4/mqtt/unsubscribe_batch

批量取消订阅。

Parameters (json):

Success Response Body (JSON):

Examples:

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

插件

返回集群下的所有插件信息。

Path Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/plugins"
{"data":[{"plugins":[{"version":"develop","type":"auth","name":"emqx_auth_clientid","description":"EMQX Authentication with ClientId/Password","active":false}, ...],"node":"emqx@127.0.0.1"}],"code":0}

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

类似 ，返回指定节点下的插件信息。

Path Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins"
{"data":[{"version":"develop","type":"auth","name":"emqx_auth_clientid","description":"EMQX Authentication with ClientId/Password","active":false}, ...],"code":0}

PUT /api/v4/nodes/{node}/plugins/{plugin}/load

加载指定节点下的指定插件。

Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/load"
{"code":0}

PUT /api/v4/nodes/{node}/plugins/{plugin}/unload

卸载指定节点下的指定插件。

Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/unload"
{"code":0}

PUT /api/v4/nodes/{node}/plugins/{plugin}/reload

重新加载指定节点下的指定插件。

Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/reload"
{"code":0}

监听器

GET /api/v4/listeners

返回集群下的所有监听器信息。

Path Parameters: 无

Success Response Body (JSON):

常见 shutdown_count

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

类似 GET /api/v4/listeners，返回指定节点的监听器信息。

Path Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

内置模块

GET /api/v4/modules

返回集群下所有内置模块信息。

Path Parameters: 无

Success Response Body (JSON):

modules:

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/modules"
{"data":[{"node":"emqx@127.0.0.1","modules":[{"name":"emqx_mod_delayed","description":"EMQX Delayed Publish Module","active":true},{"name":"emqx_mod_topic_metrics","description":"EMQX Topic Metrics Module","active":false},{"name":"emqx_mod_subscription","description":"EMQX Subscription Module","active":false},{"name":"emqx_mod_acl_internal","description":"EMQX Internal ACL Module","active":true},{"name":"emqx_mod_rewrite","description":"EMQX Topic Rewrite Module","active":false},{"name":"emqx_mod_presence","description":"EMQX Presence Module","active":true}]}],"code":0}

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

类似 GET /api/v4/modules，返回指定节点下所有内置模块信息。

PUT /api/v4/modules/{module}/load

加载集群下所有节点的指定内置模块。

Path Parameters: 无

Success Response Body (JSON):

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/modules/emqx_mod_topic_metrics/load"
{"code":0}

PUT /api/v4/nodes/{node}/modules/{module}/load

类似 ，加载指定节点下的指定内置模块。

PUT /api/v4/modules/{module}/unload

卸载集群下所有节点的指定内置模块。

Path Parameters: 无

Success Response Body (JSON):

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/modules/emqx_mod_topic_metrics/unload"
{"code":0}

PUT /api/v4/nodes/{node}/modules/{module}/unload

类似 PUT /api/v4/modules/{module}/unload，卸载指定节点下的指定内置模块。

PUT /api/v4/modules/{module}/reload

重新加载集群下所有节点的指定内置模块，仅为 emqx_mod_acl_internal 提供此功能。

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/modules/emqx_mod_acl_internal/reload"
{"code":0}

PUT /api/v4/nodes/{node}/modules/{module}/reload

类似 ，重新加载指定节点下的指定内置模块，仅为 emqx_mod_acl_internal 提供此功能。

统计指标

GET /api/v4/metrics

返回集群下所有统计指标数据。

Path Parameters: 无

Success Response Body (JSON):

metrics：

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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,"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,"packets.disconnect.sent":0,"session.created":13,"packets.pingreq.received":0,"messages.dropped":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}

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

类似 ，返回指定节点下所有监控指标数据。

Path Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/metrics"
{"data":{"bytes.received":0,"client.connected":0,"packets.pingreq.received":0,"messages.delayed":0,"packets.puback.sent":0,"packets.pingresp.sent":0,"packets.publish.auth_error":0,"client.check_acl":0,"delivery.dropped.queue_full":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}

主题统计指标

GET /api/v4/topic-metrics

返回所有主题统计指标数据。

Path Parameters: 无

Success Response Body (JSON):

metrics:

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-metrics"
{"data":[],"code":0}
$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/topic-metrics" -d '{"topic":"a/b/c"}'
{"code":0}
$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-metrics"
{"data":[{"topic":"a/b/c","metrics":{"messages.qos2.out.rate":0.0,"messages.qos2.out.count":0,"messages.qos2.in.rate":0.0,"messages.qos2.in.count":0,"messages.qos1.out.rate":0.0,"messages.qos1.out.count":0,"messages.qos1.in.rate":0.0,"messages.qos1.in.count":0,"messages.qos0.out.rate":0.0,"messages.qos0.out.count":0,"messages.qos0.in.rate":0.0,"messages.qos0.in.count":0,"messages.out.rate":0.0,"messages.out.count":0,"messages.in.rate":0.0,"messages.in.count":0,"messages.dropped.rate":0.0,"messages.dropped.count":0}}],"code":0}

GET /api/v4/topic-metrics/{topic}

返回指定主题的统计指标数据。

Path Parameters: 无

Success Response Body (JSON):

data:

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-metrics/a%2Fb%2Fc"
{"data":{"messages.qos2.out.rate":0.0,"messages.qos2.out.count":0,"messages.qos2.in.rate":0.0,"messages.qos2.in.count":0,"messages.qos1.out.rate":0.0,"messages.qos1.out.count":0,"messages.qos1.in.rate":0.0,"messages.qos1.in.count":0,"messages.qos0.out.rate":0.0,"messages.qos0.out.count":0,"messages.qos0.in.rate":0.0,"messages.qos0.in.count":0,"messages.out.rate":0.0,"messages.out.count":0,"messages.in.rate":0.0,"messages.in.count":0,"messages.dropped.rate":0.0,"messages.dropped.count":0},"code":0}

POST /api/v4/topic-metrics

开启对指定主题的指标统计。

Parameters (json):

Success Response Body (JSON):

Examples:

开启对 a/b/c 主题的指标统计

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/topic-metrics" -d '{"topic":"a/b/c"}'
{"code":0}

DELETE /api/v4/topic-metrics/{topic}

关闭对指定主题的指标统计。

Path Parameters: 无

Success Response Body (JSON):

Examples:

关闭对 a/b/c 主题的指标统计

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/topic-metrics/a%2Fb%2Fc"
{"code":0}

DELETE /api/v4/topic-metrics

关闭所有主题的指标统计。

Path Parameters: 无

Success Response Body (JSON):

Examples:

关闭所有主题的指标统计

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/topic-metrics"
{"code":0}

GET /api/v4/stats

返回集群下所有状态数据。

Path Parameters: 无

Success Response Body (JSON):

stats:

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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,"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},"node":"emqx@127.0.0.1"}],"code":0}

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

类似 GET /api/v4/stats，返回指定节点上的状态数据。

Path Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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,"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},"code":0}

告警

GET /api/v4/alarms

返回集群下当前告警信息。

Path Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms"
{"data":[{"node":"emqx@127.0.0.1","alarms":[{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":"infinity","activated":true,"activate_at":1597996203658236},{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":1597994359335482,"activated":false,"activate_at":1597993108657522}]}],"code":0}

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

返回指定节点下的告警信息。接口参数和返回请参看 。

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/alarms"
{"data":[{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":"infinity","activated":true,"activate_at":1597996203658236},{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":1597994359335482,"activated":false,"activate_at":1597993108657522}],"code":0}

GET /api/v4/alarms/activated

返回集群下激活中的告警。接口参数和返回请参看 。

Examples:

{"data":[{"node":"emqx@127.0.0.1","alarms":[{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":"infinity","activated":true,"activate_at":1597996203658236}]}],"code":0}

GET /api/v4/nodes/{node}/alarms/activated

返回指定节点下激活中的告警。接口参数和返回请参看 。

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/alarms/activated"
{"data":[{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":"infinity","activated":true,"activate_at":1597996203658236}],"code":0}

返回集群下已经取消的告警。接口参数和返回请参看 。

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms/deactivated"
{"data":[{"node":"emqx@127.0.0.1","alarms":[{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":1597994359335482,"activated":false,"activate_at":1597993108657522}]}],"code":0}

GET /api/v4/nodes/{node}/alarms/deactivated

返回指定节点下已经取消的告警。接口参数和返回请参看 。

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/alarms/deactivated"
{"data":[{"name":"high_system_memory_usage","message":"System memory usage is higher than 60%","details":{"high_watermark":60},"deactivate_at":1597994359335482,"activated":false,"activate_at":1597993108657522}],"code":0}

POST /api/v4/alarms/deactivated

取消指定告警。

Parameters (json):

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -vX POST "http://localhost:8081/api/v4/alarms/deactivated" -d '{"node":"emqx@127.0.0.1","name":"high_system_memory_usage"}'
{"code":0}

DELETE /api/v4/alarms/deactivated

清除所有已经取消的告警。

Parameters (json): 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/alarms/deactivated"
{"code":0}

DELETE /api/v4/nodes/{node}/alarms/deactivated

清除指定节点下所有已经取消的告警。

Parameters (json): 无

Success Response Body (JSON):

Examples:

ACL 缓存

DELETE /api/v4/acl-cache

清除集群中所有的 ACL 缓存

Query String Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/acl-cache"
{"code":0}

DELETE /api/v4/node/{node}/acl-cache

Query String Parameters: 无

Success Response Body (JSON):

Examples:

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/node/emqx@127.0.0.1/acl-cache"
{"code":0}

黑名单

GET /api/v4/banned

获取黑名单

Query String Parameters:

同 /api/v4/clients。

Success Response Body (JSON):

Examples:

获取黑名单列表:

$ curl -i --basic -u admin:public -vX GET "http://localhost:8081/api/v4/banned"
{"meta":{"page":1,"limit":10000,"count":1},"data":[{"who":"example","until":1582265833,"reason":"undefined","by":"user","at":1582265533,"as":"clientid"}],"code":0}

POST /api/v4/banned

将对象添加至黑名单

Parameters (json):

Success Response Body (JSON):

Examples:

将 client 添加到黑名单:

$ curl -i --basic -u admin:public -vX POST "http://localhost:8081/api/v4/banned" -d '{"who":"example","as":"clientid","reason":"example"}'
{"data":{"who":"example","as":"clientid"},"code":0}

DELETE /api/v4/banned/{as}/{who}

将对象从黑名单中删除

Parameters: 无

Success Response Body (JSON):

Examples:

将 client 从黑名单中移除:

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/banned/clientid/example"
{"code":0}