Documentation

# HTTP API (V4)

NanoMQ 提供了 HTTP API 以实现与外部系统的集成，例如查询 broker 统计信息、客户端信息、发布消息，订阅主题信息和远程修改配置/重启等。

NanoMQ 的 HTTP API 服务默认监听 8081 端口。可通过 etc/nanomq.conf 配置文件修改监听端口，所有 API 调用均以 api/v4 开头。

访问旧版本 HTTP API (V1)

# 接口安全

NanoMQ 的 HTTP API 使用 Basic 认证 (opens new window)或 JWT 认证方式。username 和 password 须分别填写。 默认的username 和 password 是：admin/public。 可通过 etc/nanomq.conf 配置文件修改 username 和 password 。

# 响应码

# HTTP 状态码 (status codes)

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

可能的状态码如下：

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

# 返回码 (result codes)

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

可能的返回码如下：

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

# API Endpoints

# GET /api/v4

返回 NanoMQ 支持的所有 Endpoints 。

Parameters: 无

Success Response Body (JSON):

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

Examples:

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

{"code":0,"data":[{"path":"/brokers/","name":"list_brokers","method":"GET","descr":"A list of brokers in the cluster"},{"path":"/nodes/","name":"list_nodes","method":"GET","descr":"A list of nodes in the cluster"},{"path":"/clients/","name":"list_clients","method":"GET","descr":"A list of clients on current node"},{"path":"/clients/:clientid","name":"lookup_client","method":"GET","descr":"Lookup a client in the cluster"},{"path":"/clients/username/:username","name":"lookup_client_via_username","method":"GET","descr":"Lookup a client via username in the cluster"},{"path":"/subscriptions/","name":"list_subscriptions","method":"GET","descr":"A list of subscriptions in the cluster"},{"path":"/subscriptions/:clientid","name":"lookup_client_subscriptions","method":"GET","descr":"A list of subscriptions of a client"},{"path":"/topic-tree/","name":"list_topic-tree","method":"GET","descr":"A list of topic-tree in the cluster"},{"path":"/configuration/","name":"get_broker_configuration","method":"GET","descr":"show broker configuration"},{"path":"/configuration/","name":"set_broker_configuration","method":"POST","descr":"set broker configuration"},{"path":"/ctrl/:action","name":"ctrl_broker","method":"POST","descr":"Control broker stop or restart"}]}
1
2
3

# Broker 基本信息

# GET /api/v4/brokers

返回 Broker 的基本信息。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of Objects返回所有节点的信息*(只有一个节点， nanomq 暂不支持集群)*
data.datetimeString当前时间，格式为 "YYYY-MM-DD HH:mm:ss"
data.node_statusString节点状态
data.sysdescrString软件描述
data.uptimeStringNanoMQ 运行时间，格式为 "H hours, m minutes, s seconds"
data.versionStringNanoMQ 版本
$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers"

{"code":0,"data":[{"datetime":"2022-06-07 10:02:24","node_status":"Running","sysdescr":"NanoMQ Broker","uptime":"15 Hours, 1 minutes, 38 seconds","version":"0.7.9-3"}]}
1
2
3

# 节点

# GET /api/v4/nodes

返回节点的状态。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of Objects以 Array 形式返回所有节点的信息*(只有一个节点， nanomq 暂不支持集群)*
data.connectionsInteger当前接入此节点的客户端数量
data.node_statusString节点状态
data.uptimeStringNanoMQ 运行时间
data.versionStringNanoMQ 版本

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes"

{"code":0,"data":[{"connections":0,"node_status":"Running","uptime":"15 Hours, 22 minutes, 4 seconds","version":"0.8.1"}]}
1
2
3

# 统计信息

# GET /api/v4/metrics

返回 NanoMQ 的统计信息。

Success Response Body (JSON):

NameTypeDescription
metricsObject/Array of Objects暂未支持，（空）
cpuinfoInteger PercentNanoMQ CPU 使用量
memoryIntegerNanoMQ 内存使用量

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/metrics"

{"metrics":[],"cpuinfo":"0.00%","memory":"20049920"}
1
2
3

# GET /api/v4/prometheus

返回 Prometheus 统计数据。

Success Response Body (text/plain):

NameTypeDescription
nanomq_connections_countgauge当前客户端连接数
nanomq_connections_maxgauge客户端最大连接数
nanomq_sessions_countgauge当前会话数量
nanomq_sessions_maxgauge最大会话数量
nanomq_topics_countgauge当前主题数量
nanomq_topics_maxgauge最大主题数量
nanomq_subscribers_countgauge当前订阅数量
nanomq_subscribers_maxgauge最大订阅数量
nanomq_messages_receivedcounter收到消息数量
nanomq_messages_sentcounter发送消息数量
nanomq_messages_droppedcounter丢弃消息数量
nanomq_memory_usagegauge当前 CPU 使量
nanomq_memory_usage_maxgauge最大 CPU 使用量
nanomq_cpu_usagegauge当前内存使量
nanomq_cpu_usage_maxgauge最大内存使用量

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/prometheus"

# TYPE nanomq_connections_count gauge
# HELP nanomq_connections_count
nanomq_connections_count 0
# TYPE nanomq_connections_max gauge
# HELP nanomq_connections_max
nanomq_connections_max 0
# TYPE nanomq_sessions_count gauge
# HELP nanomq_sessions_count
nanomq_sessions_count 0
# TYPE nanomq_sessions_max gauge
# HELP nanomq_sessions_max
nanomq_sessions_max 0
# TYPE nanomq_topics_count gauge
# HELP nanomq_topics_count
nanomq_topics_count 0
# TYPE nanomq_topics_max gauge
# HELP nanomq_topics_max
nanomq_topics_max 0
# TYPE nanomq_subscribers_count gauge
# HELP nanomq_subscribers_count
nanomq_subscribers_count 0
# TYPE nanomq_subscribers_max gauge
# HELP nanomq_subscribers_max
nanomq_subscribers_max 0
# TYPE nanomq_messages_received counter
# HELP nanomq_messages_received
nanomq_messages_received 0
# TYPE nanomq_messages_sent counter
# HELP nanomq_messages_sent
nanomq_messages_sent 0
# TYPE nanomq_messages_dropped counter
# HELP nanomq_messages_dropped
nanomq_messages_dropped 0
# TYPE nanomq_memory_usage gauge
# HELP nanomq_memory_usage (b)
nanomq_memory_usage 19922944
# TYPE nanomq_memory_usage_max gauge
# HELP nanomq_memory_usage_max (b)
nanomq_memory_usage_max 19922944
# TYPE nanomq_cpu_usage gauge
# HELP nanomq_cpu_usage (%)
nanomq_cpu_usage 0.00
# TYPE nanomq_cpu_usage_max gauge
# HELP nanomq_cpu_usage_max (%)
nanomq_cpu_usage_max 0.00
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# 客户端

# GET /api/v4/clients

支持多条件查询，其包含的查询参数有：

NameTypeRequiredDescription
clientidStringFalse客户端标识符
usernameStringFalse客户端用户名
conn_stateEnumFalse客户端当前连接状态， 可取值有： connected,idle,disconnected
clean_startBoolFalse客户端是否使用了全新的会话
proto_nameEnumFalse客户端协议名称， 可取值有： MQTT,CoAP,LwM2M,MQTT-SN
proto_verIntegerFalse客户端协议版本

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有客户端的信息
data[0].clientidString客户端标识符
data[0].usernameString客户端连接时使用的用户名
data[0].proto_nameString客户端协议名称 (MQTT,CoAP,LwM2M,MQTT-SN)
data[0].proto_verInteger客户端使用的协议版本
data[0].connectedBoolean客户端是否处于连接状态
data[0].keepaliveInteger保持连接时间，单位：秒
data[0].clean_startBoolean指示客户端是否使用了全新的会话
data[0].recv_msgInteger接收的 PUBLISH 报文数量

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients"

{"code":0,"data":[{"client_id":"nanomq-f6d6fbfb","username":"alvin","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5,"recv_msg":3},{"client_id":"nanomq-bdf61d9b","username":"nanomq","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5,"recv_msg":0}]}
1
2
3

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

返回指定客户端的信息

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

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

Examples:

查询指定客户端

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/nanomq-29978ec1"

{"code":0,"data":[{"client_id":"nanomq-29978ec1","username":"","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5}]}
1
2
3

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

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

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

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

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/username/user001"

{"code":0,"data":[{"client_id":"nanomq-56baa74d","username":"user001","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5}]}
1
2
3

# 订阅信息

# GET /api/v4/subscriptions

支持多条件查询：

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有订阅信息
data[0].clientidString客户端标识符
data[0].topicString订阅主题
data[0].qosIntegerQoS 等级

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions"

{"code":0,"data":[{"clientid":"nanomq-29978ec1","topic":"topic123","qos":2},{"clientid":"nanomq-3020ffac","topic":"topic123","qos":2}]}
1
2
3

# GET /api/v4/subscriptions/{clientid}

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

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

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

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions/123"

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

# 消息发布

# POST /api/v4/mqtt/publish

发布 MQTT 消息。

Parameters (json):

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

Properties 取值：

NameTypeDescription
payload_format_indicatorInteger载荷格式指示标识符， 0 说明载荷是未指定格式的字节，相当于没有发送载荷格式指示，说明载荷是 UTF-8 编码的字符数据。载荷中的 UTF-8 数据必须是按照 Unicode 的规范和 RFC 3629 的重申进行编码
message_expiry_intervalinteger消息过期间隔标识符，以秒为单位，如果已过期，服务端还没有开始向匹配的订阅者交付该消息时，则服务端必须删除该订阅者的消息副本，不设置，则消息不会过期。
response_topicString响应主题标识符， UTF-8 编码的字符串，用作响应消息的主题名，响应主题不能包含通配符，包含多个响应主题将造成协议错误(Protocol Error)。响应主题的存在将消息标识为请求报文。服务端在收到应用消息时必须将响应主题原封不动的发送给所有的订阅者。
correlation_dataString对比数据标识符，服务端在收到应用消息时必须原封不动的把对比数据发送给所有的订阅者。对比数据只对请求消息(Request Message)的发送端和响应消息(Response Message)的接收端有意义。
subscription_identifierInteger订阅标识符标识符，订阅标识符取值范围从 1 到 268,435,455 。订阅标识符的值为 0 将造成协议错误。如果某条发布消息匹配了多个订阅，则将包含多个订阅标识符。这种情况下他们的顺序并不重要。
content_typeString内容类型标识符，以 UTF-8 格式编码的字符串，用来描述应用消息的内容，服务端必须把收到的应用消息中的内容类型原封不动的发送给所有的订阅者
user_propertiesObject用户属性(User Property)允许出现多次，以表示多个名字/值对，服务端在转发应用消息到客户端时必须原封不动的把所有的用户属性放在 PUBLISH 报文中

Success Response Body (JSON):

NameTypeDescription
codeInteger0

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": "name", "foo": "bar"}, "content_type": "text/plain"}}'

{"code":0}
1
2
3
4

# 主题订阅

# POST /api/v4/mqtt/subscribe

订阅 MQTT 主题。

Parameters (json):

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0

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

# POST /api/v4/mqtt/unsubscribe

取消订阅。

Parameters (json):

NameTypeRequiredDefaultDescription
topicStringRequired主题
clientidStringRequired客户端标识符

Success Response Body (JSON):

NameTypeDescription
codeInteger0

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

# 消息批量发布

# 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是否为保留消息
[0].propertiesObjectOptional{}PUBLISH 消息里的 properties 字段

Success Response Body (JSON):

NameTypeDescription
codeInteger0

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": "nanomq", "foo": "bar"}}},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example","properties":{"user_properties": { "id": 10010, "name": "nanomq", "foo": "bar"},"content_type": "text/plain"}}]'

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

# 主题批量订阅

# 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 三个主题

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

# POST /api/v4/mqtt/unsubscribe_batch

批量取消订阅。

Parameters (json):

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

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

$ 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"}]'

{"code":0}
1
2
3

# 主题树结构

# GET /api/v4/topic-tree

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有订阅信息
data[0].clientidArray of String客户端标识符数组
data[0].topicString订阅主题
data[0].cld_cntInteger子节点个数

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-tree"

{"code":0,"data":[[{"topic":"","cld_cnt":1}],[{"topic":"topic123","cld_cnt":1,"clientid":["nanomq-3a4a0956"]}],[{"topic":"123","cld_cnt":1,"clientid":["nanomq-0cfd69bb"]}],[{"topic":"456","cld_cnt":0,"clientid":["nanomq-26971dc8"]}]]}
1
2
3

# 获取热更新配置

# GET /api/v4/reload

返回当前所有支持热更新的配置参数。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
data.property_sizeInteger最大属性长度。
data.msq_lenInteger队列长度。
data.qos_durationIntegerQOS 消息定时间隔时间。
data.allow_anonymousBoolean允许匿名登录。
data.max_packet_sizeKbytesNanoMQ 的最大包大小 (Kbytes)
data.client_max_packet_sizeKbytes每个 client 的 最大包大小
data.keepalive_backoffIntegerMQTT keepalive 的退避指数

Examples:

$ curl -i --basic -u admin:public -X GET 'http://127.0.0.1:8081/api/v4/reload' -d \
`{
    "code": 0,
    "data": {
        "property_size": 64,
        "max_packet_size": 3,
        "client_max_packet_size": 5,
        "msq_len": 2048,
        "qos_duration": 10,
        "keepalive_backoff": 1250,
        "allow_anonymous": false
    }
}`
1
2
3
4
5
6
7
8
9
10
11
12
13

# 设置热更新配置

# POST /api/v4/reload

设置热配置参数。

Parameters (json):

NameTypeRequiredValueDescription
dataObjectRequired同获取热更新配置一致 获取热更新配置。

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/reload' -d \
'{
       "data": {
        "property_size": 64,
        "max_packet_size": 3,
        "client_max_packet_size": 5,
        "msq_len": 2048,
        "qos_duration": 10,
        "keepalive_backoff": 1250,
        "allow_anonymous": false
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 获取桥接配置

# GET /api/v4/bridges/

获取所有桥接节点配置

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有桥接客户端的配置信息
data.bridges.nodes[0].nameString节点名字。
data.bridges.nodes[0].enableBoolean启动桥接功能（默认false不启用）。
data.bridges.nodes[0].connector.serverString桥接目标 broker 地址 URL 。
data.bridges.nodes[0].connector.proto_verInteger桥接客户端 MQTT 版本（ 4 ｜ 5 ）。
data.bridges.nodes[0].connector.clientidString桥接客户端 ID （默认 NULL 为自动生成随机 ID）。
data.bridges.nodes[0].connector.keepaliveDuration保活间隔时间。
data.bridges.nodes[0].connector.clean_startBoolean清除会话。
data.bridges.nodes[0].connector.usernameString登录用户名。
data.bridges.nodes[0].connector.passwordString登录密码。
data.bridges.nodes[0].connector.conn_propertiesObjectConnector 的 MQTT V5 属性
data.bridges.nodes[0].connector.will_propertiesObjectMQTT V5 遗嘱属性
data.bridges.nodes[0].connector.ssl.enableBoolean启动 TLS 监听（默认false）。
data.bridges.nodes[0].connector.ssl.key_passwordStringTLS 私钥密码。
data.bridges.nodes[0].connector.ssl.keyfileStringTLS 私钥数据。
data.bridges.nodes[0].connector.ssl.certfileStringTLS Cert 证书数据。
data.bridges.nodes[0].connector.ssl.cacertfileStringTLS CA 证书数据。
data.bridges.nodes[0].hybrid_bridgingBoolean混合桥接模式开关，(默认 false 不启用), 如果想最大利用 QUIC ，建议启用
data.bridges.nodes[0].quic_keepaliveDurationQuic 传输层保活时间, （默认 120s )
data.bridges.nodes[0].quic_idle_timeoutDurationQuic 连接最大过期时间 （默认 120s )
data.bridges.nodes[0].quic_discon_timeoutDurationQuic 等待连接 ACK 最大时间 （默认 20s )
data.bridges.nodes[0].quic_handshake_timeoutDurationQUIC 握手最大超时时间（默认 60s )
data.bridges.nodes[0].quic_send_idle_timeoutDurationQUIC 传输层重置拥塞控制算法的等待超时时间 (默认60 s)
data.bridges.nodes[0].quic_initial_rtt_msDuration初始 RTT 估计时间 (默认 800ms)
data.bridges.nodes[0].quic_max_ack_delay_msDuration发送 ACK 之前接收数据后等待时长(默认100ms)
data.bridges.nodes[0].quic_qos_priorityBoolean高优先级发送 QOS 1 或 2 的消息(默认 true)
data.bridges.nodes[0].quic_0rttBoolean0RTT 是 QUIC 协议的一个特性，用于快速重新建立连接 (默认 true)
data.bridges.nodes[0].quic_multi_streamBooleanQuic Multiple stream 开关（默认false不启用）
data.bridges.nodes[0].parallelLong桥接客户端并发数。
data.bridges.nodes[0].forwards[0].remote_topicString第一个转发的remote_topic
data.bridges.nodes[0].forwards[0].local_topicString第一个转发的local_topic
data.bridges.nodes[0].subscription[0].remote_topicString第 1 个订阅remote_topic。
data.bridges.nodes[0].subscription[0].local_topicString第 1 个订阅local_topic。
data.bridges.nodes[0].subscription[0].qosInteger第 1 个订阅Qos。
data.bridges.nodes[0].sub_propertiesObjectSubscription 的 MQTT V5 属性
data.bridges.nodes[0].max_send_queue_lenInteger最大发送队列长度
data.bridges.nodes[0].max_recv_queue_lenInteger最大接收队列长度

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/bridges"

{
    "code": 0,
    "data": {
        "bridge": {
            "nodes": [
                {
                    "name": "emqx",
                    "enable": true,
                    "parallel": 2,
                    "connector": {
                        "server": "mqtt-tcp://broker.emqx.io:1883",
                        "proto_ver": 5,
                        "clientid": null,
                        "clean_start": true,
                        "username": "",
                        "password": "",
                        "keepalive": 60,
                        "conn_properties": {
                            "session_expiry_interval": 30,
                            "receive_maximum": 65535,
                            "maximum_packet_size": 0,
                            "topic_alias_maximum": 0,
                            "request_response_information": false,
                            "request_problem_information": true
                        },
                        "will_properties": {
                            "payload_format_indicator": 0,
                            "message_expiry_interval": 360,
                            "will_delay_interval": 20,
                            "user_properties": [
                                {
                                    "key": "key1",
                                    "value": "value1"
                                },
                                {
                                    "key": "key2",
                                    "value": "value2"
                                }
                            ]
                        }
                    },
                    "forwards": [
                        {
                            "remote_topic": "fwd/topic1",
                            "local_topic": "topic1",
                        },
                        {
                            "remote_topic": "fwd/topic2",
                            "local_topic": "topic2",
                        }
                    ],
                    "subscription": [
                        {
                            "remote_topic": "cmd/topic1",
                            "local_topic": "topic1",
                            "qos": 1
                        },
                        {
                            "remote_topic": "cmd/topic2",
                            "local_topic": "topic2",
                            "qos": 2
                        }
                    ],
                    "sub_properties": {
                        "identifier": 1,
                        "user_properties": [
                            {
                                "key": "key1",
                                "value": "value1"
                            },
                            {
                                "key": "key2",
                                "value": "value2"
                            }
                        ]
                    },
                    "tls": {
                        "enable": false,
                        "url": null,
                        "key_password": null,
                        "key": null,
                        "cert": null,
                        "cacert": null,
                        "verify_peer": false,
                        "fail_if_no_peer_cert": false
                    }
                }
            ]
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# GET /api/v4/bridges/{bridge_name}

通过桥接节点名称获取桥接配置

Path Parameters:

NameTypeRequiredDescription
bridge_nameStringTruebridge node name

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects桥接配置信息，详细请参见 [GET /api/v4/bridges](#GET /api/v4/bridges/)

Example:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/bridges/emqx"

{
    "code": 0,
    "data": {
        "bridge": {
            "nodes": [
                {
                    "name": "emqx",
                    "enable": true,
                    "parallel": 2,
                    "connector": {
                        "server": "mqtt-tcp://broker.emqx.io:1883",
                        "proto_ver": 5,
                        "clientid": null,
                        "clean_start": true,
                        "username": "",
                        "password": "",
                        "keepalive": 60,
                        "conn_properties": {
                            "session_expiry_interval": 30,
                            "receive_maximum": 65535,
                            "maximum_packet_size": 0,
                            "topic_alias_maximum": 0,
                            "request_response_information": false,
                            "request_problem_information": true
                        },
                        "will_properties": {
                            "payload_format_indicator": 0,
                            "message_expiry_interval": 360,
                            "will_delay_interval": 20,
                            "user_properties": [
                                {
                                    "key": "key1",
                                    "value": "value1"
                                },
                                {
                                    "key": "key2",
                                    "value": "value2"
                                }
                            ]
                        }
                    },
                    "forwards": [
                        {
                            "remote_topic": "fwd/topic1",
                            "local_topic": "topic1",
                            "qos": 1
                        },
                        {
                            "remote_topic": "fwd/topic2",
                            "local_topic": "topic2",
                            "qos": 2
                        }
                    ],
                    "subscription": [
                        {
                            "remote_topic": "cmd/topic1",
                            "local_topic": "topic1",
                            "qos": 1
                        },
                        {
                            "remote_topic": "cmd/topic2",
                            "local_topic": "topic2",
                            "qos": 2
                        }
                    ],
                    "sub_properties": {
                        "identifier": 1,
                        "user_properties": [
                            {
                                "key": "key1",
                                "value": "value1"
                            },
                            {
                                "key": "key2",
                                "value": "value2"
                            }
                        ]
                    },
                    "tls": {
                        "enable": false,
                        "url": null,
                        "key_password": null,
                        "key": null,
                        "cert": null,
                        "cacert": null,
                        "verify_peer": false,
                        "fail_if_no_peer_cert": false
                    }
                }
            ]
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# 动态更新桥接配置

此类 API 允许用户动态更新桥接配置，而无需重启 NanoMQ，Reload API 会触发桥接重连，修改桥接订阅主题不会重连。

# PUT /api/v4/bridges/{bridge_name}

更新桥接配置并触发桥接连接重连以立即生效。

Path Parameters:

NameTypeRequiredDescription
bridge_nameStringTrue桥接节点名称

Success Response Body (JSON):

NameTypeDescription
codeInteger0
bridge_nameObjects桥接客户端节点名称
bridge_name.nameString节点名字
bridge_name.enableBoolean启动桥接功能（默认false不启用）。
bridge_name.serverString桥接目标 broker 地址 URL 。
bridge_name.proto_verInteger桥接客户端 MQTT 版本（ 4 ｜ 5 ）。
bridge_name.clientidString桥接客户端 ID （默认 NULL 为自动生成随机 ID）。
bridge_name.keepaliveDuration保活间隔时间。
bridge_name.clean_startBoolean清除会话。
bridge_name.usernameString登录用户名。
bridge_name.passwordString登录密码。
bridge_name.conn_propertiesObjectConnector 的 MQTT V5 属性
bridge_name.will_propertiesObjectMQTT V5 遗嘱属性
bridge_name.ssl.enableBoolean启动 TLS 监听（默认false）。
bridge_name.ssl.key_passwordStringTLS 私钥密码。
bridge_name.ssl.keyfileStringTLS 私钥数据。
bridge_name.ssl.certfileStringTLS Cert 证书数据。
bridge_name.ssl.cacertfileStringTLS CA 证书数据。
bridge_name.parallelLong桥接客户端并发数。
bridge_name.forwards.[0].remote_topicString转发到远端的remote_topic。
bridge_name.forwards.[0].local_topicString转发到远端的local_topic。
bridge_name.subscription[0].remote_topicString第 1 个订阅remote_topic。
bridge_name.subscription[0].local_topicString第 1 个订阅local_topic。
bridge_name.subscription[0].qosInteger第 1 个订阅Qos。
bridge_name.sub_propertiesObjectSubscription 的 MQTT V5 属性
bridge_name.max_send_queue_lenInteger最大发送队列长度
bridge_name.max_recv_queue_lenInteger最大接收队列长度

Example:

$ curl -i --basic -u admin:public -X PUT 'http://localhost:8081/api/v4/bridges/emqx' -d '{
    "emqx": {
        "name": "emqx",
        "enable": true,
        "parallel": 8,
        "server": "mqtt-tcp://broker.emqx.io:1883",
        "proto_ver": 4,
        "clientid": "hello3",
        "clean_start": true,
        "username": "emqx",
        "password": "emqx123",
        "keepalive": 60,
        "forwards": [
            {
                "remote_topic": "fwd/topic1",
                "local_topic": "topic1",
                "qos": 1
            },
            {
                "remote_topic": "fwd/topic3",
                "local_topic": "topic3",
                "qos": 2
            }
        ],
        "subscription": [
            {
                "remote_topic": "cmd/topic1",
                "local_topic": "topic1",
                "qos": 1
            },
            {
                "remote_topic": "cmd/topic3",
                "local_topic": "topic3",
                "qos": 2
            }
        ]
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# PUT /api/v4/bridges/sub/{bridge_name}

动态新增桥接主题并立即生效。

Path Parameters:

NameTypeRequiredDescription
codeInteger0
dataObjects桥接节点配置信息
data.subscription[0].remote_topicString第 1 个订阅remote_topic。
data.subscription[0].local_topicString第 1 个订阅local_topic。
data.subscription[0].qosInteger第 1 个订阅Qos。
data.sub_propertiesObjectSubscription 的 MQTT V5 属性
data.sub_properties.identifierIntegerSubscription 的 ID
data.sub_properties.user_propertiesObjectSubscription 的 用户属性

Example:

以桥接节点名字为 “EMQX” 为例

$ curl --location 'http://127.0.0.1:8081/api/v4/bridges/sub/emqx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--data '{
    "data": {
        "subscription": [
            {
                "remote_topic": "cmd/topic4",
                "local_topic": "topic4",
                "qos": 1
            },
            {
                "remote_topic": "cmd/topic5",
                "local_topic": "topic5",
                "qos": 2
            }
        ],
        "sub_properties": {
            "identifier": 1,
            "user_properties": [
                {
                    "key": "key1",
                    "value": "value1"
                },
                {
                    "key": "key2",
                    "value": "value2"
                }
            ]
        }
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# PUT /api/v4/bridges/unsub/{bridge_name}

动态删除桥接订阅主题并立即生效。

Path Parameters:

NameTypeRequiredDescription
bridge_nameStringTrue桥接节点名称

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjects桥接节点配置信息
data.unsubscription[0].topicString第 1 个订阅Topic。
data.unsubscription[0].qosInteger第 1 个订阅Qos。
data.unsub_propertiesObjectSubscription 的 MQTT V5 属性
data.unsub_properties.identifierIntegerSubscription 的 ID
data.unsub_properties.user_propertiesObjectSubscription 的 用户属性

Example:

以桥接节点名字为 “EMQX” 为例

$ curl --location 'http://127.0.0.1:8081/api/v4/bridges/unsub/emqx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--data '{
    "data": {
        "unsubscription": [
            {
                "topic": "cmd/topic1"
            },
            {
                "topic": "cmd/topic2"
            }
        ],
        "unsub_properties": {
            "user_properties": [
                {
                    "key": "key1",
                    "value": "value1"
                },
                {
                    "key": "key2",
                    "value": "value2"
                }
            ]
        }
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Broker 控制

# POST /api/v4/ctrl/{action}

控制 broker 停止或重启（通常应用在修改配置后）

Path Parameters:

NameTypeRequiredDescription
clientidStringTrue可取值: stop, restart

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/ctrl/restart'

{"code":0}
1
2
3

# 规则

查询规则引擎的动作

# GET /api/v4/rules/

获取规则列表, 包括规则的 SQL, id 等。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件：规则是否开启状态
dataArray of Objects规则详情
data[0].idString规则 ID
data[0].rawsqlStringSQL 语句，与请求中的 rawsql 一致

# GET /api/v4/rules/{rule_id}

获取某个规则的详情, 包括规则的 SQL, id 等。 Path Parameters:

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件：规则是否开启状态
dataArray of Objects规则详情
- data.idString规则 ID
- data.rawsqlStringSQL 语句，与请求中的 rawsql 一致

# POST /api/v4/rules

创建规则，返回规则 ID 。

Parameters (json):

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件：规则是否开启状态
dataArray of Objects规则详情
- data.idString规则 ID
- data.rawsqlStringSQL 语句，与请求中的 rawsql 一致

# 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
enabledBoolean过滤条件：规则是否开启状态
dataArray of Objects规则详情
- data.idString规则 ID
- data.rawsqlStringSQL 语句，与请求中的 rawsql 一致

# DELETE /api/v4/rules/{rule_id}

删除规则。

Parameters: 无

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

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

$ curl -XPOST -d '{
  "rawsql": "select * from \"t/a\"",
  "actions": [{
      "name": "repub",
      "params": {
          "topic": "repub1", "address":"mqtt-tcp://broker.emqx.io:1883", "clean_start": "true", "clientid": "id", "username": "admin", "password": "public", "proto_ver": 4, "keepalive": 60
      }
  }],
  "description": "repub-rule"

}' --basic -u admin:public 'http://localhost:8081/api/v4/rules'

{"data":{"rawsql":"select * from \"t/a\"","id":4,"enabled":true},"actions":[],"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13

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

$ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'

{"data":{"rawsql":"select * from \"t/a\"","id":1,"enabled":true},"actions":[],"code":0}
1
2
3

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

$ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules'

{"data":[{"rawsql":"SELECT payload.x.y as y, payload.z as z FROM \"#\" WHERE y > 10 and z != 'str'","id":1,"enabled":true},{"rawsql":"SELECT * FROM \"abc\"","id":2,"enabled":true},{"rawsql":"SELECT payload, qos FROM \"#\" WHERE qos > 0","id":3,"enabled":true},{"rawsql":"select * from \"t/a\"","id":4,"enabled":true}],"code":0}
1
2
3

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

$ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4' -d '{"rawsql":"select * from \"t/b\""}'

{"data":{"rawsql":"select * from \"t/b\"","id":4,"enabled":true},"actions":[],"code":0}
1
2
3

停用规则 (disable):

$ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4' -d '{"enabled": false}'
{"data":{"rawsql":"select * from \"t/b\"","id":4,"enabled":false},"actions":[],"code":0}
1
2

删除规则:

$ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'

{"code":0}
1
2
3

← HTTP-API (v1) →

编辑此页
本页导航