HTTP API

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

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

    响应码

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

    可能的状态码如下：

    返回码 (result codes)

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

    可能的返回码如下：

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

    API Endpoints

    /api/v4

    GET /api/v4

    返回 EMQ X 支持的所有 Endpoints。

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArrayEndpoints 列表
    - data[0].pathStringEndpoint
    - data[0].nameStringEndpoint 名
    - data[0].methodStringHTTP Method
    - data[0].descrString描述

    Examples:

    Broker 基本信息

    GET /api/v4/brokers/{node}

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

    Path Parameters:

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

    Success Response Body (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 版本

    Examples:

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

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

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

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers/emqx@127.0.0.1"
    3. {"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}

    节点

    GET /api/v4/nodes/{node}

    返回节点的状态。

    Path Parameters:

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

    Success Response Body (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 版本

    Examples:

    获取所有节点的状态：

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes"
    3. {"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. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1"
    3. {"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:

    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 内容做了修改：

    • hasnext：为新增字段，表示是否存在下一页。

    GET /api/v4/clients/{clientid}

    返回指定客户端的信息

    Path Parameters:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects客户端的信息，详细请参见

    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所有客户端的信息，详情请参看

    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客户端的信息，详细请参见

    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客户端的信息，详细请参见

    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客户端的信息，详细请参见

    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}

    订阅信息

    GET /api/v4/subscriptions

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

    Query String Parameters:

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

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

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

    Success Response Body (JSON):

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions?_page=1&_limit=10"
    3. {"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:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions/123"
    3. {"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:

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

    Success Response Body (JSON):

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/subscriptions?_page=1&limit=10"
    3. {"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}

    类似 ，在指定节点下，查询某 clientid 的所有订阅信息，支持分页机制。

    Path Parameters:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

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

    Examples:

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

    路由

    GET /api/v4/routes

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

    Query String Parameters:

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

    Success Response Body (JSON):

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

    Examples:

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

    NameTypeRequiredDescription
    topicIntegerTrue主题

    Success Response Body (JSON):

    Examples:

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

    POST /api/v4/mqtt/publish

    发布 MQTT 消息。

    Parameters (json):

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

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ 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"}'
    3. {"code":0}

    主题订阅

    POST /api/v4/mqtt/subscribe

    订阅 MQTT 主题。

    Parameters (json):

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

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

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

    POST /api/v4/mqtt/unsubscribe

    取消订阅。

    Parameters (json):

    NameTypeRequiredDefaultDescription
    topicStringRequired主题
    clientidStringRequired客户端标识符

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    取消订阅 a 主题

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

    消息批量发布

    POST /api/v4/mqtt/publish_batch

    批量发布 MQTT 消息。

    Parameters (json):

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

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ 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"},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example"}]'

    主题批量订阅

    POST /api/v4/mqtt/subscribe_batch

    批量订阅 MQTT 主题。

    Parameters (json):

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

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

    1. $ 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"}]'
    3. {"code":0}

    POST /api/v4/mqtt/unsubscribe_batch

    批量取消订阅。

    Parameters (json):

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

    Examples:

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

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

    插件

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

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects所有路由信息
    data[0].nodeString节点名称
    data[0].pluginsArray插件信息，由对象组成的数组，见下文
    data[0].plugins.nameString插件名称
    data[0].plugins.versionString插件版本
    data[0].plugins.descriptionString插件描述
    data[0].plugins.activeBoolean插件是否启动
    data[0].plugins.typeString插件类型，目前有
    auth、bridge、feature、protocol 四种类型

    Examples:

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

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

    类似 GET /api/v4/plugins，返回指定节点下的插件信息。

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects所有路由信息
    data[0].nameString插件名称
    data[0].versionString插件版本
    data[0].descriptionString插件描述
    data[0].activeBoolean插件是否启动
    data[0].typeString插件类型，目前有
    auth、bridge、feature、protocol 四种类型

    Examples:

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

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

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

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

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

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

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

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

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

    监听器

    GET /api/v4/listeners

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

    Path Parameters: 无

    Success Response Body (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 Session 或 Clean Start 为 true 而被丢弃的连接数量
    takeoveredInteger由于 Clean Session 或 Clean Start 为 false 而被接管的连接数量

    Examples:

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

    类似 ，返回指定节点的监听器信息。

    Path Parameters: 无

    Success Response Body (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连接关闭原因及计数

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/listeners"
    3. {"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):

    NameTypeDescription
    codeInteger0
    dataArray of Objects各节点上的内置模块列表
    data[0].nodeString节点名称
    data[0].modulesObject内置模块信息列表，详见下面的 modules:

    modules:

    NameTypeDescription
    nameString模块名
    descriptionString模块功能描述
    activeBoolean是否处于活跃状态（是否正在运行）

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/modules"
    3. {"data":[{"node":"emqx@127.0.0.1","modules":[{"name":"emqx_mod_delayed","description":"EMQ X Delayed Publish Module","active":true},{"name":"emqx_mod_topic_metrics","description":"EMQ X Topic Metrics Module","active":false},{"name":"emqx_mod_subscription","description":"EMQ X Subscription Module","active":false},{"name":"emqx_mod_acl_internal","description":"EMQ X Internal ACL Module","active":true},{"name":"emqx_mod_rewrite","description":"EMQ X Topic Rewrite Module","active":false},{"name":"emqx_mod_presence","description":"EMQ X 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):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息
    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/modules/emqx_mod_topic_metrics/load"
    3. {"code":0}

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

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

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

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

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息
    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/modules/emqx_mod_topic_metrics/unload"
    3. {"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 提供此功能。

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息
    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/modules/emqx_mod_acl_internal/reload"
    3. {"code":0}

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

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

    统计指标

    GET /api/v4/metrics

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

    Path Parameters: 无

    Success Response Body (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.qos1.receivedInteger接收来自客户端的 QoS 1 消息数量
    messages.qos2.receivedInteger接收来自客户端的 QoS 2 消息数量
    messages.qos0.sentInteger发送给客户端的 QoS 0 消息数量
    messages.qos1.sentInteger发送给客户端的 QoS 1 消息数量
    messages.qos2.sentInteger发送给客户端的 QoS 2 消息数量
    messages.receivedInteger接收来自客户端的消息数量，等于 messages.qos0.received，messages.qos1.received 与 messages.qos2.received 之和
    messages.sentInteger发送给客户端的消息数量，等于 messages.qos0.sent，messages.qos1.sent 与 messages.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 Session 或 Clean Start 为 true 而被丢弃的会话数量
    session.resumedInteger由于 Clean Session 或 Clean Start 为 false 而恢复的会话数量
    session.takeoveredInteger由于 Clean Session 或 Clean Start 为 false 而被接管的会话数量
    session.terminatedInteger终结的会话数量

    Examples:

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

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

    类似 GET /api/v4/metrics，返回指定节点下所有监控指标数据。

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObject各节点上的统计指标列表，详见

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/metrics"
    3. {"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}

    主题统计指标

    GET /api/v4/topic-metrics

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

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects各节点上的统计指标列表
    data[0].topicString主题名
    data[0].metricsObject主题统计指标数据，详见下面的 metrics:

    metrics:

    NameTypeDescription
    messages.qos2.out.rateIntegerQoS 2 消息 5 秒内平均发送速率
    messages.qos2.out.countIntegerQoS 2 消息发送数量统计
    messages.qos2.in.rateIntegerQoS 2 消息 5 秒内平均接收速率
    messages.qos2.in.countIntegerQoS 2 消息接收数量统计
    messages.qos1.out.rateIntegerQoS 1 消息 5 秒内平均发送速率
    messages.qos1.out.countIntegerQoS 1 消息发送数量统计
    messages.qos1.in.rateIntegerQoS 1 消息 5 秒内平均接收速率
    messages.qos1.in.countIntegerQoS 1 消息接收数量统计
    messages.qos0.out.rateIntegerQoS 0 消息 5 秒内平均发送速率
    messages.qos0.out.countIntegerQoS 0 消息发送数量统计
    messages.qos0.in.rateIntegerQoS 0 消息 5 秒内平均接收速率
    messages.qos0.in.countIntegerQoS 0 消息接收数量统计
    messages.out.rateIntegerMQTT 消息 5 秒内平均发送速率
    messages.out.countIntegerMQTT 消息发送数量统计
    messages.in.rateIntegerMQTT 消息 5 秒内平均接收速率
    messages.in.countIntegerMQTT 消息接收数量统计
    messages.dropped.rateIntegerMQTT 消息 5 秒内平均丢弃速率
    messages.dropped.countIntegerMQTT 消息丢弃数量统计

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-metrics"
    3. {"data":[],"code":0}
    4. $ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/topic-metrics" -d '{"topic":"a/b/c"}'
    6. {"code":0}
    7. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-metrics"
    9. {"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):

    NameTypeDescription
    codeInteger0
    dataObject主题统计指标数据，详见下面的 data:

    data:

    NameTypeDescription
    messages.qos2.out.rateIntegerQoS 2 消息 5 秒内平均发送速率
    messages.qos2.out.countIntegerQoS 2 消息发送数量统计
    messages.qos2.in.rateIntegerQoS 2 消息 5 秒内平均接收速率
    messages.qos2.in.countIntegerQoS 2 消息接收数量统计
    messages.qos1.out.rateIntegerQoS 1 消息 5 秒内平均发送速率
    messages.qos1.out.countIntegerQoS 1 消息发送数量统计
    messages.qos1.in.rateIntegerQoS 1 消息 5 秒内平均接收速率
    messages.qos1.in.countIntegerQoS 1 消息接收数量统计
    messages.qos0.out.rateIntegerQoS 0 消息 5 秒内平均发送速率
    messages.qos0.out.countIntegerQoS 0 消息发送数量统计
    messages.qos0.in.rateIntegerQoS 0 消息 5 秒内平均接收速率
    messages.qos0.in.countIntegerQoS 0 消息接收数量统计
    messages.out.rateIntegerMQTT 消息 5 秒内平均发送速率
    messages.out.countIntegerMQTT 消息发送数量统计
    messages.in.rateIntegerMQTT 消息 5 秒内平均接收速率
    messages.in.countIntegerMQTT 消息接收数量统计
    messages.dropped.rateIntegerMQTT 消息 5 秒内平均丢弃速率
    messages.dropped.countIntegerMQTT 消息丢弃数量统计

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-metrics/a%2Fb%2Fc"
    3. {"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):

    NameTypeRequiredDefaultDescription
    topicStringRequiredMQTT 主题名

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

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

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

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

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

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

    DELETE /api/v4/topic-metrics

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

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    关闭所有主题的指标统计

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

    GET /api/v4/stats

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

    Path Parameters: 无

    Success Response Body (JSON):

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

    stats:

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

    Examples:

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

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

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

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects各节点上的状态数据列表，详见

    Examples:

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

    告警

    GET /api/v4/alarms

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

    Path Parameters: 无

    Success Response Body (JSON):

    Examples:

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

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/alarms"
    3. {"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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms/activated"
    3. {"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/alarms。

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/alarms/activated"
    3. {"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}

    GET /api/v4/alarms/deactivated

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms/deactivated"
    3. {"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

    返回指定节点下已经取消的告警。接口参数和返回请参看 GET /api/v4/alarms/activated。

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/alarms/deactivated"
    3. {"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):

    NameTypeRequiredDefaultDescription
    nodeStringRequired告警所在节点
    nameStringRequired告警名称

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ 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"}'
    3. {"code":0}

    DELETE /api/v4/alarms/deactivated

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

    Parameters (json): 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

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

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

    Parameters (json): 无

    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/alarms/deactivated"
    3. {"code":0}

    ACL 缓存

    DELETE /api/v4/acl-cache

    清除集群中所有的 ACL 缓存

    Query String Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

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

    清除指定节点的 ACL 缓存

    Query String Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

    Examples:

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

    黑名单

    GET /api/v4/banned

    获取黑名单

    Query String Parameters:

    同 /api/v4/clients。

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray由对象构成的数组，对象中的字段与 POST 方法中的 Request Body 相同
    metaObject同 /api/v4/clients

    Examples:

    获取黑名单列表:

    1. $ curl -i --basic -u admin:public -vX GET "http://localhost:8081/api/v4/banned"
    3. {"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):

    NameTypeRequiredDefaultDescription
    whoStringRequired添加至黑名单的对象，可以是客户端标识符、用户名和 IP 地址
    asStringRequired用于区分黑名单对象类型，可以是 clientid，username，peerhost
    byStringOptionaluser指示该对象被谁添加至黑名单
    atIntegerOptional当前系统时间添加至黑名单的时间，单位：秒
    untilIntegerOptional当前系统时间 + 5 分钟何时从黑名单中解除，单位：秒

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObject与传入的 Request Body 相同

    Examples:

    将 client 添加到黑名单:

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

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

    将对象从黑名单中删除

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

    Examples:

    将 client 从黑名单中移除:

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

    数据导入导出

    数据导入导出。

    GET /api/v4/data/export

    获取当前的导出文件信息列表，包括文件名、大小和创建时间。

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects所有路由信息
    data[0].filenameString文件名
    data[0].created_atString“YYYY-MM-DD HH-mm-SS” 格式的文件创建时间
    data[0].sizeString文件大小，单位：字节

    Examples:

    列出当前的导出文件信息列表:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/data/export"
    3. {"data":[{"size":350,"filename":"emqx-export-2020-5-15-18-6-29.json","created_at":"2020-5-15 18:6:29"},{"size":388,"filename":"emqx-export-2020-5-15-17-39-0.json","created_at":"2020-5-15 17:39:0"}],"code":0}

    POST /api/v4/data/export

    导出当前数据到文件。

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObject文件信息
    data.filenameString文件名
    data.created_atString“YYYY-MM-DD HH-mm-SS” 格式的文件创建时间
    data.sizeString文件大小，单位：字节

    Examples:

    导出文件：

    1. $ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/data/export"
    3. {"data":{"size":350,"filename":"emqx-export-2020-5-18-17-17-44.json","created_at":"2020-5-18 17:17:44"},"code":0}

    POST /api/v4/data/import

    从指定文件导入数据。

    Path Parameters: 无

    Parameters (json):

    NameTypeRequiredDefaultDescription
    filenameStringRequired导入的文件名

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

    Examples:

    从指定文件导入数据：

    1. $ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/data/import" -d '{"filename":"emqx-export-2020-5-18-17-17-44.json"}'
    3. {"code":0}

    GET /api/v4/data/file/{filename}

    下载数据文件。

    Path Parameters: 无

    Parameters (json):

    NameTypeRequiredDefaultDescription
    filenameStringRequired导入的文件名

    Success Response Body (JSON):

    NameTypeDescription
    filenameString文件名
    fileString文件内容

    Examples:

    下载指定的数据文件：

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/data/file/emqx-export-2020-5-18-17-17-44.json"
    3. {"filename":"/Users/zhouzibo/emqx-rel/_build/emqx/rel/emqx/data/emqx-export-2020-5-18-17-17-44.json","file":"{\"version\":\"dev\",\"users\":[{\"username\":\"admin\",\"tags\":\"administrator\",\"password\":\"oKQPB1hbigv6+2ntALELNOb1fF0=\"}],\"schemas\":[],\"rules\":[],\"resources\":[],\"date\":\"2020-05-18 17:17:44\",\"blacklist\":[],\"auth_mnesia\":[],\"apps\":[{\"status\":true,\"secret\":\"public\",\"name\":\"Default\",\"id\":\"admin\",\"expired\":\"undefined\",\"desc\":\"Application user\"}],\"acl_mnesia\":[]}"}

    POST /api/v4/data/file

    上传数据文件。

    Path Parameters: 无

    Parameters (json):

    NameTypeRequiredDefaultDescription
    filenameStringRequired文件名
    fileStringRequired文件内容

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

    Examples:

    上传指定的数据文件：

    1. $ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/data/file" -d '{"filename":"emqx-export-2020-5-18-17-17-44.json","file":"{\"version\":\"dev\",\"users\":[{\"username\":\"admin\",\"tags\":\"administrator\",\"password\":\"oKQPB1hbigv6+2ntALELNOb1fF0=\"}],\"schemas\":[],\"rules\":[],\"resources\":[],\"date\":\"2020-05-18 17:17:44\",\"blacklist\":[],\"auth_mnesia\":[],\"apps\":[{\"status\":true,\"secret\":\"public\",\"name\":\"Default\",\"id\":\"admin\",\"expired\":\"undefined\",\"desc\":\"Application user\"}],\"acl_mnesia\":[]}"}'
    3. {"code":0}

    DELETE /api/v4/data/file/{filename}

    远程删除数据文件。

    Path Parameters: 无

    Parameters (json):

    NameTypeRequiredDefaultDescription
    filenameStringRequired文件名

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

    Examples:

    删除指定的数据文件：

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/data/file/emqx-export-2020-5-18-17-17-44.json"
    3. {"code":0}

    规则

    查询规则引擎的动作

    GET /api/v4/rules/{rule_id}

    获取某个规则的详情，包括规则的 SQL、Topics 列表、动作列表等。还会返回当前规则和动作的统计指标的值。

    Path Parameters:

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

    Success Response Body (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 /api/v4/rules

    创建规则，返回规则 ID。

    Parameters (json):

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

    Success Response Body (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 /api/v4/rules/{rule_id}

    更新规则，返回规则 ID。

    Parameters (json):

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

    Success Response Body (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 /api/v4/rules/{rule_id}

    删除规则。

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

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

    1. $ curl -XPOST -d '{
    2.   "rawsql": "select * from \"t/a\"",
    3.   "actions": [{
    4.       "name": "inspect",
    5.       "params": {
    6.           "a": 1
    7.       }
    8.   }],
    9.   "description": "test-rule"
    10. }' --basic -u admin:public 'http://localhost:8081/api/v4/rules'
    12. {"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}

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

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e'
    3. {"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}

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

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules'
    3. {"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}

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

    1. $ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e' -d '{"rawsql":"select * from \"t/b\""}'
    3. {"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}

    停用规则 (disable):

    1. $ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e' -d '{"enabled": false}'
    3. {"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. $ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e'
    3. {"code":0}

    动作

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

    GET api/v4/actions/{action_name}

    获取某个动作的详情，包括动作名字、参数列表等。

    Path Parameters:

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

    Success Response Body (JSON):

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

    Examples:

    查询 inspect 动作的详情：

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/actions/inspect'
    3. {"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. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/actions'
    3. {"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}

    资源类型

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

    GET api/v4/resource_types/{resource_type_name}

    获取某个资源的详情，包括资源描述、参数列表等。

    Path Parameters:

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

    Success Response Body (JSON):

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

    Examples:

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

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resource_types/web_hook'
    3. {"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. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resource_types'
    3. {"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}

    资源

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

    GET api/v4/resources/{resource_id}

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

    Path Parameters:

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

    Success Response Body (JSON):

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

    POST /api/v4/resources

    创建规则，返回资源 ID。

    Parameters (json):

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

    Success Response Body (JSON):

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

    DELETE /api/v4/resources/{resource_id}

    删除资源。

    Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    创建一个 webhook 资源，webserver 的 URL 为 ：

    1. $ curl -XPOST -d '{
    2.   "type": "web_hook",
    3.   "config": {
    4.       "url": "http://127.0.0.1:9910",
    5.       "headers": {"token":"axfw34y235wrq234t4ersgw4t"},
    6.       "method": "POST"
    7.   },
    8.   "description": "web hook resource-1"
    9. }' --basic -u admin:public 'http://localhost:8081/api/v4/resources'
    11. {"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}

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

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resources/resource:b12d3e44'
    3. {"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. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resources'
    3. {"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. $ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/resources/resource:b12d3e44'
    3. {"code":0}

    数据遥测

    PUT /api/v4/telemetry/status

    启用或关闭数据遥测功能。

    Path Parameters: 无

    Parameters (json):

    NameTypeRequiredDefaultDescription
    enabledBooleanRequired是否启用

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageString仅在发生错误时返回，用于提供更详细的错误信息

    Examples:

    启用数据遥测功能：

    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/telemetry/status" -d '{"enabled":true}'
    3. {"code":0}

    GET /api/v4/telemetry/status

    查询数据遥测功能是否启用。

    Path Parameters: 无

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of Objects遥测状态
    data.enabledBoolean是否启用

    Examples:

    查询数据遥测功能是否启用:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/telemetry/status"
    3. {"data":{"enabled":true},"code":0}

    获取数据遥测功能上报的数据内容。

    Path Parameters: 无

    Success Response Body (JSON):

    获取数据遥测功能上报的数据内容:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/telemetry/data"