< 反馈文档问题
API docs by Redocly

EMQX API (5.2.1)

Download OpenAPI specification:Download

Authentication

调整全局认证链上指定认证器的顺序。

调整全局认证链上指定认证器的顺序。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

position
required
string
Example: before:password_based:built_in_database

认证器在链中的位置。可能的值是 'front', 'rear', 'before:{other_authenticator_id}', 'after:{other_authenticator_id}'

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

删除全局认证链上指定认证器中的指定用户数据。

删除全局认证链上指定认证器中的指定用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

user_id
required
string

用户 ID，根据设置的账号类型不同，可以是 username 或 clientid

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

获取全局认证链上指定认证器中的指定用户数据。

获取全局认证链上指定认证器中的指定用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

user_id
required
string

用户 ID，根据设置的账号类型不同，可以是 username 或 clientid

Responses

Response samples

Content type
application/json
Example
{
  • "user_id": "user1"
}

更新全局认证链上指定认证器中的指定用户数据。

更新全局认证链上指定认证器中的指定用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

user_id
required
string

用户 ID，根据设置的账号类型不同，可以是 username 或 clientid

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

为全局认证链上的指定认证器导入用户数据。

为全局认证链上的指定认证器导入用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

Request Body schema: multipart/form-data
filename
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

获取全局认证链上指定认证器中的用户列表。

获取全局认证链上指定认证器中的用户列表。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

like_user_id
string

使用用户 ID （username 或 clientid）模糊查询。

is_superuser
boolean

是否是超级用户。

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

向全局认证链上的指定认证器添加用户数据，仅使用内置数据库作为数据源的认证器支持。

向全局认证链上的指定认证器添加用户数据，仅使用内置数据库作为数据源的认证器支持。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
Example
{
  • "user_id": "user1"
}

获取全局认证链上指定认证器的指标与状态。

获取全局认证链上指定认证器的指标与状态。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_error": [ ],
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ],
  • "node_status": [
    ],
  • "resource_metrics": {
    },
  • "status": "connected"
}

删除全局认证链上的指定认证器。

删除全局认证链上的指定认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

获取全局认证链上的指定认证器。emqx_dashboard_error_code_apiemqx_d

获取全局认证链上的指定认证器。emqx_dashboard_error_code_apiemqx_dashboard_error_code_api

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

Responses

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

更新全局认证链上的指定认证器。

更新全局认证链上的指定认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

认证器 ID。由认证方式与数据源组成 {mechanism}:{built_in_database}，如 password_based:built_in_database

Request Body schema: application/json
One of
mechanism
required
string
Value: "scram"

认证机制。

backend
required
string
Value: "built_in_database"

后端类型。

algorithm
string
Default: "sha256"
Enum: "sha256" "sha512"

Hashing algorithm.

iteration_count
integer >= 0
Default: 4096

Iteration count.

enable
boolean
Default: true

设为 true 或 false 以启用或禁用此认证数据源。

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

列出全局认证链上的认证器。

列出全局认证链上的认证器。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

为全局认证链创建认证器。

为全局认证链创建认证器。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
mechanism
required
string
Value: "scram"

认证机制。

backend
required
string
Value: "built_in_database"

后端类型。

algorithm
string
Default: "sha256"
Enum: "sha256" "sha512"

Hashing algorithm.

iteration_count
integer >= 0
Default: 4096

Iteration count.

enable
boolean
Default: true

设为 true 或 false 以启用或禁用此认证数据源。

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Metrics

EMQX 监控指标信息

EMQX 监控指标信息

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Whether to aggregate all nodes Metrics

Responses

Response samples

Content type
application/json
Example
[ ]

EMQX stats

EMQX stats

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Calculation aggregate for all nodes

Responses

Response samples

Content type
application/json
Example
[ ]

Current monitor (statistics) data, e.g. number of

Current monitor (statistics) data, e.g. number of connections and connection rate in the whole cluster.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "received_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0
}

Node monitor (statistics) data, e.g. number of con

Node monitor (statistics) data, e.g. number of connections and connection rate on the specified node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

EMQX node name.

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "received_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0
}

列出指定节点的监控数据

列出指定节点的监控数据

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

EMQX node name.

query Parameters
latest
integer >= 1
Example: latest=300

The latest N seconds data. Like 300 for 5 min.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

列出集群所有节点的监控数据

列出集群所有节点的监控数据

Authorizations:
basicAuthbearerAuth
query Parameters
latest
integer >= 1
Example: latest=300

The latest N seconds data. Like 300 for 5 min.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

MQTT

查看慢订阅状态

查看慢订阅状态

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "max_delayed_messages": 0
}

开启或者关闭功能，或者设置延迟消息数量上限

开启或者关闭功能，或者设置延迟消息数量上限

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: true

是否开启该功能

max_delayed_messages
integer
Default: 0

延迟消息的数量上限(0 代表无限)

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "max_delayed_messages": 0
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "max_delayed_messages": 0
}

删除延迟消息

删除延迟消息

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

消息的来源节点

msgid
required
string

延迟消息 ID

Responses

Response samples

Content type
application/json
{
  • "code": "MESSAGE_ID_SCHEMA_ERROR",
  • "message": "string"
}

查看延迟消息

查看延迟消息

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

消息的来源节点

msgid
required
string

延迟消息 ID

Responses

Response samples

Content type
application/json
{
  • "msgid": 0,
  • "node": "string",
  • "publish_at": "string",
  • "delayed_interval": 1,
  • "delayed_remaining": 0,
  • "expected_at": "string",
  • "topic": "/sys/#",
  • "qos": 0,
  • "from_clientid": "string",
  • "from_username": "string"
}

列出全部主题重写规则

列出全部主题重写规则

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

更新全部主题重写规则

更新全部主题重写规则

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
action
required
string
Enum: "subscribe" "publish" "all"

主题重写在哪种操作上生效：
- subscribe：订阅时重写主题；
- publish：发布时重写主题；
-all：全部重写主题

source_topic
required
string

源主题，客户端业务指定的主题

dest_topic
required
string

目标主题。

re
required
string

正则表达式

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

删除主题监控数据

删除主题监控数据

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string
Example: testtopic/1

主题字符串。注意：主题字符串在url路径中必须编码

Responses

Response samples

Content type
application/json
{
  • "code": "TOPIC_NOT_FOUND",
  • "message": "string"
}

获取主题监控数据

获取主题监控数据

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string
Example: testtopic/1

主题字符串。注意：主题字符串在url路径中必须编码

Responses

Response samples

Content type
application/json
{
  • "topic": "testtopic/1",
  • "create_time": "2022-01-14T21:48:47+08:00",
  • "reset_time": "2022-01-14T21:48:47+08:00",
  • "metrics": {
    }
}

获取主题监控数据

获取主题监控数据

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

创建主题监控数据

创建主题监控数据

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
topic
required
string

主题字符串

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

重置主题监控状态

重置主题监控状态

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
topic
string

主题名称。如果此参数不存在，则所有创建的主题监控数据都将重置。

action
required
string

操作，仅支持 reset

Responses

Request samples

Content type
application/json
Example
{
  • "action": "reset"
}

Response samples

Content type
application/json
{
  • "code": "TOPIC_NOT_FOUND",
  • "message": "string"
}

查看延迟消息列表

查看延迟消息列表

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

LwM2M Gateways

Observe a Resource

Observe/Un-Observe 指定资源

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7
enable
required
boolean
Example: enable=true

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_NOT_FOUND",
  • "message": "string"
}

List Client's Resources

查看指定资源状态

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7
action
required
string
Example: action=discover

Responses

Response samples

Content type
application/json
{
  • "clientid": "urn:oma:lwm2m:oma:2",
  • "path": "/3/0/7",
  • "action": "discover",
  • "codeMsg": "reply_not_received",
  • "content": [
    ]
}

Read Value from a Resource Path

发送读指令到某资源

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_NOT_FOUND",
  • "message": "string"
}

Write a Value to Resource Path

发送写指令到某资源

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7
type
required
string
Enum: "Integer" "Float" "Time" "String" "Boolean" "Opaque" "Objlnk"
Example: type=Integer
value
required
string
Example: value=123

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_NOT_FOUND",
  • "message": "string"
}

Plugins

Delete a plugin

Uninstalls a previously uploaded plugin package.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Responses

Response samples

Content type
application/json
{
  • "code": "PARAM_ERROR",
  • "message": "string"
}

Get a plugin description

Describs plugin according to its release.json and README.md.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Responses

Response samples

Content type
application/json
{
  • "name": "emqx_plugin_template-5.0-rc.1",
  • "author": [
    ],
  • "builder": {
    },
  • "built_on_otp_release": "24",
  • "compatibility": {
    },
  • "git_commit_or_build_date": "2021-12-25",
  • "functionality": [
    ],
  • "git_ref": "ddab50fafeed6b1faea70fc9ffd8c700d7e26ec1",
  • "metadata_vsn": "0.1.0",
  • "rel_vsn": "5.0-rc.1",
  • "rel_apps": [
    ],
  • "repo": "https://github.com/emqx/emqx-plugin-template",
  • "description": "This is an demo plugin description",
  • "running_status": [
    ],
  • "readme": "This is an demo plugin."
}

Trigger action on an installed plugin

start/stop a installed plugin.
- start: start the plugin.
- stop: stop the plugin.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

action
required
string
Enum: "start" "stop"

Action

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List all installed plugins

Plugins are launched in top-down order.
Use POST /plugins/{name}/move to change the boot order.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Move plugin within plugin hiearchy

Setting the boot order of plugins.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Request Body schema: application/json
string or string or string


Enable auto-boot at position in the boot list, where Position could be
'front', 'rear', or 'before:other-vsn', 'after:other-vsn'
to specify a relative position.

Responses

Request samples

Content type
application/json
Example
{
  • "position": "after:emqx_plugin_demo-5.1-rc.2"
}

Response samples

Content type
application/json
{
  • "code": "MOVE_FAILED",
  • "message": "string"
}

Install a new plugin

Upload a plugin tarball (plugin-vsn.tar.gz).Follow emqx-plugin-template to develop plugin.

Authorizations:
basicAuthbearerAuth
Request Body schema: multipart/form-data
plugin
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "UNEXPECTED_ERROR",
  • "message": "string"
}

Bridges

Reset bridge metrics

通过 ID 重置 Bridge 的计数

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Stop/restart bridge

在某个节点上停止/重新启动 Bridge。

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

节点名，比如 emqx@127.0.0.1

id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

operation
required
string
Enum: "start" "stop" "restart"
Example: start

节点可用操作：停止、重新启动

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Test creating bridge

通过给定的 ID 测试创建一个新的桥接。

ID 的格式必须为 ’{type}:{name}”

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "webhook"

The Bridge Type

name
required
string

Bridge name, used as a human-readable description of the bridge.

enable
boolean
Default: true

Enable or disable this bridge

object (bridge_webhook.creation_opts)
connect_timeout
string
Default: "15s"

The timeout when connecting to the HTTP server.

retry_interval
string
Deprecated
pool_type
string
Default: "random"
Enum: "random" "hash"

The type of the pool. Can be one of random, hash.

pool_size
integer >= 1
Default: 8

The pool size.

enable_pipelining
integer >= 1
Default: 100

A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

object (connector-http.request)
object (broker.ssl_client_opts)
url
required
string

The URL of the HTTP Bridge.

Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.

For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.

direction
string
Deprecated
Value: "egress"

Deprecated, The direction of this bridge, MUST be 'egress'

local_topic
string

The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.

NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.

method
string
Default: "post"
Enum: "post" "put" "get" "delete"

The method of the HTTP request. All the available methods are: post, put, get, delete.

Template with variables is allowed.

headers
object
Default: {"accept":"application/json","cache-control":"no-cache","connection":"keep-alive","content-type":"application/json","keep-alive":"timeout=5"}

The headers of the HTTP request.

Template with variables is allowed.

body
string

The body of the HTTP request.

If not provided, the body will be a JSON object of all the available fields.

There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the local_topic is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).

Template with variables is allowed.

max_retries
integer >= 0
Default: 2

HTTP request max retry times if failed.

request_timeout
string
Deprecated
Default: "15s"

HTTP request timeout.

Responses

Request samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

Enable or disable bridge

启用或禁用所有节点上的桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

enable
required
boolean
Example: true

是否启用桥接

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Get bridge metrics

通过 Id 来获取桥接的指标信息

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

Delete bridge

通过 ID 删除 Bridge

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get bridge

通过 ID 获取 Bridge

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

Responses

Response samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Update bridge

通过 ID 更新 Bridge

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

Request Body schema: application/json
One of
enable
boolean
Default: true

Enable or disable this bridge

object (bridge_webhook.creation_opts)
connect_timeout
string
Default: "15s"

The timeout when connecting to the HTTP server.

retry_interval
string
Deprecated
pool_type
string
Default: "random"
Enum: "random" "hash"

The type of the pool. Can be one of random, hash.

pool_size
integer >= 1
Default: 8

The pool size.

enable_pipelining
integer >= 1
Default: 100

A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

object (connector-http.request)
object (broker.ssl_client_opts)
url
required
string

The URL of the HTTP Bridge.

Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.

For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.

direction
string
Deprecated
Value: "egress"

Deprecated, The direction of this bridge, MUST be 'egress'

local_topic
string

The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.

NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.

method
string
Default: "post"
Enum: "post" "put" "get" "delete"

The method of the HTTP request. All the available methods are: post, put, get, delete.

Template with variables is allowed.

headers
object
Default: {"accept":"application/json","cache-control":"no-cache","connection":"keep-alive","content-type":"application/json","keep-alive":"timeout=5"}

The headers of the HTTP request.

Template with variables is allowed.

body
string

The body of the HTTP request.

If not provided, the body will be a JSON object of all the available fields.

There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the local_topic is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).

Template with variables is allowed.

max_retries
integer >= 0
Default: 2

HTTP request max retry times if failed.

request_timeout
string
Deprecated
Default: "15s"

HTTP request timeout.

Responses

Request samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "username": "foo"
}

Response samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Stop or restart bridge

停止或启用所有节点上的桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: webhook:webhook_example

Bridge ID ， 格式为 {type}:{name}

operation
required
string
Enum: "start" "stop" "restart"
Example: start

集群可用操作：停止、重新启动

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List bridges

列出所有 Bridge

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create bridge

通过类型和名字创建 Bridge

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "webhook"

The Bridge Type

name
required
string

Bridge name, used as a human-readable description of the bridge.

enable
boolean
Default: true

Enable or disable this bridge

object (bridge_webhook.creation_opts)
connect_timeout
string
Default: "15s"

The timeout when connecting to the HTTP server.

retry_interval
string
Deprecated
pool_type
string
Default: "random"
Enum: "random" "hash"

The type of the pool. Can be one of random, hash.

pool_size
integer >= 1
Default: 8

The pool size.

enable_pipelining
integer >= 1
Default: 100

A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

object (connector-http.request)
object (broker.ssl_client_opts)
url
required
string

The URL of the HTTP Bridge.

Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.

For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.

direction
string
Deprecated
Value: "egress"

Deprecated, The direction of this bridge, MUST be 'egress'

local_topic
string

The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.

NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.

method
string
Default: "post"
Enum: "post" "put" "get" "delete"

The method of the HTTP request. All the available methods are: post, put, get, delete.

Template with variables is allowed.

headers
object
Default: {"accept":"application/json","cache-control":"no-cache","connection":"keep-alive","content-type":"application/json","keep-alive":"timeout=5"}

The headers of the HTTP request.

Template with variables is allowed.

body
string

The body of the HTTP request.

If not provided, the body will be a JSON object of all the available fields.

There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the local_topic is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).

Template with variables is allowed.

max_retries
integer >= 0
Default: 2

HTTP request max retry times if failed.

request_timeout
string
Deprecated
Default: "15s"

HTTP request timeout.

Responses

Request samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Response samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Status

节点的健康检查。 返回节点状态的描述信息。<br/><br/>如果 EMQX 应用程序已经启动并运行

节点的健康检查。 返回节点状态的描述信息。

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

这个API是在v5.0.10中引入的。
GET /status端点（没有/api/...前缀）也是这个端点的一个别名，工作方式相同。 这个别名从v5.0.0开始就有了。
自 v5.0.25 和 e5.0.4 开始，可以通过指定 'format' 参数来得到 JSON 格式的信息。

query Parameters
format
string
Default: "text"

指定返回的内容格式。使用 'text'（默认）则返回自由格式的字符串； 'json' 则返回 JSON 格式。

Responses

Topics

获取主题到节点名称的路由映射

获取主题到节点名称的路由映射

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic Name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

列出主题

列出主题

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

Topic Name

node
string
Example: node=emqx@127.0.0.1

Node Name

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Authorization

根据用户名查询内置数据库中相关的授权规则。

根据用户名查询内置数据库中相关的授权规则。

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

like_username
string

使用字串匹配模糊搜索用户名

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

为指定的用户在内置数据库中添加授权规则。

为指定的用户在内置数据库中添加授权规则。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
Array of objects (emqx_authz_api_mnesia.rule_item)
username
required
string

用户名

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

根据客户端ID查询内置数据库中的授权规则。

根据客户端ID查询内置数据库中的授权规则。

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

like_clientid
string

使用字串匹配模糊搜索客户端标识符

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

为指定客户端添加内置数据库中客户端的规则。

为指定客户端添加内置数据库中客户端的规则。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
Array of objects (emqx_authz_api_mnesia.rule_item)
clientid
required
string

客户端标识符

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

删除内置数据库中指定客户端的授权规则

删除内置数据库中指定客户端的授权规则

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

客户端标识符

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

获取内置数据库中指定客户端的授权规则

获取内置数据库中指定客户端的授权规则

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

客户端标识符

Responses

Response samples

Content type
application/json
{
  • "clientid": "client1",
  • "rules": [
    ]
}

更新内置数据库中指定客户端的授权规则

更新内置数据库中指定客户端的授权规则

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

客户端标识符

Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)
clientid
required
string

客户端标识符

Responses

Request samples

Content type
application/json
{
  • "clientid": "client1",
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

获取指定授权数据源的状态

获取指定授权数据源的状态

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "http" "mongodb" "redis" "built_in_database" "mysql" "postgresql" "file"

数据源类型

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ],
  • "node_status": [
    ],
  • "resource_metrics": {
    },
  • "status": "connected"
}

列出所有授权数据源。

列出所有授权数据源。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ]
}

添加授权数据源

添加授权数据源

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
enable
boolean
Default: true

设为 true 或 false 以启用或禁用此访问控制数据源。

type
required
string
Default: "file"
Value: "file"

数据后端类型。

rules
required
string

静态授权文件规则。

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "type": "file",
  • "rules": "{allow,{username,{re,\"^dashboard$\"}},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}."
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

删除内置数据库中指定用户名的授权规则

删除内置数据库中指定用户名的授权规则

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

用户名

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

获取内置数据库中指定用户名授权规则

获取内置数据库中指定用户名授权规则

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

用户名

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "username": "user1"
}

更新内置数据库中指定用户名的授权规则

更新内置数据库中指定用户名的授权规则

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

用户名

Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)
username
required
string

用户名

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ],
  • "username": "user1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

清除内置数据库中的所有类型（'users' 、'clients' 、'all'）的所有规则

清除内置数据库中的所有类型（'users' 、'clients' 、'all'）的所有规则

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

更新授权数据源的优先执行顺序

更新授权数据源的优先执行顺序

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "http" "mongodb" "redis" "built_in_database" "mysql" "postgresql" "file"

数据源类型

Request Body schema: application/json
position
required
string

认证数据源位置。

Responses

Request samples

Content type
application/json
Example
{
  • "position": "front"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

删除指定类型的授权数据源

删除指定类型的授权数据源

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "http" "mongodb" "redis" "built_in_database" "mysql" "postgresql" "file"

数据源类型

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

获取指定类型的授权数据源

获取指定类型的授权数据源

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "http" "mongodb" "redis" "built_in_database" "mysql" "postgresql" "file"

数据源类型

Responses

Response samples

Content type
application/json
Example
{
  • "enable": true,
  • "type": "file",
  • "rules": "{allow,{username,{re,\"^dashboard$\"}},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}."
}

更新指定类型的授权数据源

更新指定类型的授权数据源

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "http" "mongodb" "redis" "built_in_database" "mysql" "postgresql" "file"

数据源类型

Request Body schema: application/json
One of
enable
boolean
Default: true

设为 true 或 false 以启用或禁用此访问控制数据源。

type
required
string
Default: "file"
Value: "file"

数据后端类型。

rules
required
string

静态授权文件规则。

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "type": "file",
  • "rules": "{allow,{username,{re,\"^dashboard$\"}},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}."
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

清除集群中所有授权数据缓存。

清除集群中所有授权数据缓存。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

获取授权配置

获取授权配置

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "no_match": "allow",
  • "deny_action": "ignore",
  • "cache": {
    }
}

更新授权配置

更新授权配置

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
no_match
required
string
Default: "allow"
Enum: "allow" "deny"

如果用户或客户端不匹配ACL规则，或者从可配置授权源(比如内置数据库、HTTP API 或 PostgreSQL 等。)内未找
到此类用户或客户端时，模式的认访问控制操作。
在“授权”中查找更多详细信息。

deny_action
required
string
Default: "ignore"
Enum: "ignore" "disconnect"

授权检查拒绝操作时的操作。

object (broker.authz_cache)

Responses

Request samples

Content type
application/json
{
  • "no_match": "allow",
  • "deny_action": "ignore",
  • "cache": {
    }
}

Response samples

Content type
application/json
{
  • "no_match": "allow",
  • "deny_action": "ignore",
  • "cache": {
    }
}

删除 'all' 规则

删除 'all' 规则

Authorizations:
basicAuthbearerAuth

Responses

列出适用于所有客户端规则 （即 'all' 规则）。

列出适用于所有客户端规则 （即 'all' 规则）。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

创建或更新适用于所有客户端的规则（即 'all' 规则）。

创建或更新适用于所有客户端的规则（即 'all' 规则）。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Nodes

获取节点上的统计信息，例如主题数量，连接数量等。

获取节点上的统计信息，例如主题数量，连接数量等。

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "channels.count": 0,
  • "channels.max": 0,
  • "connections.count": 0,
  • "connections.max": 0,
  • "delayed.count": 0,
  • "delayed.max": 0,
  • "live_connections.count": 0,
  • "live_connections.max": 0,
  • "retained.count": 0,
  • "retained.max": 0,
  • "sessions.count": 0,
  • "sessions.max": 0,
  • "suboptions.count": 0,
  • "suboptions.max": 0,
  • "subscribers.count": 0,
  • "subscribers.max": 0,
  • "subscriptions.count": 0,
  • "subscriptions.max": 0,
  • "subscriptions.shared.count": 0,
  • "subscriptions.shared.max": 0,
  • "topics.count": 0,
  • "topics.max": 0
}

获取节节点上的运行计数信息，例如消息发送数量，收到或发送字节数，认证和授权成功失败次数等。

获取节节点上的运行计数信息，例如消息发送数量，收到或发送字节数，认证和授权成功失败次数等。

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "node": "string",
  • "actions.failure": 0,
  • "actions.success": 0,
  • "bytes.received": 0,
  • "bytes.sent": 0,
  • "client.auth.anonymous": 0,
  • "client.authenticate": 0,
  • "client.check_authz": 0,
  • "client.connack": 0,
  • "client.connect": 0,
  • "client.connected": 0,
  • "client.disconnected": 0,
  • "client.subscribe": 0,
  • "client.unsubscribe": 0,
  • "delivery.dropped": 0,
  • "delivery.dropped.expired": 0,
  • "delivery.dropped.no_local": 0,
  • "delivery.dropped.qos0_msg": 0,
  • "delivery.dropped.queue_full": 0,
  • "delivery.dropped.too_large": 0,
  • "messages.acked": 0,
  • "messages.delayed": 0,
  • "messages.delivered": 0,
  • "messages.dropped": 0,
  • "messages.dropped.await_pubrel_timeout": 0,
  • "messages.dropped.no_subscribers": 0,
  • "messages.forward": 0,
  • "messages.publish": 0,
  • "messages.qos0.received": 0,
  • "messages.qos0.sent": 0,
  • "messages.qos1.received": 0,
  • "messages.qos1.sent": 0,
  • "messages.qos2.received": 0,
  • "messages.qos2.sent": 0,
  • "messages.received": 0,
  • "messages.retained": 0,
  • "messages.sent": 0,
  • "packets.auth.received": 0,
  • "packets.auth.sent": 0,
  • "packets.connack.auth_error": 0,
  • "packets.connack.error": 0,
  • "packets.connack.sent": 0,
  • "packets.connect.received": 0,
  • "packets.disconnect.received": 0,
  • "packets.disconnect.sent": 0,
  • "packets.pingreq.received": 0,
  • "packets.pingresp.sent": 0,
  • "packets.puback.inuse": 0,
  • "packets.puback.missed": 0,
  • "packets.puback.received": 0,
  • "packets.puback.sent": 0,
  • "packets.pubcomp.inuse": 0,
  • "packets.pubcomp.missed": 0,
  • "packets.pubcomp.received": 0,
  • "packets.pubcomp.sent": 0,
  • "packets.publish.auth_error": 0,
  • "packets.publish.dropped": 0,
  • "packets.publish.error": 0,
  • "packets.publish.inuse": 0,
  • "packets.publish.received": 0,
  • "packets.publish.sent": 0,
  • "packets.pubrec.inuse": 0,
  • "packets.pubrec.missed": 0,
  • "packets.pubrec.received": 0,
  • "packets.pubrec.sent": 0,
  • "packets.pubrel.missed": 0,
  • "packets.pubrel.received": 0,
  • "packets.pubrel.sent": 0,
  • "packets.received": 0,
  • "packets.sent": 0,
  • "packets.suback.sent": 0,
  • "packets.subscribe.auth_error": 0,
  • "packets.subscribe.error": 0,
  • "packets.subscribe.received": 0,
  • "packets.unsuback.sent": 0,
  • "packets.unsubscribe.error": 0,
  • "packets.unsubscribe.received": 0,
  • "rules.matched": 0,
  • "session.created": 0,
  • "session.discarded": 0,
  • "session.resumed": 0,
  • "session.takenover": 0,
  • "session.terminated": 0
}

获取节点信息

获取节点信息

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "connections": 0,
  • "live_connections": 0,
  • "load1": 2.66,
  • "load5": 2.66,
  • "load15": 2.66,
  • "max_fds": 1024,
  • "memory_total": "512.00M",
  • "memory_used": "256.00M",
  • "node_status": "running",
  • "otp_release": "24.2/12.2",
  • "process_available": 2097152,
  • "process_used": 1024,
  • "uptime": 5120000,
  • "version": "5.0.0",
  • "edition": "Opensource",
  • "sys_path": "path/to/emqx",
  • "log_path": "path/to/log | The log path is not yet set",
  • "role": "core"
}

列出所有 EMQX 节点

列出所有 EMQX 节点

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ExHook

删除 Exhook 服务器

删除 Exhook 服务器

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

Exhook 服务器的名称

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

查看 Exhook 服务器详细信息

查看 Exhook 服务器详细信息

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

Exhook 服务器的名称

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "hooks": [
    ],
  • "name": "default",
  • "enable": true,
  • "url": "http://127.0.0.1:9000",
  • "request_timeout": "12m",
  • "failed_action": "deny",
  • "ssl": {
    },
  • "socket_options": {
    },
  • "auto_reconnect": "60s",
  • "pool_size": 8
}

更新 Exhook 服务器

更新 Exhook 服务器

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

Exhook 服务器的名称

Request Body schema: application/json
name
required
string

ExHook 服务器名称

enable
boolean
Default: true

开启这个 Exhook 服务器

url
required
string

gRPC 服务器地址

request_timeout
string
Default: "5s"

gRPC 服务器请求超时时间

failed_action
string
Default: "deny"
Enum: "deny" "ignore"

当 gRPC 请求失败后的操作

object (exhook.ssl_conf)
object (exhook.socket_options)
string or string
Default: "60s"

自动重连到 gRPC 服务器的设置。
当 gRPC 服务器不可用时，Exhook 将会按照这里设置的间隔时间进行重连，并重新初始化注册的钩子

pool_size
integer >= 1
Default: 8

gRPC 客户端进程池大小

Responses

Request samples

Content type
application/json
{
  • "auto_reconnect": "60s",
  • "enable": true,
  • "failed_action": "deny",
  • "name": "default",
  • "pool_size": 8,
  • "request_timeout": "5s",
  • "ssl": {
    },
  • "url": "http://127.0.0.1:8081"
}

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "hooks": [
    ],
  • "name": "default",
  • "enable": true,
  • "url": "http://127.0.0.1:9000",
  • "request_timeout": "12m",
  • "failed_action": "deny",
  • "ssl": {
    },
  • "socket_options": {
    },
  • "auto_reconnect": "60s",
  • "pool_size": 8
}

移动 Exhook 服务器顺序。<br/>注意: 移动的参数只能是：front | rear | b

移动 Exhook 服务器顺序。
注意: 移动的参数只能是：front | rear | before:{name} | after:{name}

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

Exhook 服务器的名称

Request Body schema: application/json
position
required
string

移动的方向

Responses

Request samples

Content type
application/json
Example
{
  • "position": "front"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

查看ExHook 服务器列表

查看ExHook 服务器列表

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

添加 ExHook 服务器

添加 ExHook 服务器

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
required
string

ExHook 服务器名称

enable
boolean
Default: true

开启这个 Exhook 服务器

url
required
string

gRPC 服务器地址

request_timeout
string
Default: "5s"

gRPC 服务器请求超时时间

failed_action
string
Default: "deny"
Enum: "deny" "ignore"

当 gRPC 请求失败后的操作

object (exhook.ssl_conf)
object (exhook.socket_options)
string or string
Default: "60s"

自动重连到 gRPC 服务器的设置。
当 gRPC 服务器不可用时，Exhook 将会按照这里设置的间隔时间进行重连，并重新初始化注册的钩子

pool_size
integer >= 1
Default: 8

gRPC 客户端进程池大小

Responses

Request samples

Content type
application/json
{
  • "auto_reconnect": "60s",
  • "enable": true,
  • "failed_action": "deny",
  • "name": "default",
  • "pool_size": 8,
  • "request_timeout": "5s",
  • "ssl": {
    },
  • "url": "http://127.0.0.1:8081"
}

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "hooks": [
    ],
  • "name": "default",
  • "enable": true,
  • "url": "http://127.0.0.1:9000",
  • "request_timeout": "12m",
  • "failed_action": "deny",
  • "ssl": {
    },
  • "socket_options": {
    },
  • "auto_reconnect": "60s",
  • "pool_size": 8
}

获取 Exhook 服务器的钩子信息

获取 Exhook 服务器的钩子信息

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

Exhook 服务器的名称

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Monitor

Get Prometheus config info

Get Prometheus config info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "push_gateway_server": "http://127.0.0.1:9091"
}

Update Prometheus config

Update Prometheus config

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
push_gateway_server
required
string
Default: "http://127.0.0.1:9091"

Prometheus 服务器地址

interval
required
string
Default: "15s"

数据推送间隔

headers
Array of objects
Default: {}

推送到 Push Gateway 的 HTTP Headers 列表。

例如， { Authorization = "some-authz-tokens"}

job_name
required
string
Default: "${name}/instance/${name}~${host}"

推送到 Push Gateway 的 Job 名称。可用变量为：

- ${name}: EMQX 节点的名称。
- ${host}: EMQX 节点主机名。
例如，当 EMQX 节点名为 emqx@127.0.0.1 则 name 变量的值为 emqx，host 变量的值为 127.0.0.1。

默认值为: ${name}/instance/${name}~${host}

enable
required
boolean
Default: false

开启或关闭 Prometheus 数据推送

vm_dist_collector
required
string
Default: "disabled"
Enum: "disabled" "enabled"

开启或关闭 VM 分布采集器，收集 Erlang 分布机制中涉及的套接字和进程的信息。

mnesia_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

开启或关闭 Mnesia 采集器, 使用 mnesia:system_info/1 收集 Mnesia 相关指标

vm_statistics_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

开启或关闭 VM 统计采集器, 使用 erlang:statistics/1 收集 Erlang VM 相关指标

vm_system_info_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

开启或关闭 VM 系统信息采集器, 使用 erlang:system_info/1 收集 Erlang VM 相关指标

vm_memory_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

开启或关闭 VM 内存采集器, 使用 erlang:memory/0 收集 Erlang 虚拟机动态分配的内存信息，同时提供基本的 (D)ETS 统计信息

vm_msacc_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

开启或关闭 VM msacc 采集器, 使用 erlang:statistics(microstate_accounting) 收集微状态计数指标

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "push_gateway_server": "http://127.0.0.1:9091"
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "push_gateway_server": "http://127.0.0.1:9091"
}

Get Prometheus Data

Get Prometheus Data

Responses

Response samples

Content type
No sample

Get opentelmetry configuration

Get opentelmetry configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{}

Update opentelmetry configuration

Update opentelmetry configuration

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (opentelemetry.exporter)
enable
required
boolean
Default: false

Enable or disable open telemetry metrics

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Auto Subscribe

获取自动订阅主题列表

获取自动订阅主题列表

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

更新自动订阅主题列表

更新自动订阅主题列表

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
topic
required
string

订阅标识符，支持使用占位符，例如 client/${clientid}/username/${username}/host/${host}/port/${port}
必填，且不可为空字符串

qos
integer [ 0 .. 2 ]
Default: 0

缺省值为 0，服务质量，
QoS 0：消息最多传递一次，如果当时客户端不可用，则会丢失该消息。
QoS 1：消息传递至少 1 次。
QoS 2：消息仅传送一次。

rh
integer [ 0 .. 2 ]
Default: 0

指定订阅建立时服务端是否向客户端发送保留消息，
可选值 0：只要客户端订阅成功，服务端就发送保留消息。
可选值 1：客户端订阅成功且该订阅此前不存在，服务端才发送保留消息。毕竟有些时候客户端重新发起订阅可能只是为了改变一下 QoS，并不意味着它想再次接收保留消息。
可选值 2：即便客户订阅成功，服务端也不会发送保留消息。

rap
integer [ 0 .. 1 ]
Default: 0

缺省值为 0，这一选项用来指定服务端向客户端转发消息时是否要保留其中的 RETAIN 标识，注意这一选项不会影响保留消息中的 RETAIN 标识。因此当 Retain As Publish 选项被设置为 0 时，客户端直接依靠消息中的 RETAIN 标识来区分这是一个正常的转发消息还是一个保留消息，而不是去判断消息是否是自己订阅后收到的第一个消息（转发消息甚至可能会先于保留消息被发送，视不同 Broker 的具体实现而定）。

nl
integer [ 0 .. 1 ]
Default: 0

缺省值为0，
MQTT v3.1.1：如果设备订阅了自己发布消息的主题，那么将收到自己发布的所有消息。
MQTT v5：如果设备在订阅时将此选项设置为 1，那么服务端将不会向设备转发自己发布的消息

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Gateway Listeners

Delete the listener's authenticator

移除指定监听器的认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get the listener's authenticator

获取监听器的认证器配置。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Responses

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Create authenticator for listener

为指定监听器开启认证器以实现客户端认证的能力。

当某一监听器开启认证后，所有连接到该监听器的客户端会使用该认证器进行认证。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

是否使用 JWKS。

endpoint
required
string

JWKS 端点， 它是一个以 JWKS 格式返回服务端的公钥集的只读端点。

pool_size
integer >= 1
Default: 8

桥接远端服务时使用的连接池大小。

refresh_interval
integer
Default: 300

JWKS 刷新间隔。

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

认证机制。

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: []

需要验证的自定义声明列表，它是一个名称/值对列表。
值可以使用以下占位符：
- ${username}: 将在运行时被替换为客户端连接时使用的用户名
- ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
认证时将验证 JWT（取自 Password 字段）中 claims 的值是否与 verify_claims 中要求的相匹配。

from
string
Default: "password"
Enum: "username" "password"

指定客户端连接请求中 JWT 的位置；可选值： password、 username（分别对应于 MQTT 客户端 CONNECT 报文中的 Password 和 Username 字段）

enable
boolean
Default: true

设为 true 或 false 以启用或禁用此认证数据源。

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Update config of authenticator for listener

更新指定监听器的认证器配置，或停用/启用该认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

是否使用 JWKS。

endpoint
required
string

JWKS 端点， 它是一个以 JWKS 格式返回服务端的公钥集的只读端点。

pool_size
integer >= 1
Default: 8

桥接远端服务时使用的连接池大小。

refresh_interval
integer
Default: 300

JWKS 刷新间隔。

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

认证机制。

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: []

需要验证的自定义声明列表，它是一个名称/值对列表。
值可以使用以下占位符：
- ${username}: 将在运行时被替换为客户端连接时使用的用户名
- ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
认证时将验证 JWT（取自 Password 字段）中 claims 的值是否与 verify_claims 中要求的相匹配。

from
string
Default: "password"
Enum: "username" "password"

指定客户端连接请求中 JWT 的位置；可选值： password、 username（分别对应于 MQTT 客户端 CONNECT 报文中的 Password 和 Username 字段）

enable
boolean
Default: true

设为 true 或 false 以启用或禁用此认证数据源。

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

List all listeners

获取网关监听器列表。该接口会返回监听器所有的配置（包括该监听器上的认证器），同时也会返回该监听器在集群中运行的状态。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Add listener

为指定网关添加监听器。

注：对于某网关不支持的监听器类型，该接口会返回 400: BAD_REQUEST。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Request Body schema: application/json
One of
id
string

监听器 ID

type
string
Value: "dtls"

监听器类型

name
string

监听器名称

running
boolean

监听器运行状态

acceptors
integer
Default: 16

Acceptor 进程池大小。

object (gateway.udp_opts)
enable
boolean
Default: true

是否启用该监听器。

bind
string

监听器绑定的 IP 地址或端口。

string or integer
Default: 1024

监听器支持的最大连接数。

max_conn_rate
integer
Default: 1000

监听器支持的最大连接速率。

enable_authn
boolean
Default: true

配置 true （默认值）启用客户端进行身份认证。
配置 false 时，将不对客户端做任何认证。

mountpoint
string

发布或订阅时，在所有主题前增加前缀字符串。
当消息投递给订阅者时，前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。
例如，如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t，
则客户端实际上订阅了 some_tenant/t 主题。
类似地，如果另一个客户端 B（连接到与客户端 A 相同的侦听器）向主题 t 发送消息，
则该消息被路由到所有订阅了 some_tenant/t 的客户端，因此客户端 A 将收到该消息，带有 主题名称t。 设置为 "" 以禁用该功能。
挂载点字符串中可用的变量：

- ${clientid}：clientid

- ${username}：用户名

access_rules
Array of strings
Default: []

配置监听器的访问控制规则。
见：https://github.com/emqtt/esockd#allowdeny

object (gateway.dtls_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Delete listener

删除指定监听器。被删除的监听器下所有已连接的客户端都会离线。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get listener config

获取指定网关监听器的配置。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Responses

Response samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Update listener config

更新某网关监听器的配置。被更新的监听器会执行重启，所有已连接到该监听器上的客户端都会被断开。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Request Body schema: application/json
One of
id
string

监听器 ID

type
string
Value: "dtls"

监听器类型

name
string

监听器名称

running
boolean

监听器运行状态

acceptors
integer
Default: 16

Acceptor 进程池大小。

object (gateway.udp_opts)
enable
boolean
Default: true

是否启用该监听器。

bind
string

监听器绑定的 IP 地址或端口。

string or integer
Default: 1024

监听器支持的最大连接数。

max_conn_rate
integer
Default: 1000

监听器支持的最大连接速率。

enable_authn
boolean
Default: true

配置 true （默认值）启用客户端进行身份认证。
配置 false 时，将不对客户端做任何认证。

mountpoint
string

发布或订阅时，在所有主题前增加前缀字符串。
当消息投递给订阅者时，前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。
例如，如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t，
则客户端实际上订阅了 some_tenant/t 主题。
类似地，如果另一个客户端 B（连接到与客户端 A 相同的侦听器）向主题 t 发送消息，
则该消息被路由到所有订阅了 some_tenant/t 的客户端，因此客户端 A 将收到该消息，带有 主题名称t。 设置为 "" 以禁用该功能。
挂载点字符串中可用的变量：

- ${clientid}：clientid

- ${username}：用户名

access_rules
Array of strings
Default: []

配置监听器的访问控制规则。
见：https://github.com/emqtt/esockd#allowdeny

object (gateway.dtls_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Delete user

删除用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

uid
required
string

用户 ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get user info

获取用户信息（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

uid
required
string

用户 ID

Responses

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Update user info

更新用户信息（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

uid
required
string

用户 ID

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

List authenticator's users

获取用户列表（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Add user for an authenticator

添加用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string

监听器 ID

Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Configs

Get the sub-configurations under *sys_topics*

Get the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "sys_msg_interval": "1m",
  • "sys_heartbeat_interval": "30s",
  • "sys_event_messages": {
    }
}

Update the sub-configurations under *sys_topics*

Update the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
string or string
Default: "1m"

发送 $SYS 主题的间隔时间。

string or string
Default: "30s"

发送心跳系统消息的间隔时间，它包括：
- $SYS/brokers/<node>/uptime
- $SYS/brokers/<node>/datetime

object (broker.event_names)

Responses

Request samples

Content type
application/json
{
  • "sys_msg_interval": "1m",
  • "sys_heartbeat_interval": "30s",
  • "sys_event_messages": {
    }
}

Response samples

Content type
application/json
{
  • "sys_msg_interval": "1m",
  • "sys_heartbeat_interval": "30s",
  • "sys_event_messages": {
    }
}

Get the sub-configurations under *sysmon*

Get the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "vm": {
    },
  • "os": {
    }
}

Update the sub-configurations under *sysmon*

Update the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (broker.sysmon_vm)
object (broker.sysmon_os)

Responses

Request samples

Content type
application/json
{
  • "vm": {
    },
  • "os": {
    }
}

Response samples

Content type
application/json
{
  • "vm": {
    },
  • "os": {
    }
}

获取全局默认 zone 的配置

获取全局默认 zone 的配置

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "mqtt": {
    },
  • "flapping_detect": {
    },
  • "force_shutdown": {
    },
  • "force_gc": {
    }
}

更新全局默认 zone 的配置

更新全局默认 zone 的配置

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (broker.mqtt)
object (broker.flapping_detect)
object (broker.force_shutdown)
object (broker.force_gc)

Responses

Request samples

Content type
application/json
{
  • "mqtt": {
    },
  • "flapping_detect": {
    },
  • "force_shutdown": {
    },
  • "force_gc": {
    }
}

Response samples

Content type
application/json
{
  • "mqtt": {
    },
  • "flapping_detect": {
    },
  • "force_shutdown": {
    },
  • "force_gc": {
    }
}

Get the sub-configurations under *alarm*

Get the sub-configurations under alarm

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "size_limit": 1000,
  • "validity_period": "24h"
}

Update the sub-configurations under *alarm*

Update the sub-configurations under alarm

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
actions
Array of strings
Default: ["log","publish"]

警报激活时触发的动作。
目前，支持以下操作：log 和 publish.
log 将告警写入日志 (控制台或者文件).
publish 将告警作为 MQTT 消息发布到系统主题:
$SYS/brokers/emqx@xx.xx.xx.x/alarms/activate and
$SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivate

size_limit
integer [ 1 .. 3000 ]
Default: 1000

要保留为历史记录的已停用报警的最大总数。当超过此限制时，将删除最旧的停用报警，以限制总数。

validity_period
string
Default: "24h"

停用报警的保留时间。报警在停用时不会立即删除，而是在保留时间之后删除。

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "size_limit": 1000,
  • "validity_period": "24h"
}

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "size_limit": 1000,
  • "validity_period": "24h"
}

Get the sub-configurations under *dashboard*

Get the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "listeners": {
    },
  • "token_expired_time": "12m",
  • "cors": false
}

Update the sub-configurations under *dashboard*

Update the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (dashboard.listeners)
token_expired_time
string
Default: "60m"

JWT token 过期时间。默认设置为 60 分钟。

cors
boolean
Default: false

支持跨域资源共享(CORS)，
允许服务器指示任何来源(域名、协议或端口)，除了本服务器之外的任何浏览器应允许加载资源。

Responses

Request samples

Content type
application/json
{
  • "listeners": {
    },
  • "token_expired_time": "12m",
  • "cors": false
}

Response samples

Content type
application/json
{
  • "listeners": {
    },
  • "token_expired_time": "12m",
  • "cors": false
}

重置（使用 `conf_path` 参数）指定的配置路径下的值<br/><br/>- 若指定路径的配

重置（使用 conf_path 参数）指定的配置路径下的值

- 若指定路径的配置有默认值，则使用默认值；
- 若指定路径的配置没有默认值，则返回 HTTP 状态码 400。

Authorizations:
basicAuthbearerAuth
path Parameters
rootname
required
string
Enum: "log" "sysmon" "sys_topics" "alarm" "dashboard"
Example: sysmon
query Parameters
conf_path
string
Example: conf_path=os.sysmem_high_watermark

The config path separated by '.' character

Responses

Response samples

Content type
application/json
{
  • "code": "NO_DEFAULT_VALUE",
  • "message": "string"
}

Get all the configurations of the specified keys,

Get all the configurations of the specified keys, including hot and non-hot updatable items.

Authorizations:
basicAuthbearerAuth
query Parameters
key
string
Enum: "alarm" "api_key" "authentication" "authorization" "auto_subscribe" "bridges" "cluster" "conn_congestion" "crl_cache" "dashboard" "delayed" "exhook" "flapping_detect" "force_gc" "force_shutdown" "gateway" "limiter" "listeners" "log" "mqtt" "node" "opentelemetry" "overload_protection" "prometheus" "psk_authentication" "retainer" "rewrite" "rpc" "rule_engine" "slow_subs" "sys_topics" "sysmon" "telemetry" "topic_metrics"
Example: key=sysmon
node
string

指定节点名称。如果未指定，则返回收到这个HTTP请求的节点的配置。

Responses

Response samples

Content type
No sample

Update the configurations of the specified keys.

Update the configurations of the specified keys.

Authorizations:
basicAuthbearerAuth
query Parameters
mode
string
Default: "merge"
Enum: "replace" "merge"
Request Body schema: text/plain
string

Responses

Response samples

Content type
application/json
{
  • "code": "UPDATE_FAILED",
  • "message": "string"
}

Get the sub-configurations under *log*

Get the sub-configurations under log

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "console": {
    },
  • "file": {
    }
}

Update the sub-configurations under *log*

Update the sub-configurations under log

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx_conf_schema.console_handler)
object or emqx_conf_schema.log_file_handler (object)
Default: {"level":"warning"}

输出到文件的日志处理进程列表

Responses

Request samples

Content type
application/json
{
  • "console": {
    },
  • "file": {
    }
}

Response samples

Content type
application/json
{
  • "console": {
    },
  • "file": {
    }
}

Clients

Kick out a batch of client by client IDs

Kick out a batch of client by client IDs

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "emqx_clienid_985bb09d",
  • "emqx_clientid_211cc01c"
]

清除指定客户端的授权缓存

清除指定客户端的授权缓存

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

获取指定客户端的授权缓存

获取指定客户端的授权缓存

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "access": "publish",
  • "result": "allow",
  • "topic": "testtopic/1",
  • "updated_time": 1687850712989
}

踢出指定客户端

踢出指定客户端

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

获取指定客户端的详细信息

获取指定客户端的详细信息

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "awaiting_rel_cnt": 0,
  • "awaiting_rel_max": 0,
  • "clean_start": true,
  • "clientid": "string",
  • "connected": true,
  • "connected_at": 1640995200000,
  • "created_at": 1640995200000,
  • "disconnected_at": 1640995200000,
  • "expiry_interval": 0,
  • "heap_size": 0,
  • "inflight_cnt": 0,
  • "inflight_max": 0,
  • "ip_address": "string",
  • "is_bridge": true,
  • "keepalive": 0,
  • "mailbox_len": 0,
  • "mqueue_dropped": 0,
  • "mqueue_len": 0,
  • "mqueue_max": 0,
  • "node": "string",
  • "port": 0,
  • "proto_name": "string",
  • "proto_ver": 0,
  • "recv_cnt": 0,
  • "recv_msg": 0,
  • "recv_msg.dropped": 0,
  • "recv_msg.dropped.await_pubrel_timeout": 0,
  • "recv_msg.qos0": 0,
  • "recv_msg.qos1": 0,
  • "recv_msg.qos2": 0,
  • "recv_oct": 0,
  • "recv_pkt": 0,
  • "reductions": 0,
  • "send_cnt": 0,
  • "send_msg": 0,
  • "send_msg.dropped": 0,
  • "send_msg.dropped.expired": 0,
  • "send_msg.dropped.queue_full": 0,
  • "send_msg.dropped.too_large": 0,
  • "send_msg.qos0": 0,
  • "send_msg.qos1": 0,
  • "send_msg.qos2": 0,
  • "send_oct": 0,
  • "send_pkt": 0,
  • "subscriptions_cnt": 0,
  • "subscriptions_max": 0,
  • "username": "string",
  • "mountpoint": "string"
}

批量取消订阅

批量取消订阅

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
topic
string

Topic

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

批量订阅

批量订阅

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
topic
required
string

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

订阅

订阅

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
topic
required
string

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/#",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0
}

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "topic": "testtopic/1",
  • "clientid": "emqx_clientid_xx128cdhfc",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0
}

取消订阅

取消订阅

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
topic
string

Topic

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/#"
}

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

获取指定客户端的订阅信息

获取指定客户端的订阅信息

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

列出客户端

列出客户端

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

node
string
Example: node=emqx@127.0.0.1

Node name

username
string

User name

ip_address
string
Example: ip_address=127.0.0.1

Client's IP address

conn_state
string
Enum: "connected" "idle" "disconnected"

The current connection status of the client, the possible values are connected,idle,disconnected

clean_start
boolean

Whether the client uses a new session

proto_ver
string

Client protocol version

like_clientid
string

Fuzzy search clientid as substring

like_username
string

Fuzzy search username as substring

integer or string

Search client session creation time by greater than or equal method, rfc3339 or timestamp(millisecond)

integer or string

Search client session creation time by less than or equal method, rfc3339 or timestamp(millisecond)

integer or string

Search client connection creation time by greater than or equal method, rfc3339 or timestamp(epoch millisecond)

integer or string

Search client connection creation time by less than or equal method, rfc3339 or timestamp(millisecond)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Telemetry

获取遥测状态

获取遥测状态

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false
}

更新遥测状态

更新遥测状态

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: true

启用遥测

Responses

Request samples

Content type
application/json
{
  • "enable": false
}

Response samples

Content type
application/json
{
  • "enable": false
}

获取遥测数据

获取遥测数据

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "emqx_version": "5.0.0-beta.3-32d1547c",
  • "license": {
    },
  • "os_name": "Linux",
  • "os_version": "20.04",
  • "otp_version": "24",
  • "up_time": 20220113,
  • "uuid": "AAAAAAAA-BBBB-CCCC-2022-DDDDEEEEFFF",
  • "nodes_uuid": [
    ],
  • "active_plugins": [
    ],
  • "active_modules": [
    ],
  • "num_clients": 20220113,
  • "messages_received": 2022,
  • "messages_sent": 2022
}

Cluster

获取集群信息

获取集群信息

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "nodes": [
    ],
  • "self": "string"
}

强制节点离开集群

强制节点离开集群

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx2@127.0.0.1

node name

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

邀请节点加入集群

邀请节点加入集群

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx2@127.0.0.1

node name

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get RLOG cluster topology: connections between cor

Get RLOG cluster topology: connections between core and replicant nodes.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Gateway Clients

Kick out client

踢出指定客户端

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string

网关名称

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get client info

获取客户端信息

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string

网关名称

Responses

Response samples

Content type
application/json
Example
{
  • "awaiting_rel_cnt": 0,
  • "recv_cnt": 1,
  • "recv_pkt": 1,
  • "recv_msg": 0,
  • "connected": true,
  • "awaiting_rel_max": "infinity",
  • "expiry_interval": 0,
  • "is_bridge": false,
  • "created_at": "2021-12-07T10:44:02.721+08:00",
  • "inflight_cnt": 0,
  • "mqueue_len": 0,
  • "ip_address": "127.0.0.1",
  • "reductions": 72022,
  • "proto_name": "STOMP",
  • "mqueue_dropped": 0,
  • "proto_ver": "1.0",
  • "username": "guest",
  • "subscriptions_cnt": 0,
  • "send_pkt": 1,
  • "connected_at": "2021-12-07T10:44:02.721+08:00",
  • "clientid": "MzAyMzEzNTUwNzk1NDA1MzYyMzIwNzUxNjQwMTY1NzQ0NjE",
  • "recv_oct": 56,
  • "send_oct": 61,
  • "disconnected_at": null,
  • "keepalive": 0,
  • "inflight_max": "infinity",
  • "clean_start": true,
  • "subscriptions_max": "infinity",
  • "mailbox_len": 0,
  • "node": "emqx@127.0.0.1",
  • "send_msg": 0,
  • "mqueue_max": "infinity",
  • "heap_size": 4185,
  • "port": 50675,
  • "send_cnt": 1
}

List client's subscription

获取某客户端的主题订阅列表

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string

网关名称

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Add subscription for client

为某客户端新增订阅关系

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string

网关名称

Request Body schema: application/json
topic
string

主题过滤器或主题名称

qos
integer

QoS 等级，枚举：0，1，2

nl
integer

No Local 选项，枚举：0，1

rap
integer

Retain as Published 选项，枚举：0，1

rh
integer

Retain Handling 选项，枚举：0，1，2

object (emqx_gateway_api_clients.extra_sub_props)

Responses

Request samples

Content type
application/json
Example
{
  • "nl": 0,
  • "qos": 1,
  • "rap": 0,
  • "rh": 0,
  • "topic": "test/topic"
}

Response samples

Content type
application/json
Example
{
  • "nl": 0,
  • "qos": 1,
  • "rap": 0,
  • "rh": 0,
  • "topic": "test/topic"
}

Delete client's subscription

为某客户端删除某订阅关系

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

主题过滤器或主题名称

clientid
required
string

客户端 ID

name
required
string

网关名称

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List gateway's clients

获取指定网关的客户端列表

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string

网关名称

query Parameters
node
string

匹配客户端的节点名称

clientid
string

匹配客户端 ID

username
string

匹配客户端 Username

ip_address
string

匹配客户端 IP 地址

conn_state
string

匹配客户端连接状态

proto_ver
string

匹配客户端协议版本

clean_start
boolean

匹配客户端 clean_start 标记

like_clientid
string

子串匹配客户端 ID

like_username
string

子串匹配 客户端 Username

integer or string

匹配会话创建时间大于等于指定值的客户端

integer or string

匹配会话创建时间小于等于指定值的客户端

integer or string

匹配连接创建时间大于等于指定值的客户端

integer or string

匹配连接创建时间小于等于指定值的客户端

endpoint_name
string

匹配 LwM2M 客户端 Endpoint Name

like_endpoint_name
string

子串匹配 LwM2M 客户端 Endpoint Name

gte_lifetime
string

匹配心跳时间大于等于指定值的 LwM2M 客户端

lte_lifetime
string

匹配心跳时间小于等于指定值的 LwM2M 客户端

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Publish

Publish a batch of messages

批量发布一组消息。

可能的 HTTP 状态码如下：

200: 所有的消息都被成功发送到至少一个订阅。

202: 至少有一个消息没有匹配到任何订阅。

400: 至少有一个消息编码错误，如非法主题，或 QoS 超出范围等。

503: 至少有一个小因为服务重启的原因导致转发失败。


请求的 Body 或者 Body 中包含的某个消息无法通过 API 规范的类型检查时，HTTP 响应的消息与发布单个消息的 API
/publish 是一样的。
如果所有的消息都是合法的，那么 HTTP 返回的内容是一个 JSON 数组，每个元素代表了该消息转发的状态。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT 消息体的编码方式，可以是 base64 或 plain。当设置为 base64 时，消息在发布前会先被解码。

topic
required
string

主题名称

qos
integer [ 0 .. 2 ]
Default: 0

MQTT 消息的 QoS

clientid
string
Deprecated
payload
required
string

MQTT 消息体。

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

布尔型字段，用于表示该消息是否保留消息。

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Publish a message

发布一个消息。

可能的 HTTP 状态码如下：

200: 消息被成功发送到至少一个订阅。

202: 没有匹配到任何订阅。

400: 消息编码错误，如非法主题，或 QoS 超出范围等。

503: 服务重启等过程中导致转发失败。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT 消息体的编码方式，可以是 base64 或 plain。当设置为 base64 时，消息在发布前会先被解码。

topic
required
string

主题名称

qos
integer [ 0 .. 2 ]
Default: 0

MQTT 消息的 QoS

clientid
string
Deprecated
payload
required
string

MQTT 消息体。

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

布尔型字段，用于表示该消息是否保留消息。

Responses

Request samples

Content type
application/json
{
  • "payload_encoding": "plain",
  • "topic": "api/example/topic",
  • "qos": 0,
  • "clientid": "string",
  • "payload": "hello emqx api",
  • "properties": {
    },
  • "retain": false
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Rules

Test a rule

测试一个规则

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
emqx_rule_api_schema.ctx_delivery_dropped (object) or emqx_rule_api_schema.ctx_bridge_mqtt (object) or emqx_rule_api_schema.ctx_check_authz_complete (object) or emqx_rule_api_schema.ctx_connack (object) or emqx_rule_api_schema.ctx_disconnected (object) or emqx_rule_api_schema.ctx_connected (object) or emqx_rule_api_schema.ctx_dropped (object) or emqx_rule_api_schema.ctx_acked (object) or emqx_rule_api_schema.ctx_delivered (object) or emqx_rule_api_schema.ctx_unsub (object) or emqx_rule_api_schema.ctx_sub (object) or emqx_rule_api_schema.ctx_pub (object)
Default: {}

测试事件的上下文

sql
required
string

测试的 SQL

Responses

Request samples

Content type
application/json
{
  • "context": { },
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List rules

列出所有规则

Authorizations:
basicAuthbearerAuth
query Parameters
enable
boolean

根据规则是否开启条件过滤

from
string

根据规则来源 Topic 过滤, 需要完全匹配

like_id
string

根据规则 id 过滤, 使用子串模糊匹配

like_from
string

根据规则来源 Topic 过滤, 使用子串模糊匹配

like_description
string

根据规则描述过滤, 使用子串模糊匹配

match_from
string

根据规则来源 Topic 过滤, 使用 MQTT Topic 匹配

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a rule

通过指定 ID 创建规则

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
string
Default: ""

规则名字

sql
required
string

用于处理消息的 SQL 。
示例：SELECT * FROM "test/topic" WHERE payload.x = 1

Array of rule_engine.user_provided_function (object) or rule_engine.builtin_action_console (object) or rule_engine.builtin_action_republish (object) or strings
Default: []

规则的动作列表。
动作可以是指向 EMQX bridge 的引用，也可以是一个指向函数的对象。
我们支持一些内置函数，如“republish”和“console”，我们还支持用户提供的函数，它的格式为：“{module}:{function}”。
列表中的动作按顺序执行。这意味着如果其中一个动作执行缓慢，则以下所有动作都不会被执行直到它返回。
如果其中一个动作崩溃，在它之后的所有动作仍然会被按照原始顺序执行。
如果运行动作时出现任何错误，则会出现错误消息，并且相应的计数器会增加。

enable
boolean
Default: true

启用或禁用规则引擎

description
string
Default: ""

规则的描述

metadata
object

规则的元数据，不要手动修改

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Get rule metrics

通过给定的 Id 获得规则的指标数据

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

List rule events

列出所有能被规则使用的事件

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "event": "$events/client_connected",
  • "title": "some title",
  • "description": "some desc",
  • "columns": { },
  • "test_columns": { },
  • "sql_example": "string"
}

Reset rule metrics

重置规则计数

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Delete rule

通过 ID 删除集群里所有节点上的规则

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Get rule

通过 ID 查询规则

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Update rule

通过 ID 更新集群里所有节点上的规则

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
name
string
Default: ""

规则名字

sql
required
string

用于处理消息的 SQL 。
示例：SELECT * FROM "test/topic" WHERE payload.x = 1

Array of rule_engine.user_provided_function (object) or rule_engine.builtin_action_console (object) or rule_engine.builtin_action_republish (object) or strings
Default: []

规则的动作列表。
动作可以是指向 EMQX bridge 的引用，也可以是一个指向函数的对象。
我们支持一些内置函数，如“republish”和“console”，我们还支持用户提供的函数，它的格式为：“{module}:{function}”。
列表中的动作按顺序执行。这意味着如果其中一个动作执行缓慢，则以下所有动作都不会被执行直到它返回。
如果其中一个动作崩溃，在它之后的所有动作仍然会被按照原始顺序执行。
如果运行动作时出现任何错误，则会出现错误消息，并且相应的计数器会增加。

enable
boolean
Default: true

启用或禁用规则引擎

description
string
Default: ""

规则的描述

metadata
object

规则的元数据，不要手动修改

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

获取规则引擎配置。

获取规则引擎配置。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

更新规则引擎配置。

更新规则引擎配置。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
ignore_sys_message
boolean
Default: true

当设置为“true”（默认）时，规则引擎将忽略发布到 $SYS 主题的消息。

jq_function_default_timeout
string
Default: "10s"

规则引擎内建函数 jq 默认时间限制

Responses

Request samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

Response samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

Gateways

Enable or disable gateway

更新指定网关的基础配置、和启用的状态。

注：认证、和监听器的配置更新需参考对应的 API 接口。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

enable
required
boolean
Example: true

是否开启此网关

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List all gateways

该接口会返回指定或所有网关的概览状态，
包括当前状态、连接数、监听器状态等。

Authorizations:
basicAuthbearerAuth
query Parameters
status
string
Enum: "running" "stopped" "unloaded"
Example: status=running

通过网关状态筛选

可选值为 running、stopped、unloaded

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get gateway

获取网关配置详情

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Responses

Response samples

Content type
application/json
Example
{
  • "connection_required": false,
  • "enable": true,
  • "enable_stats": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "listeners": [
    ],
  • "mountpoint": "coap/",
  • "name": "coap",
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Load or update the gateway confs

更新指定网关的基础配置、和启用的状态。

注：认证、和监听器的配置更新需参考对应的 API 接口。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Request Body schema: application/json
One of
required
object (emqx_exproto_schema.exproto_grpc_server)
required
object (emqx_exproto_schema.exproto_grpc_handler)
mountpoint
string
Default: ""

发布或订阅时，在所有主题前增加前缀字符串。
当消息投递给订阅者时，前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。
例如，如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t，
则客户端实际上订阅了 some_tenant/t 主题。
类似地，如果另一个客户端 B（连接到与客户端 A 相同的侦听器）向主题 t 发送消息，
则该消息被路由到所有订阅了 some_tenant/t 的客户端，因此客户端 A 将收到该消息，带有 主题名称t。 设置为 "" 以禁用该功能。
挂载点字符串中可用的变量：

- ${clientid}：clientid

- ${username}：用户名

enable
boolean
Default: true

是否启用该网关

enable_stats
boolean
Default: true

是否开启客户端统计

idle_timeout
string
Default: "30s"

客户端连接过程的空闲时间。该配置用于：
1. 一个新创建的客户端进程如果在该时间间隔内没有收到任何客户端请求，将被直接关闭。
2. 一个正在运行的客户进程如果在这段时间后没有收到任何客户请求，将进入休眠状态以节省资源。

object (gateway.clientinfo_override)

Responses

Request samples

Content type
application/json
Example
{
  • "connection_required": false,
  • "enable": true,
  • "enable_stats": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "mountpoint": "coap2/",
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Trace

获取 trace 日志文件的元数据, 例如文件大小和修改时间

获取 trace 日志文件的元数据, 例如文件大小和修改时间

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
[
  • {
    }
]

下载指定 trace 的日志文件

下载指定 trace 的日志文件

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

query Parameters
node
string
Example: node=emqx@127.0.0.1

指定从哪个节点获取 trace 文件内容。

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

清除所有 trace

清除所有 trace

Authorizations:
basicAuthbearerAuth

Responses

列出所有 trace

列出所有 trace

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

创建 trace

创建 trace

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
required
string

Unique name of the trace. Only ascii letters in a-z, A-Z, 0-9 and underscore '_' are allowed.

type
required
string
Enum: "clientid" "topic" "ip_address"

过滤器类型

topic
string

如果过滤器类型为 'topic' 则该字段可以指定用于匹配的 MQTT 主题或主题过滤器。

clientid
string

如果过滤器类型为 'clientid' 则该字段可以指定用于匹配的 MQTT 客户端 ID。

ip_address
string

如果过滤器类型为 'ip_address' 则该字段可以指定用于匹配的客户端 IP 地址。

payload_encode
string
Default: "text"
Enum: "hex" "text" "hidden"

Determine the format of the payload format in the trace file.

text: Text-based protocol or plain text protocol.
It is recommended when payload is JSON encoded.

hex: Binary hexadecimal encode.It is recommended when payload is a custom binary protocol.

hidden: payload is obfuscated as ******

integer or string

时间戳格式，rfc3339 或者 epoch second

integer or string

时间戳格式，rfc3339 或者 epoch second

Responses

Request samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00"
}

Response samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "status": "running",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "log_size": [
    ]
}

查看 trace

查看 trace

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

query Parameters
bytes
integer [ 0 .. 2147483647 ]
Default: 1000

单个 HTTP 相应中包含 trace 日志的字节数。

position
integer
Default: 0

指定从该偏移量开始读取指定的 trace 日志文件。

node
string
Example: node=emqx@127.0.0.1

指定从哪个节点获取 trace 文件内容。

Responses

Response samples

Content type
application/json
{
  • "items": "TEXT-LOG-ITEMS",
  • "meta": {
    }
}

删除指定的 trace

删除指定的 trace

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

停止指定的 trace

停止指定的 trace

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "status": "running",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "log_size": [
    ]
}

Dashboard

Dashboard 用户列表

Dashboard 用户列表

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

创建 Dashboard 用户

创建 Dashboard 用户

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
username
string <= 100 characters

Dashboard 用户名

password
string <= 100 characters

Dashboard 密码

description
string

Dashboard 用户描述

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "public",
  • "description": "administrator"
}

Response samples

Content type
application/json
{
  • "username": "admin",
  • "description": "administrator"
}

Dashboard authentication

获取 Dashboard 认证 Token。

Request Body schema: application/json
username
string <= 100 characters

Dashboard 用户名

password
string <= 100 characters

Dashboard 密码

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "public"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "version": "5.0.0",
  • "license": {
    }
}

删除 Dashboard 用户

删除 Dashboard 用户

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard 用户名

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

更新 Dashboard 用户描述

更新 Dashboard 用户描述

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard 用户名

Request Body schema: application/json
description
string

Dashboard 用户描述

Responses

Request samples

Content type
application/json
{
  • "description": "administrator"
}

Response samples

Content type
application/json
{
  • "username": "admin",
  • "description": "administrator"
}

更改 Dashboard 用户密码

更改 Dashboard 用户密码

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard 用户名

Request Body schema: application/json
old_pwd
string

旧密码

new_pwd
string

新密码

Responses

Request samples

Content type
application/json
{
  • "old_pwd": "string",
  • "new_pwd": "string"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get the schema JSON of the specified name. NOTE: o

Get the schema JSON of the specified name. NOTE: only intended for EMQX Dashboard.

path Parameters
name
required
string
Enum: "hotconf" "bridges"

Responses

Response samples

Content type
application/json
"string"

Dashboard 用户登出

Dashboard 用户登出

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
username
string <= 100 characters

Dashboard 用户名

Responses

Request samples

Content type
application/json
{
  • "username": "admin"
}

Response samples

Content type
application/json
{
  • "code": "BAD_USERNAME_OR_PWD",
  • "message": "string"
}

Listeners

列出所有节点上的指定类型的监听器

列出所有节点上的指定类型的监听器

Authorizations:
basicAuthbearerAuth
query Parameters
type
string
Enum: "tcp" "ssl" "ws" "wss" "quic"
Example: type=tcp

Listener type

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

在所有节点上创建指定的监听器

在所有节点上创建指定的监听器

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "quic"

Listener type

running
boolean

Listener status

name
required
string

Listener name

current_connections
integer >= 0

Current connections

ciphers
Array of strings
Default: ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256","TLS_CHACHA20_POLY1305_SHA256"]

此配置保存由逗号分隔的 TLS 密码套件名称，或作为字符串数组。例如
"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"或
["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]。


密码（及其顺序）定义了客户端和服务器通过网络连接加密信息的方式。
选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

名称应为 OpenSSL 字符串格式（而不是 RFC 格式）。
EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式

注意：某些密码套件仅与特定的 TLS 版本兼容（'tlsv1.1'、'tlsv1.2'或'tlsv1.3'）。
不兼容的密码套件将被自动删除。

例如，如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。



注：PSK 的 Ciphers 不支持 tlsv1.3

如果打算使用PSK密码套件，tlsv1.3。应在ssl.versions中禁用。



PSK 密码套件：
"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"


注：QUIC 监听器不支持 tlsv1.3 的 ciphers

object (broker.listener_quic_ssl_opts)
enable
boolean
Default: true

启停监听器。

bind
required
string
Default: 14567

监听套接字的 IP 地址和端口。

acceptors
integer >= 1
Default: 16

监听器接收池的大小。

integer or string
Default: "infinity"

监听器允许的最大并发连接数。

mountpoint
string
Default: ""

发布或订阅时，请在所有主题前面加上 mountpoint 字符串。

将消息传递给订阅者时，将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

例如，如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant'，那么客户端实际上订阅了主题'some_tenant/t'。

类似地，如果另一个客户端B（与客户端A连接到同一个侦听器）向主题 't' 发送消息，该消息将路由到所有订阅了'some_租户/t'的客户端，因此客户端 A 将接收主题名为't'的消息


设置为"" 以禁用该功能


mountpoint 字符串中的变量：
- ${clientid}: clientid
- ${username}: username

enable_authn
string
Default: true
Enum: true false "quick_deny_anonymous"

配置 true （默认值）启用客户端进行身份认证，通过检查认配置的认认证器链来决定是否允许接入。
配置 false 时，将不对客户端做任何认证，任何客户端，不论是不是携带用户名等认证信息，都可以接入。
配置 quick_deny_anonymous 时，行为跟 true 类似，但是会对匿名
客户直接拒绝，不做使用任何认证器对客户端进行身份检查。

max_conn_rate
string

Maximum connection rate.

This is used to limit the connection rate for this listener,
once the limit is reached, new connections will be deferred or refused

messages_rate
string

Messages publish rate.

This is used to limit the inbound message numbers for each client connected to this listener,
once the limit is reached, the restricted client will slow down and even be hung for a while.

bytes_rate
string

Data publish rate.

This is used to limit the inbound bytes rate for each client connected to this listener,
once the limit is reached, the restricted client will slow down and even be hung for a while.

Responses

Request samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "name": "demo",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp"
}

Response samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "id": "tcp:demo",
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp"
}

在所有节点上停止指定ID的监听器

在所有节点上停止指定ID的监听器

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

在所有节点上启动指定ID的监听器

在所有节点上启动指定ID的监听器

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

在所有节点上重启指定ID的监听器

在所有节点上重启指定ID的监听器

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

删除所有节点上指定ID的监听器

删除所有节点上指定ID的监听器

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_LISTENER_ID",
  • "message": "string"
}

获取指定ID的监听器

获取指定ID的监听器

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "id": "tcp:demo",
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp"
}

为集群中所有的节点更新指定ID的监听器

为集群中所有的节点更新指定ID的监听器

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Request Body schema: application/json
One of
type
required
string
Value: "wss"

Listener type

running
boolean

Listener status

id
required
string

Listener id

current_connections
integer >= 0

Current connections

bind
string
Default: 8084

监听套接字的 IP 地址和端口。

enable
boolean
Default: true

启停监听器。

acceptors
integer >= 1
Default: 16

监听器接收池的大小。

integer or string
Default: "infinity"

监听器允许的最大并发连接数。

mountpoint
string
Default: ""

发布或订阅时，请在所有主题前面加上 mountpoint 字符串。

将消息传递给订阅者时，将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

例如，如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant'，那么客户端实际上订阅了主题'some_tenant/t'。

类似地，如果另一个客户端B（与客户端A连接到同一个侦听器）向主题 't' 发送消息，该消息将路由到所有订阅了'some_租户/t'的客户端，因此客户端 A 将接收主题名为't'的消息


设置为"" 以禁用该功能


mountpoint 字符串中的变量：
- ${clientid}: clientid
- ${username}: username

enable_authn
string
Default: true
Enum: true false "quick_deny_anonymous"

配置 true （默认值）启用客户端进行身份认证，通过检查认配置的认认证器链来决定是否允许接入。
配置 false 时，将不对客户端做任何认证，任何客户端，不论是不是携带用户名等认证信息，都可以接入。
配置 quick_deny_anonymous 时，行为跟 true 类似，但是会对匿名
客户直接拒绝，不做使用任何认证器对客户端进行身份检查。

max_conn_rate
string

Maximum connection rate.

This is used to limit the connection rate for this listener,
once the limit is reached, new connections will be deferred or refused

messages_rate
string

Messages publish rate.

This is used to limit the inbound message numbers for each client connected to this listener,
once the limit is reached, the restricted client will slow down and even be hung for a while.

bytes_rate
string

Data publish rate.

This is used to limit the inbound bytes rate for each client connected to this listener,
once the limit is reached, the restricted client will slow down and even be hung for a while.

access_rules
Array of strings
Default: ["allow all"]

此监听器的访问控制规则。

proxy_protocol
boolean
Default: false

如果EMQX集群部署在 HAProxy 或 Nginx 之后，请启用代理协议 V1/2

详情见: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

代理协议超时。如果在超时时间内未收到代理协议数据包，EMQX将关闭TCP连接。

Array of authn.scram (object) or authn.jwt_jwks (object) or authn.jwt_public_key (object) or authn.jwt_hmac (object) or authn.http_post (object) or authn.http_get (object) or authn.redis_sentinel (object) or authn.redis_cluster (object) or authn.redis_single (object) or authn.mongo_sharded (object) or authn.mongo_rs (object) or authn.mongo_single (object) or authn.postgresql (object) or authn.mysql (object) or authn.builtin_db (object)
Default: []

Default authentication configs for all MQTT listeners.

For per-listener overrides see authentication in listener configs

This option can be configured with:


  • []: The default value, it allows ALL logins

  • one: For example {enable:true,backend:"built_in_database",mechanism="password_based"}

  • chain: An array of structs.



When a chain is configured, the login credentials are checked against the backends per the configured order, until an 'allow' or 'deny' decision can be made.

If there is no decision after a full chain exhaustion, the login is rejected.

object (broker.tcp_opts)
object (broker.listener_wss_opts)
object (broker.ws_opts)

Responses

Request samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "id": "tcp:demo",
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp"
}

Response samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "id": "tcp:demo",
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp"
}

列出所有节点上的监听器状态。按监听器类型分组

列出所有节点上的监听器状态。按监听器类型分组

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Gateway Authentication

Delete gateway authenticator

删除指定网关的认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get authenticator configuration

获取指定网关认证器的配置
当网关或认证未启用时，返回 404。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Responses

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Create authenticator for gateway

为指定网关开启认证器实现客户端认证的功能。

当未配置认证器或关闭认证器时，则认为允许所有客户端的连接。

注：在网关中仅支持添加一个认证器，而不是像 MQTT 一样允许配置多个认证器构成认证链。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

是否使用 JWKS。

endpoint
required
string

JWKS 端点， 它是一个以 JWKS 格式返回服务端的公钥集的只读端点。

pool_size
integer >= 1
Default: 8

桥接远端服务时使用的连接池大小。

refresh_interval
integer
Default: 300

JWKS 刷新间隔。

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

认证机制。

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: []

需要验证的自定义声明列表，它是一个名称/值对列表。
值可以使用以下占位符：
- ${username}: 将在运行时被替换为客户端连接时使用的用户名
- ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
认证时将验证 JWT（取自 Password 字段）中 claims 的值是否与 verify_claims 中要求的相匹配。

from
string
Default: "password"
Enum: "username" "password"

指定客户端连接请求中 JWT 的位置；可选值： password、 username（分别对应于 MQTT 客户端 CONNECT 报文中的 Password 和 Username 字段）

enable
boolean
Default: true

设为 true 或 false 以启用或禁用此认证数据源。

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Update authenticator configuration

更新指定网关认证器的配置，或停用认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

是否使用 JWKS。

endpoint
required
string

JWKS 端点， 它是一个以 JWKS 格式返回服务端的公钥集的只读端点。

pool_size
integer >= 1
Default: 8

桥接远端服务时使用的连接池大小。

refresh_interval
integer
Default: 300

JWKS 刷新间隔。

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

认证机制。

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: []

需要验证的自定义声明列表，它是一个名称/值对列表。
值可以使用以下占位符：
- ${username}: 将在运行时被替换为客户端连接时使用的用户名
- ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
认证时将验证 JWT（取自 Password 字段）中 claims 的值是否与 verify_claims 中要求的相匹配。

from
string
Default: "password"
Enum: "username" "password"

指定客户端连接请求中 JWT 的位置；可选值： password、 username（分别对应于 MQTT 客户端 CONNECT 报文中的 Password 和 Username 字段）

enable
boolean
Default: true

设为 true 或 false 以启用或禁用此认证数据源。

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Import users

导入用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Request Body schema: multipart/form-data
filename
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List users for gateway authenticator

获取用户列表（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

like_user_id
string
Example: like_user_id=test_

使用用户 ID （username 或 clientid）模糊搜索，仅支持按子串的方式进行搜索。

is_superuser
boolean

是否是超级用户

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add user for gateway authenticator

添加用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Delete user for gateway authenticator

删除用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

uid
required
string
Example: test_username

用户 ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get user info for gateway authenticator

获取用户信息（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

uid
required
string
Example: test_username

用户 ID

Responses

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Update user info for gateway authenticator

更新用户信息（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

uid
required
string
Example: test_username

用户 ID

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Import users

导入用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: stomp

网关名称.

可取值为 stomp、mqttsn、coap、lwm2m、exproto

id
required
string
Example: stomp:tcp:def

监听器 ID

Request Body schema: multipart/form-data
filename
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

CoAP Gateways

Send a Request to a Client

发送 CoAP 消息到指定客户端

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
token
string

消息 Token, 可以为空

method
string
Enum: "get" "put" "post" "delete"

请求 Method 类型

timeout
string

请求超时时间

content_type
string
Enum: "text/plain" "application/json" "application/octet-stream"

Payload 类型

payload
string

Payload 内容

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "method": "get",
  • "timeout": "32s",
  • "content_type": "text/plain",
  • "payload": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "token": "string",
  • "method": "string",
  • "payload": "string"
}

Retainer

查看保留消息列表

查看保留消息列表

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

删除对应的消息

删除对应的消息

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

主题

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

通过不带通配符的主题查看对应的保留消息

通过不带通配符的主题查看对应的保留消息

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

主题

Responses

Response samples

Content type
application/json
{
  • "payload": "string",
  • "msgid": "string",
  • "topic": "string",
  • "qos": 0,
  • "publish_at": "string",
  • "from_clientid": "string",
  • "from_username": "string"
}

查看配置内容

查看配置内容

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "delivery_rate": "1000/s",
  • "backend": {
    }
}

更新配置

更新配置

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: true

是否开启消息保留功能

msg_expiry_interval
string
Default: "0s"

消息保留时间。0 代表永久保留

msg_clear_interval
string
Default: "0s"

消息清理间隔。0 代表不进行清理

max_payload_size
string
Default: "1MB"

消息大小最大值

stop_publish_clear_msg
boolean
Default: false

是否不发送保留消息的清理消息，在 MQTT 5.0 中如果一条保留消息的消息体为空，则会清除掉之前存储
的对应的保留消息，通过这个值控制是否停止发送清理消息

delivery_rate
string

The maximum rate of delivering retained messages

object (retainer.mnesia_config)

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "delivery_rate": "1000/s",
  • "backend": {
    }
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "delivery_rate": "1000/s",
  • "backend": {
    }
}

Alarms

删除所有历史告警。

删除所有历史告警。

Authorizations:
basicAuthbearerAuth

Responses

列出当前激活的告警或历史告警，由查询参数决定。

列出当前激活的告警或历史告警，由查询参数决定。

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

activated
boolean

用于指定查询的告警类型，
为 true 时返回当前激活的告警，为 false 时返回历史告警，默认为 false。

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Subscriptions

列出订阅

列出订阅

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

node
string
Example: node=emqx@127.0.0.1

Node name

clientid
string

Client ID

qos
integer [ 0 .. 2 ]
Example: qos=0

QoS

topic
string

Topic, url encoding

match_topic
string

Match topic string, url encoding

share_group
string

Shared subscription group name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Error Codes

API 错误码

API 错误码

Responses

Response samples

Content type
application/json
[
  • {
    }
]

API 错误码

API 错误码

path Parameters
code
required
string
Enum: "BAD_USERNAME_OR_PWD" "BAD_API_KEY_OR_SECRET" "BAD_REQUEST" "NOT_MATCH" "ALREADY_EXISTS" "BAD_CONFIG_SCHEMA" "BAD_LISTENER_ID" "BAD_NODE_NAME" "BAD_RPC" "BAD_TOPIC" "EXCEED_LIMIT" "INVALID_PARAMETER" "CONFLICT" "NO_DEFAULT_VALUE" "DEPENDENCY_EXISTS" "MESSAGE_ID_SCHEMA_ERROR" "INVALID_ID" "MESSAGE_ID_NOT_FOUND" "NOT_FOUND" "CLIENTID_NOT_FOUND" "CLIENT_NOT_FOUND" "RESOURCE_NOT_FOUND" "TOPIC_NOT_FOUND" "USER_NOT_FOUND" "INTERNAL_ERROR" "SERVICE_UNAVAILABLE" "SOURCE_ERROR" "UPDATE_FAILED" "REST_FAILED" "CLIENT_NOT_RESPONSE"
Example: BAD_USERNAME_OR_PWD

API Error Codes

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Slow Subscriptions

查看配置

查看配置

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

更新配置

更新配置

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: false

开启慢订阅

threshold
string
Default: "500ms"

慢订阅统计的阈值

expire_interval
string
Default: "300s"

慢订阅记录的有效时间

top_k_num
integer >= 1
Default: 10

慢订阅统计表的记录数量上限

stats_type
string
Default: "whole"
Enum: "whole" "internal" "response"

慢订阅的统计类型

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

Response samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

清除当前记录，然后重新开始统计

清除当前记录，然后重新开始统计

Authorizations:
basicAuthbearerAuth

Responses

查看慢订阅的统计数据

查看慢订阅的统计数据

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

API Keys

Return api_key list

Return api_key list

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Create new api_key

Create new api_key

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
string

Unique and format by [a-zA-Z0-9-_]

(integer or string) or string
Default: "infinity"

No longer valid datetime

desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

Responses

Request samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "api_secret": "MzAyMjk3ODMwMDk0NjIzOTUxNjcwNzQ0NzQ3MTE2NDYyMDI",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Delete the specific api_key

Delete the specific api_key

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

^[A-Za-z]+[A-Za-z0-9-_]*$

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Return the specific api_key

Return the specific api_key

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

^[A-Za-z]+[A-Za-z0-9-_]*$

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Update the specific api_key

Update the specific api_key

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

^[A-Za-z]+[A-Za-z0-9-_]*$

Request Body schema: application/json
(integer or string) or string
Default: "infinity"

No longer valid datetime

desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

Responses

Request samples

Content type
application/json
{
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Banned

Clear all banned data.

Clear all banned data.

Authorizations:
basicAuthbearerAuth

Responses

列出目前所有被封禁的客户端 ID、用户名和 IP 地址。

列出目前所有被封禁的客户端 ID、用户名和 IP 地址。

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

添加一个客户端 ID、用户名或者 IP 地址到黑名单。

添加一个客户端 ID、用户名或者 IP 地址到黑名单。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
as
required
string
Enum: "clientid" "username" "peerhost"

封禁方式，可以通过客户端 ID、用户名或者 IP 地址等方式进行封禁。

who
required
string

封禁对象，具体的客户端 ID、用户名或者 IP 地址。

by
string

封禁的发起者。

reason
string

封禁原因，记录当前对象被封禁的原因。

integer or string

封禁的起始时间，格式为 rfc3339，默认为发起操作的时间。

integer or string

封禁的结束时间，格式为 rfc3339，默认值为发起操作的时间 + 1 年。

Responses

Request samples

Content type
application/json
{
  • "as": "username",
  • "who": "Banned name",
  • "by": "mgmt_api",
  • "reason": "Too many requests",
  • "at": "2021-10-25T21:48:47+08:00",
  • "until": "2021-10-25T21:53:47+08:00"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

将一个客户端 ID、用户名或者 IP 地址从黑名单中删除。

将一个客户端 ID、用户名或者 IP 地址从黑名单中删除。

Authorizations:
basicAuthbearerAuth
path Parameters
as
required
string
Enum: "clientid" "username" "peerhost"
Example: username

封禁方式，可以通过客户端 ID、用户名或者 IP 地址等方式进行封禁。

who
required
string
Example: Badass

封禁对象，具体的客户端 ID、用户名或者 IP 地址。

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}