< 反馈文档问题
API docs by Redocly

EMQX API (5.7.2)

Download OpenAPI specification:Download

Plugins

Get installed plugin's AVRO schema

Get plugin's config AVRO schema.

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
"string"

Get a plugin description

Describe a 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."
}

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 plugin config

Get plugin config. Config schema is defined by user's schema.avsc file.

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
"string"

Update plugin config

Update plugin config. Config schema defined by user's schema.avsc file.

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
object

Responses

Request samples

Content type
application/json
{ }

Response samples

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

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 hierarchy

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

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
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

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

query Parameters
type
required
string
Enum: "plain" "hash"
Example: type=hash

The import file template type, enum with plain,hash

Request Body schema:

Import body

filename
string <binary>

Responses

Request samples

Content type
No sample

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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

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
{
  • "status": "connected",
  • "node_status": [
    ],
  • "metrics": {
    },
  • "resource_metrics": {
    },
  • "node_error": [ ],
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ]
}

获取全局认证链上的指定认证器。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
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "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: "password_based"

认证方式。

backend
required
string
Value: "ldap"

后端类型。

query_timeout
string
Default: "5s"

LDAP 查询的超时时间。

enable
boolean
Default: true

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

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

指示哪个属性用于表示用户密码。

is_superuser_attribute
string
Default: "isSuperuser"

指示哪个属性用于表示用户是否为超级用户。

Responses

Request samples

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

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

Responses

Response samples

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

列出全局认证的认证器。

列出全局认证的认证器。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

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

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

认证方式。

backend
required
string
Value: "ldap"

后端类型。

query_timeout
string
Default: "5s"

LDAP 查询的超时时间。

enable
boolean
Default: true

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

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

指示哪个属性用于表示用户密码。

is_superuser_attribute
string
Default: "isSuperuser"

指示哪个属性用于表示用户是否为超级用户。

Responses

Request samples

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

Response samples

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

在全局认证链中重新排序所有认证器。

在全局认证链中重新排序所有认证器。

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

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

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Actions

Reset action metrics

通过 id 重置数据桥接指标。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Responses

Response samples

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

Manually start a bridge

启用集群中所有节点上的数据桥接。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

operation
required
string
Value: "start"
Example: start

集群可用操作：'启动'。

Responses

Response samples

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

Enable or disable bridge

启用或禁用集群内所有节点上的数据桥接。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

enable
required
boolean
Example: true

是否启用该数据桥接。

Responses

Response samples

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

List bridges

列出所有创建的数据桥接。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create bridge

通过类型和名称创建一个新的数据桥接。

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

MQTT 主题或主题过滤器作为数据源（动作输入）。 如果规则动作用作数据源，则应将此配置留空，否则消息将在远程系统中重复。

enable
boolean
Default: true

是否启用此动作。

connector
required
string

由动作指定的连接器名称，用于选择外部资源。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

required
object (bridge_mqtt_publisher.action_parameters)
object (bridge_mqtt_publisher.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Test creating bridge

测试创建一个新的数据桥接。

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

MQTT 主题或主题过滤器作为数据源（动作输入）。 如果规则动作用作数据源，则应将此配置留空，否则消息将在远程系统中重复。

enable
boolean
Default: true

是否启用此动作。

connector
required
string

由动作指定的连接器名称，用于选择外部资源。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

required
object (bridge_mqtt_publisher.action_parameters)
object (bridge_mqtt_publisher.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

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

List available action types

列出所有可用的动作类型。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "http",
  • "mqtt"
]

Get bridge

通过 id 获取一个数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Responses

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Update bridge

通过 id 更新数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Request Body schema: application/json
One of
local_topic
string

MQTT 主题或主题过滤器作为数据源（动作输入）。 如果规则动作用作数据源，则应将此配置留空，否则消息将在远程系统中重复。

enable
boolean
Default: true

是否启用此动作。

connector
required
string

由动作指定的连接器名称，用于选择外部资源。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

required
object (bridge_mqtt_publisher.action_parameters)
object (bridge_mqtt_publisher.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Delete bridge

通过 id 删除数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

query Parameters
also_delete_dep_actions
boolean
Default: false

是否级联删除依赖的动作。

Responses

Response samples

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

Get action metrics

通过 id 来获取数据桥接的指标信息。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Responses

Response samples

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

Manually start a bridge on a given node

在某个节点上启动数据桥接。

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

节点名称，例如： 'emqx@127.0.0.1'。

id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

operation
required
string
Value: "start"
Example: start

节点可用操作：'启动'。

Responses

Response samples

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

Metrics

EMQX 监控指标信息

EMQX 监控指标信息

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Whether to aggregate all nodes Metrics

Responses

Response samples

Content type
application/json
Example
[ ]

获取 EMQX 状态

获取 EMQX 状态

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Calculation aggregate for all nodes

Responses

Response samples

Content type
application/json
Example
{
  • "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,
  • "cluster_sessions.count": 0,
  • "cluster_sessions.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

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "persisted_rate": 0,
  • "received_msg_rate": 0,
  • "transformation_failed_rate": 0,
  • "transformation_succeeded_rate": 0,
  • "validation_failed_rate": 0,
  • "validation_succeeded_rate": 0,
  • "disconnected_durable_sessions": 0,
  • "subscriptions_durable": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0,
  • "retained_msg_count": 0,
  • "shared_subscriptions": 0
}

节点监控（统计）数据，例如指定节点上的连接数和连接速率。

节点监控（统计）数据，例如指定节点上的连接数和连接速率。

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

EMQX node name.

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "persisted_rate": 0,
  • "received_msg_rate": 0,
  • "transformation_failed_rate": 0,
  • "transformation_succeeded_rate": 0,
  • "validation_failed_rate": 0,
  • "validation_succeeded_rate": 0,
  • "disconnected_durable_sessions": 0,
  • "subscriptions_durable": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0,
  • "node_uptime": 0,
  • "retained_msg_count": 0,
  • "shared_subscriptions": 0
}

包括连接数/在线连接数、主题数/订阅数、消息流入数、流出数、丢弃数等指标。

包括连接数/在线连接数、主题数/订阅数、消息流入数、流出数、丢弃数等指标。

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

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

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
{
  • "topic": "testtopic/1",
  • "create_time": "2022-01-14T21:48:47+08:00",
  • "reset_time": "2022-01-14T21:48:47+08:00",
  • "metrics": {
    }
}

删除主题监控

删除主题监控

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

主题

Responses

Response samples

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

获取主题监控数据

获取主题监控数据

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

重置主题监控数据

重置主题监控数据

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
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
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

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

Results per page(max 10000)

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

Bridges

Reset bridge metrics

通过 Id 重置数据桥接的指标

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 ID ， 格式为 {type}:{name}

Responses

Response samples

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

Stop/restart bridge

在某个节点上停止/重新启动数据桥接。

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

节点名，比如 emqx@127.0.0.1

id
required
string
Example: http:http_example

数据桥接 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
Enum: "webhook" "http"

动作的类型

name
required
string

动作名称，用作动作的可读描述。

enable
boolean
Default: true

启用或停用动作

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

connect_timeout
string
Default: "15s"

连接到 HTTP 服务器的超时时间。

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

连接池类型。可以是random、hash之一。

pool_size
integer >= 1
Default: 8

连接池大小。

enable_pipelining
integer >= 1
Default: 100

一个正整数。是否连续发送 HTTP 请求，当设置为1时，意味着在发送每个 HTTP 请求后，需要等待服务器返回，然后继续发送下一个请求。

request
object
Deprecated

This field is never used, so we deprecated it since 5.3.2.

object (emqx.ssl_client_opts)
url
required
string

HTTP 动作的 URL。

此路径允许使用带有变量的模板，但变量不能用于方案、主机或端口部分。

例如， http://localhost:9901/${topic} 是允许的，但
http://${host}:9901/message 或 http://localhost:${port}/message
是不允许的。

direction
string
Deprecated
Value: "egress"
local_topic
string

将要转发到 HTTP 服务器的 MQTT 主题过滤器。所有与 local_topic 匹配的 MQTT 'PUBLISH' 消息都将被转发。

注意：如果将此动作用作规则的操作（EMQX 规则引擎），并且同时配置了 local_topic，那么将同时转发从规则获取的数据和与 local_topic 匹配的 MQTT 消息。

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

HTTP 请求的方法。所有可用的方法包括：post、put、get、delete。

允许使用带有变量的模板。

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

HTTP 请求头。

允许使用带有变量的模板。

body
string

HTTP 请求的主体。

如果未提供，主体将是所有可用字段的 JSON 对象。

这里的“所有可用字段”是指在触发此 Webhook 时的 MQTT 消息的上下文（当 local_topic 已设置并接收到 MQTT 消息时触发），
或者当此 Webhook 用作规则的动作时，在触发此 Webhook 时的事件上下文。
允许使用带有变量的模板。

max_retries
integer >= 0
Default: 2

如果发送请求时出错，最大的重试次数。

request_timeout
string
Deprecated
Default: "15s"

HTTP 请求超时时间

object (bridge_http.v1_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Response samples

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

Enable or disable bridge

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 ID ， 格式为 {type}:{name}

enable
required
boolean
Example: true

是否启用桥接

Responses

Response samples

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

Get bridge metrics

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 ID ， 格式为 {type}:{name}

Responses

Response samples

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

Get bridge

通过 Id 获取数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 ID ， 格式为 {type}:{name}

Responses

Response samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Update bridge

通过 Id 更新数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 ID ， 格式为 {type}:{name}

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

启用或停用动作

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

connect_timeout
string
Default: "15s"

连接到 HTTP 服务器的超时时间。

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

连接池类型。可以是random、hash之一。

pool_size
integer >= 1
Default: 8

连接池大小。

enable_pipelining
integer >= 1
Default: 100

一个正整数。是否连续发送 HTTP 请求，当设置为1时，意味着在发送每个 HTTP 请求后，需要等待服务器返回，然后继续发送下一个请求。

request
object
Deprecated

This field is never used, so we deprecated it since 5.3.2.

object (emqx.ssl_client_opts)
url
required
string

HTTP 动作的 URL。

此路径允许使用带有变量的模板，但变量不能用于方案、主机或端口部分。

例如， http://localhost:9901/${topic} 是允许的，但
http://${host}:9901/message 或 http://localhost:${port}/message
是不允许的。

direction
string
Deprecated
Value: "egress"
local_topic
string

将要转发到 HTTP 服务器的 MQTT 主题过滤器。所有与 local_topic 匹配的 MQTT 'PUBLISH' 消息都将被转发。

注意：如果将此动作用作规则的操作（EMQX 规则引擎），并且同时配置了 local_topic，那么将同时转发从规则获取的数据和与 local_topic 匹配的 MQTT 消息。

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

HTTP 请求的方法。所有可用的方法包括：post、put、get、delete。

允许使用带有变量的模板。

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

HTTP 请求头。

允许使用带有变量的模板。

body
string

HTTP 请求的主体。

如果未提供，主体将是所有可用字段的 JSON 对象。

这里的“所有可用字段”是指在触发此 Webhook 时的 MQTT 消息的上下文（当 local_topic 已设置并接收到 MQTT 消息时触发），
或者当此 Webhook 用作规则的动作时，在触发此 Webhook 时的事件上下文。
允许使用带有变量的模板。

max_retries
integer >= 0
Default: 2

如果发送请求时出错，最大的重试次数。

request_timeout
string
Deprecated
Default: "15s"

HTTP 请求超时时间

object (bridge_http.v1_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Response samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Delete bridge

通过 Id 删除数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 ID ， 格式为 {type}:{name}

Responses

Response samples

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

Stop or restart bridge

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

数据桥接 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

列出所有数据桥接

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create bridge

通过类型和名字创建数据桥接

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

动作的类型

name
required
string

动作名称，用作动作的可读描述。

enable
boolean
Default: true

启用或停用动作

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

connect_timeout
string
Default: "15s"

连接到 HTTP 服务器的超时时间。

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

连接池类型。可以是random、hash之一。

pool_size
integer >= 1
Default: 8

连接池大小。

enable_pipelining
integer >= 1
Default: 100

一个正整数。是否连续发送 HTTP 请求，当设置为1时，意味着在发送每个 HTTP 请求后，需要等待服务器返回，然后继续发送下一个请求。

request
object
Deprecated

This field is never used, so we deprecated it since 5.3.2.

object (emqx.ssl_client_opts)
url
required
string

HTTP 动作的 URL。

此路径允许使用带有变量的模板，但变量不能用于方案、主机或端口部分。

例如， http://localhost:9901/${topic} 是允许的，但
http://${host}:9901/message 或 http://localhost:${port}/message
是不允许的。

direction
string
Deprecated
Value: "egress"
local_topic
string

将要转发到 HTTP 服务器的 MQTT 主题过滤器。所有与 local_topic 匹配的 MQTT 'PUBLISH' 消息都将被转发。

注意：如果将此动作用作规则的操作（EMQX 规则引擎），并且同时配置了 local_topic，那么将同时转发从规则获取的数据和与 local_topic 匹配的 MQTT 消息。

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

HTTP 请求的方法。所有可用的方法包括：post、put、get、delete。

允许使用带有变量的模板。

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

HTTP 请求头。

允许使用带有变量的模板。

body
string

HTTP 请求的主体。

如果未提供，主体将是所有可用字段的 JSON 对象。

这里的“所有可用字段”是指在触发此 Webhook 时的 MQTT 消息的上下文（当 local_topic 已设置并接收到 MQTT 消息时触发），
或者当此 Webhook 用作规则的动作时，在触发此 Webhook 时的事件上下文。
允许使用带有变量的模板。

max_retries
integer >= 0
Default: 2

如果发送请求时出错，最大的重试次数。

request_timeout
string
Deprecated
Default: "15s"

HTTP 请求超时时间

object (bridge_http.v1_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Response samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Status

节点的健康检查 API，返回当前节点状态信息。<br/><br/>如果 EMQX 应用程序已经启动并

节点的健康检查 API，返回当前节点状态信息。

如果 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@172.17.0.2

Node Name

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

Page number of the results to fetch.

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

Results per page(max 10000)

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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

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

显示客户端规则列表。

显示客户端规则列表。

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

Page number of the results to fetch.

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

Results per page(max 10000)

like_clientid
string

使用字串匹配模糊搜索客户端 ID

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

客户端 ID

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

客户端 ID

Responses

Response samples

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

设置指定客户端的规则

设置指定客户端的规则

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

客户端 ID

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

客户端 ID

Responses

Request samples

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

Response samples

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

删除指定客户端的规则

删除指定客户端的规则

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

客户端 ID

Responses

Response samples

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

获取指定授权器的状态

获取指定授权器的状态

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

授权期所使用的数据源类型。

Responses

Response samples

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

列出所有授权器。

列出所有授权器。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

添加授权器

添加授权器

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

数据后端类型

enable
boolean
Default: true

设置为 true 或 false 来禁用此 ACL 提供者

publish_attribute
string
Default: "mqttPublishTopic"

表示使用哪个属性来表示允许发布的主题列表。

subscribe_attribute
string
Default: "mqttSubscriptionTopic"

表示使用哪个属性来表示允许订阅的主题列表。

all_attribute
string
Default: "mqttPubSubTopic"

表示使用哪个属性来表示允许发布和订阅的主题列表。

query_timeout
string
Default: "5s"

LDAP 查询超时。

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "ldap",
  • "enable": true,
  • "publish_attribute": "mqttPublishTopic",
  • "subscribe_attribute": "mqttSubscriptionTopic",
  • "all_attribute": "mqttPubSubTopic",
  • "query_timeout": "32s",
  • "server": "string",
  • "pool_size": 8,
  • "username": "string",
  • "password": "R4ND0M/S∃CЯ∃T",
  • "base_dn": "uid=${username},ou=testdevice,dc=emqx,dc=io",
  • "filter": "(& (objectClass=mqttUser) (uid=${username}))",
  • "request_timeout": "32s",
  • "ssl": {
    }
}

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

删除指定用户名的规则

删除指定用户名的规则

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

用户名

Responses

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: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

授权期所使用的数据源类型。

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: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

授权期所使用的数据源类型。

Responses

Response samples

Content type
application/json
Example
{
  • "type": "ldap",
  • "enable": true,
  • "publish_attribute": "mqttPublishTopic",
  • "subscribe_attribute": "mqttSubscriptionTopic",
  • "all_attribute": "mqttPubSubTopic",
  • "query_timeout": "32s",
  • "server": "string",
  • "pool_size": 8,
  • "username": "string",
  • "password": "R4ND0M/S∃CЯ∃T",
  • "base_dn": "uid=${username},ou=testdevice,dc=emqx,dc=io",
  • "filter": "(& (objectClass=mqttUser) (uid=${username}))",
  • "request_timeout": "32s",
  • "ssl": {
    }
}

更新指定的授权器

更新指定的授权器

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

授权期所使用的数据源类型。

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

数据后端类型

enable
boolean
Default: true

设置为 true 或 false 来禁用此 ACL 提供者

publish_attribute
string
Default: "mqttPublishTopic"

表示使用哪个属性来表示允许发布的主题列表。

subscribe_attribute
string
Default: "mqttSubscriptionTopic"

表示使用哪个属性来表示允许订阅的主题列表。

all_attribute
string
Default: "mqttPubSubTopic"

表示使用哪个属性来表示允许发布和订阅的主题列表。

query_timeout
string
Default: "5s"

LDAP 查询超时。

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "ldap",
  • "enable": true,
  • "publish_attribute": "mqttPublishTopic",
  • "subscribe_attribute": "mqttSubscriptionTopic",
  • "all_attribute": "mqttPubSubTopic",
  • "query_timeout": "32s",
  • "server": "string",
  • "pool_size": 8,
  • "username": "string",
  • "password": "R4ND0M/S∃CЯ∃T",
  • "base_dn": "uid=${username},ou=testdevice,dc=emqx,dc=io",
  • "filter": "(& (objectClass=mqttUser) (uid=${username}))",
  • "request_timeout": "32s",
  • "ssl": {
    }
}

Response samples

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

删除指定的授权器

删除指定的授权器

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

授权期所使用的数据源类型。

Responses

Response samples

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

重新排序所有授权源。

重新排序所有授权源。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

授权期所使用的数据源类型。

Responses

Request samples

Content type
application/json
[
  • {
    }
]

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 (emqx.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

Response samples

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

删除 'all' 规则

删除 'all' 规则

Authorizations:
basicAuthbearerAuth

Responses

创建或更新适用于所有客户端的规则（即 '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,
  • "cluster_sessions.count": 0,
  • "cluster_sessions.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",
  • "bytes.received": 0,
  • "bytes.sent": 0,
  • "packets.received": 0,
  • "packets.sent": 0,
  • "packets.connect.received": 0,
  • "packets.connack.sent": 0,
  • "packets.connack.error": 0,
  • "packets.connack.auth_error": 0,
  • "packets.publish.received": 0,
  • "packets.publish.sent": 0,
  • "packets.publish.inuse": 0,
  • "packets.publish.error": 0,
  • "packets.publish.auth_error": 0,
  • "packets.publish.dropped": 0,
  • "packets.puback.received": 0,
  • "packets.puback.sent": 0,
  • "packets.puback.inuse": 0,
  • "packets.puback.missed": 0,
  • "packets.pubrec.received": 0,
  • "packets.pubrec.sent": 0,
  • "packets.pubrec.inuse": 0,
  • "packets.pubrec.missed": 0,
  • "packets.pubrel.received": 0,
  • "packets.pubrel.sent": 0,
  • "packets.pubrel.missed": 0,
  • "packets.pubcomp.received": 0,
  • "packets.pubcomp.sent": 0,
  • "packets.pubcomp.inuse": 0,
  • "packets.pubcomp.missed": 0,
  • "packets.subscribe.received": 0,
  • "packets.subscribe.error": 0,
  • "packets.subscribe.auth_error": 0,
  • "packets.suback.sent": 0,
  • "packets.unsubscribe.received": 0,
  • "packets.unsubscribe.error": 0,
  • "packets.unsuback.sent": 0,
  • "packets.pingreq.received": 0,
  • "packets.pingresp.sent": 0,
  • "packets.disconnect.received": 0,
  • "packets.disconnect.sent": 0,
  • "packets.auth.received": 0,
  • "packets.auth.sent": 0,
  • "messages.received": 0,
  • "messages.sent": 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.publish": 0,
  • "messages.dropped": 0,
  • "messages.validation_failed": 0,
  • "messages.validation_succeeded": 0,
  • "messages.transformation_failed": 0,
  • "messages.transformation_succeeded": 0,
  • "messages.dropped.await_pubrel_timeout": 0,
  • "messages.dropped.no_subscribers": 0,
  • "messages.forward": 0,
  • "messages.delayed": 0,
  • "messages.delivered": 0,
  • "messages.acked": 0,
  • "messages.persisted": 0,
  • "delivery.dropped": 0,
  • "delivery.dropped.no_local": 0,
  • "delivery.dropped.too_large": 0,
  • "delivery.dropped.qos0_msg": 0,
  • "delivery.dropped.queue_full": 0,
  • "delivery.dropped.expired": 0,
  • "client.connect": 0,
  • "client.connack": 0,
  • "client.connected": 0,
  • "client.authenticate": 0,
  • "client.auth.anonymous": 0,
  • "client.authorize": 0,
  • "client.subscribe": 0,
  • "client.unsubscribe": 0,
  • "client.disconnected": 0,
  • "session.created": 0,
  • "session.resumed": 0,
  • "session.takenover": 0,
  • "session.discarded": 0,
  • "session.terminated": 0,
  • "authorization.allow": 0,
  • "authorization.deny": 0,
  • "authorization.cache_hit": 0,
  • "authorization.cache_miss": 0,
  • "authentication.success": 0,
  • "authentication.success.anonymous": 0,
  • "authentication.failure": 0,
  • "overload_protection.delay.ok": 0,
  • "overload_protection.delay.timeout": 0,
  • "overload_protection.hibernation": 0,
  • "overload_protection.gc": 0,
  • "overload_protection.new_conn": 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,
  • "cluster_sessions": 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"
}

获取当前集群下的节点列表。

获取当前集群下的节点列表。

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
{
  • "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
{
  • "name": "default",
  • "ssl": {
    },
  • "pool_size": 8,
  • "enable": true,
  • "url": "http://127.0.0.1:8081",
  • "request_timeout": "5s",
  • "auto_reconnect": "60s",
  • "failed_action": "deny"
}

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
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

移动 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
{
  • "name": "default",
  • "ssl": {
    },
  • "pool_size": 8,
  • "enable": true,
  • "url": "http://127.0.0.1:8081",
  • "request_timeout": "5s",
  • "auto_reconnect": "60s",
  • "failed_action": "deny"
}

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

获取 Prometheus 配置信息

获取 Prometheus 配置信息

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "collectors": {
    },
  • "enable_basic_auth": false,
  • "push_gateway": {
    }
}

更新 Prometheus 配置

更新 Prometheus 配置

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

自5.4.0版本起弃用，改用 prometheus.push_gateway.url。

interval
required
string
Default: "15s"

自5.4.0版本起弃用，改用 prometheus.push_gateway.interval。

headers
object
Default: {}

自5.4.0版本起弃用，改用 prometheus.push_gateway.headers。

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

自5.4.0版本起弃用，改用 prometheus.push_gateway.job_name。

enable
required
boolean
Default: false

自5.4.0版本起弃用，改用 prometheus.push_gateway.url。

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

自5.4.0版本起弃用，改用 prometheus.collectors.vm_dist。

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

自5.4.0版本起弃用，改用 prometheus.collectors.mnesia。

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

自5.4.0版本起弃用，改用 prometheus.collectors.vm_statistics。

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

自5.4.0版本起弃用，改用 prometheus.collectors.vm_system_info。

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

自5.4.0版本起弃用，改用 prometheus.collectors.vm_memory。

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

自5.4.0版本起弃用，改用 prometheus.collectors.vm_msacc。

Responses

Request samples

Content type
application/json
Example
{
  • "collectors": {
    },
  • "enable_basic_auth": false,
  • "push_gateway": {
    }
}

Response samples

Content type
application/json
{
  • "collectors": {
    },
  • "enable_basic_auth": false,
  • "push_gateway": {
    }
}

获取数据集成的 Prometheus 指标

获取数据集成的 Prometheus 指标

query Parameters
mode
string
Default: "node"
Enum: "node" "all_nodes_aggregated" "all_nodes_unaggregated"
Example: mode=node


Metrics format mode.

node:
Return metrics from local node. And it is the default behaviour if mode not specified.

all_nodes_aggregated:
Return metrics for all nodes.
And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.

all_nodes_unaggregated:
Return metrics from all nodes, and the metrics are not aggregated.
The node name will be included in the returned results to
indicate that certain metrics were returned on a certain node.

Responses

Response samples

Content type
No sample

获取 Prometheus 数据

获取 Prometheus 数据

query Parameters
mode
string
Default: "node"
Enum: "node" "all_nodes_aggregated" "all_nodes_unaggregated"
Example: mode=node


Metrics format mode.

node:
Return metrics from local node. And it is the default behaviour if mode not specified.

all_nodes_aggregated:
Return metrics for all nodes.
And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.

all_nodes_unaggregated:
Return metrics from all nodes, and the metrics are not aggregated.
The node name will be included in the returned results to
indicate that certain metrics were returned on a certain node.

Responses

Response samples

Content type
No sample

获取 AuthN、AuthZ 和 Banned 的 Prometheus 指标

获取 AuthN、AuthZ 和 Banned 的 Prometheus 指标

query Parameters
mode
string
Default: "node"
Enum: "node" "all_nodes_aggregated" "all_nodes_unaggregated"
Example: mode=node


Metrics format mode.

node:
Return metrics from local node. And it is the default behaviour if mode not specified.

all_nodes_aggregated:
Return metrics for all nodes.
And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.

all_nodes_unaggregated:
Return metrics from all nodes, and the metrics are not aggregated.
The node name will be included in the returned results to
indicate that certain metrics were returned on a certain node.

Responses

Response samples

Content type
No sample

Get opentelmetry configuration

Get opentelmetry configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "exporter": {},
  • "metrics": {
    },
  • "traces": {
    },
  • "logs": {
    }
}

Update opentelmetry configuration

Update opentelmetry configuration

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (opentelemetry.otel_metrics)
object (opentelemetry.otel_logs)
object (opentelemetry.otel_traces)
object (opentelemetry.otel_exporter)

Responses

Request samples

Content type
application/json
{
  • "exporter": {},
  • "metrics": {
    },
  • "traces": {
    },
  • "logs": {
    }
}

Response samples

Content type
application/json
{
  • "exporter": {},
  • "metrics": {
    },
  • "traces": {
    },
  • "logs": {
    }
}

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。消息服务质量。
至多一次（0）
至少一次（1）
恰好一次（2）

rh
integer [ 0 .. 2 ]
Default: 0

默认值为 0。此选项用于指定客户端建立订阅时，服务器是否向客户端转发保留的消息。
当 Retain Handling 等于 0 时，只要客户端成功订阅，服务器就会发送保留消息。
当 Retain Handling 等于 1 时，如果客户端成功订阅并且此前不存在此订阅，服务器发送保留消息。毕竟，有时客户端重新发起订阅只是为了改变 QoS，并不意味着它想再次接收保留的消息。
当 Retain Handling 等于 2 时，即使客户端成功订阅，服务器也不会发送保留消息。

rap
integer [ 0 .. 1 ]
Default: 0

默认值为 0。此选项用于指定服务器在向客户端转发消息时是否保留 RETAIN 标记，而且此选项不影响保留消息中的 RETAIN 标记。因此，当选项 Retain As Publish 设置为 0 时，客户端将直接根据消息中的 RETAIN 标记来区分这是普通的转发消息还是保留消息，而不是判断此消息是否为订阅后首次收到的消息（转发的消息可能在保留消息之前发送，这取决于不同消息服务器的具体实现）。

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

Get the listener's authenticator

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
required
string

监听器 ID

Responses

Response samples

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

Update config of authenticator for listener

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
required
string

监听器 ID

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

认证方式。

backend
required
string
Value: "ldap"

后端类型。

query_timeout
string
Default: "5s"

LDAP 查询的超时时间。

enable
boolean
Default: true

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

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

指示哪个属性用于表示用户密码。

is_superuser_attribute
string
Default: "isSuperuser"

指示哪个属性用于表示用户是否为超级用户。

Responses

Request samples

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

Response samples

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

Delete the listener's authenticator

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
required
string

监听器 ID

Responses

Response samples

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

Create authenticator for listener

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
required
string

监听器 ID

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

认证方式。

backend
required
string
Value: "ldap"

后端类型。

query_timeout
string
Default: "5s"

LDAP 查询的超时时间。

enable
boolean
Default: true

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

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

指示哪个属性用于表示用户密码。

is_superuser_attribute
string
Default: "isSuperuser"

指示哪个属性用于表示用户是否为超级用户。

Responses

Request samples

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

Response samples

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

List all listeners

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

Request Body schema: application/json
One of
id
string

监听器 ID

type
string
Value: "wss"

监听器类型

name
string

监听器名称

running
boolean

监听器运行状态

acceptors
integer
Default: 16

Acceptor 进程池大小。

object (emqx.tcp_opts)
proxy_protocol
boolean
Default: false

如果为 EMQX 部署了反向代理，且在代理处启用了 PROXY 协议以传递客户端真实 IP 时，则需要一并开启此选项，以便 EMQX 从 PROXY 协议标头中提取客户端真实 IP。EMQX 将自动检测 PROXY 协议的版本，支持 V1 和 V2。

PROXY 协议的详细说明，请参考：https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

接收 Proxy Protocol 报文头的超时时间。如果在超时内没有收到 Proxy Protocol 包，EMQX 将关闭 TCP 连接。

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: []

由字符串规则组成的访问规则列表，以限制或允许某些地址的访问。规则之间存在前后顺序。规则的格式为 allow | deny <address> | <CIDR> | all。
例如：
["deny 192.168.1.1", "allow 192.168.1.0/24", "deny, all"]

object (emqx.listener_wss_opts)
object (gateway.websocket)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Get listener config

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
required
string

监听器 ID

Responses

Response samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Update listener config

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
required
string

监听器 ID

Request Body schema: application/json
One of
id
string

监听器 ID

type
string
Value: "wss"

监听器类型

name
string

监听器名称

running
boolean

监听器运行状态

acceptors
integer
Default: 16

Acceptor 进程池大小。

object (emqx.tcp_opts)
proxy_protocol
boolean
Default: false

如果为 EMQX 部署了反向代理，且在代理处启用了 PROXY 协议以传递客户端真实 IP 时，则需要一并开启此选项，以便 EMQX 从 PROXY 协议标头中提取客户端真实 IP。EMQX 将自动检测 PROXY 协议的版本，支持 V1 和 V2。

PROXY 协议的详细说明，请参考：https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

接收 Proxy Protocol 报文头的超时时间。如果在超时内没有收到 Proxy Protocol 包，EMQX 将关闭 TCP 连接。

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: []

由字符串规则组成的访问规则列表，以限制或允许某些地址的访问。规则之间存在前后顺序。规则的格式为 allow | deny <address> | <CIDR> | all。
例如：
["deny 192.168.1.1", "allow 192.168.1.0/24", "deny, all"]

object (emqx.listener_wss_opts)
object (gateway.websocket)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Delete listener

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

id
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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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": {
    }
}

Delete user

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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"
}

List authenticator's users

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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 (emqx.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 (emqx.sysmon_vm)
object (emqx.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": {
    },
  • "durable_sessions": {
    }
}

更新全局默认 zone 的配置

更新全局默认 zone 的配置

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

Responses

Request samples

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

Response samples

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

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"]
Items Enum: "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,
  • "swagger_support": true
}

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（Cross-Origin Resource Sharing，跨域资源共享）允许服务器响应来自任何来源（域名、协议或端口）的请求，启用后允许另一个域名下的服务直接通过 JavaScript 调用 EMQX REST API。

swagger_support
boolean
Default: true

启用或禁用对 Swagger API 文档的支持。

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *broker*

Get the sub-configurations under broker

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable_session_registry": true,
  • "session_history_retain": "1h"
}

Update the sub-configurations under *broker*

Update the sub-configurations under broker

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

是否启用 Session Registry

session_history_retain
string
Default: "0s"

保留会话注册历史记录的持续时间。将此值设置为大于 0s 的值会增加内存使用并影响性能。
这个保留的历史记录可以用来监控过去配置的持续时间内注册了多少会话。
注意：如果 enable_session_registry 设置为 false，则此配置无效。

注意：如果客户端使用随机客户端 ID，则不建议启用此功能，至少不是长时间保留。

注意：在集群中，集群内节点中的最低（但大于 0s）值将生效。

Responses

Request samples

Content type
application/json
{
  • "enable_session_registry": true,
  • "session_history_retain": "1h"
}

Response samples

Content type
application/json
{
  • "enable_session_registry": true,
  • "session_history_retain": "1h"
}

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

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
rootname
required
string
Enum: "broker" "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"
}

获取指定键的所有配置，包括热更新和非热更新项目。

获取指定键的所有配置，包括热更新和非热更新项目。

Authorizations:
basicAuthbearerAuth
query Parameters
key
string
Enum: "actions" "alarm" "api_key" "authentication" "authorization" "auto_subscribe" "banned" "bridges" "cluster" "conn_congestion" "connectors" "crl_cache" "dashboard" "delayed" "durable_storage" "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" "sources" "sys_topics" "sysmon" "telemetry" "topic_metrics"
Example: key=sysmon
node
string

指定节点名称。如果未指定，则返回当前 HTTP 请求节点的配置。

Responses

Response samples

Content type
No sample

更新指定建的配置。

更新指定建的配置。

Authorizations:
basicAuthbearerAuth
query Parameters
mode
string
Default: "merge"
Enum: "replace" "merge"
ignore_readonly
boolean
Default: false
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": {
    },
  • "throttling": {
    }
}

Update the sub-configurations under *log*

Update the sub-configurations under log

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

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

object (emqx.log_throttling)

Responses

Request samples

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

Response samples

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

Clients

----

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

Responses

Request samples

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

获取集群中的会话总数。<br/>默认情况下，仅包括那些未过期的会话。<br/>如果 broker.s

获取集群中的会话总数。
默认情况下，仅包括那些未过期的会话。
如果 broker.session_history_retain 配置设置为大于 0 秒的持续时间，
这个计数也将包括在指定保留时间内过期的会话。
通过指定 since 参数，它可以返回在指定时间内过期的会话数。

Authorizations:
basicAuthbearerAuth
query Parameters
since
integer >= 0
Default: 0
Example: since=1705391625

Include sessions expired after this time (UNIX Epoch in seconds precision)

Responses

Response samples

Content type
application/json
"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
{
  • "heap_size": 610,
  • "send_msg.dropped.expired": 0,
  • "send_oct": 31,
  • "recv_msg.qos1": 0,
  • "is_persistent": false,
  • "send_pkt": 4,
  • "clean_start": true,
  • "inflight_cnt": 0,
  • "node": "emqx@127.0.0.1",
  • "send_msg.dropped.queue_full": 0,
  • "awaiting_rel_cnt": 0,
  • "inflight_max": 32,
  • "created_at": "2024-01-01T12:34:56.789+08:00",
  • "subscriptions_cnt": 1,
  • "mailbox_len": 0,
  • "send_cnt": 4,
  • "connected": true,
  • "ip_address": "127.0.0.1",
  • "awaiting_rel_max": 100,
  • "recv_msg.qos2": 0,
  • "proto_ver": 5,
  • "mountpoint": "null",
  • "proto_name": "MQTT",
  • "durable": false,
  • "port": 52571,
  • "connected_at": "2024-01-01T12:34:56.789+08:00",
  • "enable_authn": true,
  • "expiry_interval": 0,
  • "username": null,
  • "recv_msg": 0,
  • "recv_oct": 49,
  • "send_msg.dropped.too_large": 0,
  • "keepalive": 60,
  • "send_msg.qos1": 0,
  • "send_msg.qos2": 0,
  • "recv_msg.qos0": 0,
  • "send_msg.qos0": 0,
  • "subscriptions_max": "infinity",
  • "mqueue_max": 1000,
  • "mqueue_dropped": 0,
  • "clientid": "01",
  • "is_bridge": false,
  • "peerport": 52571,
  • "send_msg": 0,
  • "listener": "tcp:default",
  • "recv_cnt": 4,
  • "recv_pkt": 4,
  • "recv_msg.dropped": 0,
  • "send_msg.dropped": 0,
  • "recv_msg.dropped.await_pubrel_timeout": 0,
  • "reductions": 6836,
  • "mqueue_len": 0
}

踢出指定客户端

踢出指定客户端

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
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,
  • "durable": false
}

获取客户端消息队列中的消息。

获取客户端消息队列中的消息。

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

Client's inflight/mqueue messages payload encoding. If set to none, no payload is returned in the response.

max_payload_bytes
string
Default: "1MB"
Example: max_payload_bytes=32MB

Client's inflight/mqueue messages payload limit. The total payload size of all messages in the response will not exceed this value. Messages beyond the limit will be silently omitted in the response. The only exception to this rule is when the first message payload is already larger than the limit. In this case, the first message will be returned in the response.

string or string or string
Example: position=none

An opaque token that can then be in subsequent requests to get the next chunk of results: "?position={prev_response.meta.position}"
It is used instead of "page" parameter to traverse highly volatile data.
Can be omitted or set to "none" to get the first chunk of data.

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

Results per page(max 10000)

Responses

Response samples

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

获取客户端未确认消息。

获取客户端未确认消息。

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

Client's inflight/mqueue messages payload encoding. If set to none, no payload is returned in the response.

max_payload_bytes
string
Default: "1MB"
Example: max_payload_bytes=32MB

Client's inflight/mqueue messages payload limit. The total payload size of all messages in the response will not exceed this value. Messages beyond the limit will be silently omitted in the response. The only exception to this rule is when the first message payload is already larger than the limit. In this case, the first message will be returned in the response.

string or string or string
Example: position=none

An opaque token that can then be in subsequent requests to get the next chunk of results: "?position={prev_response.meta.position}"
It is used instead of "page" parameter to traverse highly volatile data.
Can be omitted or set to "none" to get the first chunk of data.

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

Results per page(max 10000)

Responses

Response samples

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

取消订阅

取消订阅

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.

node
string
Example: node=emqx@127.0.0.1

Node name

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

Results per page(max 10000)

username
Array of strings

User name, multiple values can be specified by repeating the parameter: username=u1&username=u2

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)

clientid
Array of strings

Client ID, multiple values can be specified by repeating the parameter: clientid=c1&clientid=c2

Array of strings or string
Default: "all"

Comma separated list of client fields to return in the response

Responses

Response samples

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

Connectors

Test creating connector

测试创建一个新的连接器。

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

连接器的类型。

name
required
string

连接器的名称

enable
boolean
Default: true

是否启用该连接器。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

pool_size
integer >= 1
Default: 8

将发布消息到远程代理的 MQTT 客户端池的大小。

每个 MQTT 客户端都将分配'clientid'，格式为'${clientid_prefix}:${bridge_name}:egress:${node}:${n}'
其中'n'是池中客户端的编号。

object (connector_mqtt.resource_opts)
mode
string
Deprecated
Default: "cluster_shareload"
Value: "cluster_shareload"

MQTT 动作的模式。

- cluster_shareload：在 emqx 集群中的每个节点上创建一个 MQTT 连接。

在'cluster_shareload'模式下，来自远程代理的传入负载通过
使用共享订阅进行共享。

请注意，'clientid'将以节点名称作为后缀，以避免
不同节点之间的 clientid 冲突。并且我们只能使用共享订阅
作为入口连接的'remote.topic'的主题过滤器。

server
required
string

远程 MQTT 代理的主机和端口

clientid_prefix
string

附加到 egress 动作使用的 clientid 前缀（可选）。

reconnect_interval
string
Deprecated
proto_ver
string
Default: "v4"
Enum: "v3" "v4" "v5"

MQTT协议版本

bridge_mode
boolean
Default: false

如果启用桥接模式。
注意：此设置仅适用于 MQTT 协议版本早于5.0的情况，远程 MQTT
代理必须支持此功能。
如果将 bridge_mode 设置为true，则桥接将指示远程代理它是一个桥接而不是普通客户端。
这意味着循环检测将更加有效，并且保留的消息将被正确传递。

username
string

MQTT 协议的用户名

password
string <password>

MQTT 协议的密码

clean_start
boolean
Default: true

在重新连接到入口动作时是否启动新会话

keepalive
string
Default: "300s"

MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

retry_interval
string
Default: "15s"

Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

max_inflight
integer >= 0
Default: 32

MQTT 协议的最大 inflight（已发送但未确认）消息数

object (emqx.ssl_client_opts)

Responses

Request samples

Content type
application/json
{
  • "name": "my_http_connector",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Response samples

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

Get connector

通过 id 获取一个连接器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

连接器 id。必须是 {type}:{name} 的格式。

Responses

Response samples

Content type
application/json
{
  • "name": "my_http_connector",
  • "status": "connected",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "node_status": [
    ],
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Update connector

通过 id 更新一个连接器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

连接器 id。必须是 {type}:{name} 的格式。

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

是否启用该连接器。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

pool_size
integer >= 1
Default: 8

将发布消息到远程代理的 MQTT 客户端池的大小。

每个 MQTT 客户端都将分配'clientid'，格式为'${clientid_prefix}:${bridge_name}:egress:${node}:${n}'
其中'n'是池中客户端的编号。

object (connector_mqtt.resource_opts)
mode
string
Deprecated
Default: "cluster_shareload"
Value: "cluster_shareload"

MQTT 动作的模式。

- cluster_shareload：在 emqx 集群中的每个节点上创建一个 MQTT 连接。

在'cluster_shareload'模式下，来自远程代理的传入负载通过
使用共享订阅进行共享。

请注意，'clientid'将以节点名称作为后缀，以避免
不同节点之间的 clientid 冲突。并且我们只能使用共享订阅
作为入口连接的'remote.topic'的主题过滤器。

server
required
string

远程 MQTT 代理的主机和端口

clientid_prefix
string

附加到 egress 动作使用的 clientid 前缀（可选）。

reconnect_interval
string
Deprecated
proto_ver
string
Default: "v4"
Enum: "v3" "v4" "v5"

MQTT协议版本

bridge_mode
boolean
Default: false

如果启用桥接模式。
注意：此设置仅适用于 MQTT 协议版本早于5.0的情况，远程 MQTT
代理必须支持此功能。
如果将 bridge_mode 设置为true，则桥接将指示远程代理它是一个桥接而不是普通客户端。
这意味着循环检测将更加有效，并且保留的消息将被正确传递。

username
string

MQTT 协议的用户名

password
string <password>

MQTT 协议的密码

clean_start
boolean
Default: true

在重新连接到入口动作时是否启动新会话

keepalive
string
Default: "300s"

MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

retry_interval
string
Default: "15s"

Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

max_inflight
integer >= 0
Default: 32

MQTT 协议的最大 inflight（已发送但未确认）消息数

object (emqx.ssl_client_opts)

Responses

Request samples

Content type
application/json
{
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Response samples

Content type
application/json
{
  • "name": "my_http_connector",
  • "status": "connected",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "node_status": [
    ],
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Delete connector

通过 id 删除一个连接器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

连接器 id。必须是 {type}:{name} 的格式。

Responses

Response samples

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

Manually start a connector

在集群的所有节点上启动连接器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

连接器 id。必须是 {type}:{name} 的格式。

operation
required
string
Value: "start"
Example: start

集群可用操作：'start'。

Responses

Response samples

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

Manually start a connector on a given node

在特定节点上启动连接器。

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

节点名称，例如 'emqx@127.0.0.1'。

id
required
string
Example: http:my_http_connector

连接器 id。必须是 {type}:{name} 的格式。

operation
required
string
Value: "start"
Example: start

节点可用操作：'start'。

Responses

Response samples

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

Enable or disable connector

在集群的所有节点上启用或禁用连接器。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

连接器 id。必须是 {type}:{name} 的格式。

enable
required
boolean
Example: true

是否启用此连接器。

Responses

Response samples

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

List connectors

列出所有创建的连接器。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create connector

通过类型和名称创建一个新的连接器。

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

连接器的类型。

name
required
string

连接器的名称

enable
boolean
Default: true

是否启用该连接器。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

pool_size
integer >= 1
Default: 8

将发布消息到远程代理的 MQTT 客户端池的大小。

每个 MQTT 客户端都将分配'clientid'，格式为'${clientid_prefix}:${bridge_name}:egress:${node}:${n}'
其中'n'是池中客户端的编号。

object (connector_mqtt.resource_opts)
mode
string
Deprecated
Default: "cluster_shareload"
Value: "cluster_shareload"

MQTT 动作的模式。

- cluster_shareload：在 emqx 集群中的每个节点上创建一个 MQTT 连接。

在'cluster_shareload'模式下，来自远程代理的传入负载通过
使用共享订阅进行共享。

请注意，'clientid'将以节点名称作为后缀，以避免
不同节点之间的 clientid 冲突。并且我们只能使用共享订阅
作为入口连接的'remote.topic'的主题过滤器。

server
required
string

远程 MQTT 代理的主机和端口

clientid_prefix
string

附加到 egress 动作使用的 clientid 前缀（可选）。

reconnect_interval
string
Deprecated
proto_ver
string
Default: "v4"
Enum: "v3" "v4" "v5"

MQTT协议版本

bridge_mode
boolean
Default: false

如果启用桥接模式。
注意：此设置仅适用于 MQTT 协议版本早于5.0的情况，远程 MQTT
代理必须支持此功能。
如果将 bridge_mode 设置为true，则桥接将指示远程代理它是一个桥接而不是普通客户端。
这意味着循环检测将更加有效，并且保留的消息将被正确传递。

username
string

MQTT 协议的用户名

password
string <password>

MQTT 协议的密码

clean_start
boolean
Default: true

在重新连接到入口动作时是否启动新会话

keepalive
string
Default: "300s"

MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

retry_interval
string
Default: "15s"

Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

max_inflight
integer >= 0
Default: 32

MQTT 协议的最大 inflight（已发送但未确认）消息数

object (emqx.ssl_client_opts)

Responses

Request samples

Content type
application/json
{
  • "name": "my_http_connector",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Response samples

Content type
application/json
{
  • "name": "my_http_connector",
  • "status": "connected",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "node_status": [
    ],
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Sources

Manually start a bridge on a given node

在某个节点上启动数据桥接。

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

节点名称，例如： 'emqx@127.0.0.1'。

id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

operation
required
string
Value: "start"
Example: start

节点可用操作：'启动'。

Responses

Response samples

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

List sources

列出所有创建的数据桥接。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create source

通过类型和名称创建一个新的数据桥接。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"
name
required
string
enable
boolean
Default: true

是否启用此动作。

connector
required
string

由动作指定的连接器名称，用于选择外部资源。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

required
object (bridge_mqtt_publisher.ingress_parameters)
object (bridge_mqtt_publisher.source_resource_opts)

Responses

Request samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "status": "connected",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Get source

通过 id 获取一个数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Responses

Response samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "status": "connected",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Update source

通过 id 更新数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

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

是否启用此动作。

connector
required
string

由动作指定的连接器名称，用于选择外部资源。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

required
object (bridge_mqtt_publisher.ingress_parameters)
object (bridge_mqtt_publisher.source_resource_opts)

Responses

Request samples

Content type
application/json
{
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "status": "connected",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Delete source

通过 id 删除数据桥接

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

query Parameters
also_delete_dep_actions
boolean
Default: false

是否级联删除依赖的动作。

Responses

Response samples

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

List available source types

列出所有可用的数据源类型。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "mqtt"
]

Reset source metrics

通过 id 重置数据桥接指标。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Responses

Response samples

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

Enable or disable bridge

启用或禁用集群内所有节点上的数据桥接。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

enable
required
boolean
Example: true

是否启用该数据桥接。

Responses

Response samples

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

Test creating bridge

测试创建一个新的数据桥接。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"
name
required
string
enable
boolean
Default: true

是否启用此动作。

connector
required
string

由动作指定的连接器名称，用于选择外部资源。

tags
Array of strings

连接器的标签

description
string
Default: ""

描述性文本。

required
object (bridge_mqtt_publisher.ingress_parameters)
object (bridge_mqtt_publisher.source_resource_opts)

Responses

Request samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "resource_opts": {
    }
}

Response samples

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

Get source metrics

通过 id 来获取数据桥接的指标信息。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

Responses

Response samples

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

Manually start a bridge

启用集群中所有节点上的数据桥接。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

数据桥接 ID，格式必须为 {type}:{name}。

operation
required
string
Value: "start"
Example: start

集群可用操作：'启动'。

Responses

Response samples

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

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
}

Data Backup

Download a data backup file

Download a data backup file

Authorizations:
basicAuthbearerAuth
path Parameters
filename
required
string

Data backup file name

query Parameters
node
string

Node name

Responses

Response samples

Content type
application/json
"binary"

Delete a data backup file

Delete a data backup file

Authorizations:
basicAuthbearerAuth
path Parameters
filename
required
string

Data backup file name

query Parameters
node
string

Node name

Responses

Response samples

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

Export a data backup file

Export a data backup file

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "size": 22740,
  • "filename": "emqx-export-2023-11-23-19-13-19.043.tar.gz",
  • "created_at": "2023-11-23T19:13:19+02:00",
  • "created_at_sec": 1700759599
}

Import a data backup file

Import a data backup file

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

Node name

filename
required
string

Data backup file name

Responses

Request samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "filename": "emqx-export-2023-11-23-19-13-19.043.tar.gz"
}

Response samples

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

List backup files

List backup files

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Upload a data backup file

Upload a data backup file

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

Responses

Response samples

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

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

向一个节点发送加入集群的邀请，但不等待加入结果。加入状态可以通过 `GET api/<version

向一个节点发送加入集群的邀请，但不等待加入结果。加入状态可以通过 GET api/<version>/invitation 获取。

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

邀请节点加入集群

邀请节点加入集群

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

node name

Request Body schema: application/json
timeout
integer >= 0

Timeout in milliseconds

Responses

Request samples

Content type
application/json
{
  • "timeout": "15000"
}

Response samples

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

获取 RLOG 集群拓扑：核心节点与副本节点之间的连接。

获取 RLOG 集群拓扑：核心节点与副本节点之间的连接。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

获取每个节点所有异步邀请状态的执行状态

获取每个节点所有异步邀请状态的执行状态

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "succeed": [
    ],
  • "in_progress": [
    ],
  • "failed": [
    ]
}

Gateway Clients

Get client info

获取客户端信息

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

网关名称

Responses

Response samples

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

Kick out client

踢出指定客户端

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

网关名称

Responses

Response samples

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

List client's subscription

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

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

网关名称

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Add subscription for client

为某客户端新增订阅关系

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

客户端 ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

网关名称

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,
  • "topic": "test/topic",
  • "qos": 1,
  • "rap": 0,
  • "rh": 0
}

Response samples

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

Delete client's subscription

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

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

主题过滤器或主题名称

clientid
required
string

客户端 ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

网关名称

Responses

Response samples

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

List gateway's clients

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

网关名称

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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

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

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

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
rule_engine.ctx_message_transformation_failed (object) or rule_engine.ctx_schema_validation_failed (object) or rule_engine.ctx_delivery_dropped (object) or rule_engine.ctx_bridge_mqtt (object) or rule_engine.ctx_check_authn_complete (object) or rule_engine.ctx_check_authz_complete (object) or rule_engine.ctx_connack (object) or rule_engine.ctx_disconnected (object) or rule_engine.ctx_connected (object) or rule_engine.ctx_dropped (object) or rule_engine.ctx_acked (object) or rule_engine.ctx_delivered (object) or rule_engine.ctx_unsub (object) or rule_engine.ctx_sub (object) or rule_engine.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"
}

Apply a rule for testing

依据指定的消息内容和运行环境执行相应的规则。

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
rule_engine.ctx_message_transformation_failed (object) or rule_engine.ctx_schema_validation_failed (object) or rule_engine.ctx_delivery_dropped (object) or rule_engine.ctx_bridge_mqtt (object) or rule_engine.ctx_check_authn_complete (object) or rule_engine.ctx_check_authz_complete (object) or rule_engine.ctx_connack (object) or rule_engine.ctx_disconnected (object) or rule_engine.ctx_connected (object) or rule_engine.ctx_dropped (object) or rule_engine.ctx_acked (object) or rule_engine.ctx_delivered (object) or rule_engine.ctx_unsub (object) or rule_engine.ctx_sub (object) or rule_engine.ctx_pub (object)
Default: {}

测试事件的上下文

stop_action_after_template_rendering
boolean
Default: true

如果操作在模板渲染后应该停止，请将此设置为 true（默认为 true）。

Responses

Request samples

Content type
application/json
{
  • "context": { },
  • "stop_action_after_template_rendering": true
}

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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

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 数据桥接的引用，也可以是一个指向函数的对象。
我们支持一些内置函数，如“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"
}

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 数据桥接的引用，也可以是一个指向函数的对象。
我们支持一些内置函数，如“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": { }
}

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

获取规则引擎配置。

获取规则引擎配置。

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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

Responses

Response samples

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

Load or update the gateway confs

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

Request Body schema: application/json
One of
object (gateway.stomp_frame)
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
{
  • "enable": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "mountpoint": "coap2/",
  • "enable_stats": true,
  • "connection_required": false,
  • "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

Response samples

Content type
application/json
[
  • {
    }
]

清除所有 trace

清除所有 trace

Authorizations:
basicAuthbearerAuth

Responses

创建 trace

创建 trace

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

日志追踪的唯一名字。只允许使用小写字母 a-z、大写字母 A-Z、数字 0-9 和下划线 '_'。

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

过滤器类型

topic
string

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

clientid
string

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

ip_address
string

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

ruleid
string
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 时间戳格式

integer or string

rfc3339 或者 epoch 时间戳格式

string or string

用于格式化追踪日志条目的格式处理器。设置为 text 将日志条目格式化为纯文本（默认）。设置为 json 将每个日志条目格式化为 JSON 对象。

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "ruleid": "my_rule",
  • "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": [
    ],
  • "formatter": "text"
}

查看 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",
  • "ruleid": "my_rule",
  • "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": [
    ],
  • "formatter": "text"
}

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",
  • "backend": "local"
}

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 用户名

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",
  • "backend": "local"
}

删除 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
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" "actions" "connectors"

Responses

Response samples

Content type
application/json
"string"

Dashboard 用户退出登录

Dashboard 用户退出登录

Authorizations:
bearerAuth
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 (emqx.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

zone
string
Default: "default"

监听器所属的配置 zone。
连接到此监听器的客户端将继承在此 zone 名称下创建的 zone 设置。

一个 zone 可以覆盖以下根名称下的配置：
- mqtt
- force_shutdown
- force_gc
- flapping_detect
- durable_sessions

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

配置为 true 时将对启用客户端身份认证，只有通过认证的客户端才会被允许接入。

配置为 false 时，将不对客户端做任何身份检查，任何客户端都可以直接接入。

配置为 quick_deny_anonymous 时，EMQX 将直接拒绝未指定用户名的匿名客户端，不会对这些客户端进行任何身份检查，其余行为同 true。

max_conn_rate
string
Default: "infinity"

用于限制当前监听器接受连接的速率。一旦达到限制，EMQX 将暂停从 Accept 队列获取连接，从而推迟或拒绝新的连接。
例如：

- 1000/s：每秒只接受 1000 个连接。

- 1000/10s：每 10 秒只接受 1000 个连接。

messages_rate
string

用于限制单个客户端每秒可以向 EMQX 发送的消息数。一旦达到限制，EMQX 将暂停从接收缓冲区读取数据，从而使发送方减速甚至暂时挂起。
例如：

- 500/s：每秒只接收 500 条消息，剩余的消息消息将被推迟。

- 500/10s：每 10 秒只接收 500 条消息，剩余的消息消息将被推迟。

bytes_rate
string

用于限制单个客户端每秒可以向 EMQX 发送的字节数。一旦达到限制，EMQX 将暂停从接收缓冲区读取数据，从而使发送方减速甚至暂时挂起。
字节的单位可以是：KB、MB、GB。
例如：

- 500KB/s：每秒只接受 500 千字节，剩余的字节将被推迟。。

- 500MB/10s：每 10 秒只接收 500 兆字节，剩余的字节将被推迟。

Responses

Request samples

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

Response samples

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

在所有节点上停止指定 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
{
  • "id": "tcp:demo",
  • "running": true,
  • "type": "tcp",
  • "bind": "0.0.0.0:1884",
  • "tcp_options": {
    },
  • "max_connections": 204800,
  • "access_rules": [
    ],
  • "acceptors": 16,
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "zone": "default",
  • "mountpoint": "/",
  • "current_connections": 10240
}

为集群中所有的节点更新指定 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

zone
string
Default: "default"

监听器所属的配置 zone。
连接到此监听器的客户端将继承在此 zone 名称下创建的 zone 设置。

一个 zone 可以覆盖以下根名称下的配置：
- mqtt
- force_shutdown
- force_gc
- flapping_detect
- durable_sessions

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

配置为 true 时将对启用客户端身份认证，只有通过认证的客户端才会被允许接入。

配置为 false 时，将不对客户端做任何身份检查，任何客户端都可以直接接入。

配置为 quick_deny_anonymous 时，EMQX 将直接拒绝未指定用户名的匿名客户端，不会对这些客户端进行任何身份检查，其余行为同 true。

max_conn_rate
string
Default: "infinity"

用于限制当前监听器接受连接的速率。一旦达到限制，EMQX 将暂停从 Accept 队列获取连接，从而推迟或拒绝新的连接。
例如：

- 1000/s：每秒只接受 1000 个连接。

- 1000/10s：每 10 秒只接受 1000 个连接。

messages_rate
string

用于限制单个客户端每秒可以向 EMQX 发送的消息数。一旦达到限制，EMQX 将暂停从接收缓冲区读取数据，从而使发送方减速甚至暂时挂起。
例如：

- 500/s：每秒只接收 500 条消息，剩余的消息消息将被推迟。

- 500/10s：每 10 秒只接收 500 条消息，剩余的消息消息将被推迟。

bytes_rate
string

用于限制单个客户端每秒可以向 EMQX 发送的字节数。一旦达到限制，EMQX 将暂停从接收缓冲区读取数据，从而使发送方减速甚至暂时挂起。
字节的单位可以是：KB、MB、GB。
例如：

- 500KB/s：每秒只接受 500 千字节，剩余的字节将被推迟。。

- 500MB/10s：每 10 秒只接收 500 兆字节，剩余的字节将被推迟。

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

由字符串规则组成的访问规则列表，以限制或允许某些地址的访问，规则之间存在前后顺序，格式为 allow | deny <address> | <CIDR> | all。
例如：
["deny 192.168.1.1", "allow 192.168.1.0/24", "deny, all"]。

proxy_protocol
boolean
Default: false

如果为 EMQX 部署了反向代理，且代理处启用了 PROXY 协议以传递客户端真实 IP 时，则需要一并开启此选项，以便 EMQX 从 PROXY 协议标头中提取客户端真实 IP。EMQX 将自动检测 PROXY 协议的版本，支持 V1 和 V2。

PROXY 协议的详细说明，请参考：https://www.haproxy.com/blog/haproxy/proxy-protocol/。

proxy_protocol_timeout
string
Default: "3s"

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

object (emqx.tcp_opts)
object (emqx.listener_wss_opts)
object (emqx.ws_opts)

Responses

Request samples

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

Response samples

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

删除所有节点上指定 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"
}

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

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Gateway Authentication

Get authenticator configuration

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

Responses

Response samples

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

Update authenticator configuration

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

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

认证方式。

backend
required
string
Value: "ldap"

后端类型。

query_timeout
string
Default: "5s"

LDAP 查询的超时时间。

enable
boolean
Default: true

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

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

指示哪个属性用于表示用户密码。

is_superuser_attribute
string
Default: "isSuperuser"

指示哪个属性用于表示用户是否为超级用户。

Responses

Request samples

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

Response samples

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

Delete gateway authenticator

删除指定网关的认证器。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

Responses

Response samples

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

Create authenticator for gateway

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

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

网关名称.

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

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

认证方式。

backend
required
string
Value: "ldap"

后端类型。

query_timeout
string
Default: "5s"

LDAP 查询的超时时间。

enable
boolean
Default: true

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

server
required
string

要连接的 IPv4 或 IPv6 地址或主机名。

主机名条目的格式为：主机[:端口]。

如果 [:端口] 未指定， 将使用 LDAP 默认端口 389。

pool_size
integer >= 1
Default: 8

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

username
required
string

内部数据库的用户名。

password
string <password>

内部数据库密码。

base_dn
required
string

与基本对象条目（或根）相关的名称。
搜索用户的起点。

filter
string
Default: "(objectClass=mqttUser)"

定义哪些条件必须被依次满足的过滤器
用于搜索匹配一条给定的条目.

筛选器的语法遵循 RFC 4515，并且还支持占位符。

request_timeout
string
Default: "10s"

设置每个单独请求所使用的最大时间（以毫秒为单位）。

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

指示哪个属性用于表示用户密码。

is_superuser_attribute
string
Default: "isSuperuser"

指示哪个属性用于表示用户是否为超级用户。

Responses

Request samples

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

Response samples

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

Import users

导入用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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": {
    }
}

Get user info for gateway authenticator

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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": {
    }
}

Delete user for gateway authenticator

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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"
}

Import users

导入用户（仅支持 built_in_database 类型的认证器）

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
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"
}

Durable storage

Add site as a replica for the durable storage

Add site as a replica for the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Value: "messages"
Example: messages

Durable storage ID

site
required
string
Example: AFA18CB1C22F0157

Site ID

Responses

Response samples

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

Remove site as a replica for the durable storage

Remove site as a replica for the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Value: "messages"
Example: messages

Durable storage ID

site
required
string
Example: AFA18CB1C22F0157

Site ID

Responses

Response samples

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

List durable storages

List durable storages

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "string"
]

List sites

List sites

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "string"
]

List replicas of the durable storage

List replicas of the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Value: "messages"
Example: messages

Durable storage ID

Responses

Response samples

Content type
application/json
[
  • "string"
]

Update replicas of the durable storage

Update replicas of the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Value: "messages"
Example: messages

Durable storage ID

Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • "string"
]

Get sites

Get sites

Authorizations:
basicAuthbearerAuth
path Parameters
site
required
string
Example: AFA18CB1C22F0157

Site ID

Responses

Response samples

Content type
application/json
{
  • "node": "'emqx@example.com'",
  • "up": true,
  • "shards": [
    ]
}

Get durable storage

Get durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Value: "messages"
Example: messages

Durable storage ID

Responses

Response samples

Content type
application/json
{
  • "name": "messages",
  • "shards": [
    ]
}

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
topic
string

主题过滤器，支持通配符，省略此项以匹配所有消息。

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

删除所有保留消息

删除所有保留消息

Authorizations:
basicAuthbearerAuth

Responses

不支持主题通配符

不支持主题通配符

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
path Parameters
topic
required
string

主题

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "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 则表示保留消息永不过期。但如果 MQTT 消息中指定了 Message-Expiry-Interval 属性，则以该属性的值为准。

msg_clear_interval
string
Default: "0s"

检查并清除过期保留消息的时间间隔。这可以避免已经过期的保留消息仍然被长时间地存储。
如果 msg_clear_interval 设置为 0，即不主动定期检查过期的保留消息，EMQX 将只在准备投递时检查并删除已经过期的保留消息。

max_payload_size
string
Default: "1MB"

允许存储的保留消息的最大大小。EMQX 将拒绝存储超过此大小的保留消息，并输出一条包含 'retain_failed_for_payload_size_exceeded_limit' 关键字的 Error 日志。
0 表示不限制保留消息大小。

stop_publish_clear_msg
boolean
Default: false

当 PUBLISH 消息的保留标志被设置且有效载荷为空时，是否继续发布消息。
参见：
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718038

delivery_rate
string
Default: "1000/s"

发送保留消息的最大速率。

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
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

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

Results per page(max 10000)

activated
boolean

用于指定查询的告警类型，
为 true 时返回当前激活的告警，为 false 时返回历史告警，默认为 false。

Responses

Response samples

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

删除所有历史告警。

删除所有历史告警。

Authorizations:
basicAuthbearerAuth

Responses

Subscriptions

获取集群的订阅列表。

获取集群的订阅列表。

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

Page number of the results to fetch.

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

Results per page(max 10000)

node
string
Example: node=emqx@172.17.0.2

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

durable
boolean

Filter subscriptions by durability

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"

消息时延大于此阈值的消费端 Client ID 与主题将被记录到慢订阅列表中。

expire_interval
string
Default: "300s"

慢订阅记录的过期时间，如果记录在过期时间内没有更新，那么该记录将被删除。

top_k_num
integer >= 1
Default: 10

慢订阅记录的最大数量，最大不能超过 1000。

stats_type
string
Default: "whole"
Enum: "whole" "internal" "response"

消息时延的计算方式：
- whole：从消息到达 EMQX（EMQX 从接收缓冲区取得消息）开始，到消息完成传输的时间。
- internal：从消息到达 EMQX（EMQX 从接收缓冲区取得消息）开始，到消息开始投递（EMQX 尝试向发送缓冲区写入消息）的时间。
- response：从消息开始投递开始，到消息完成传输的时间。
注：消息完成传输时间指的是 QoS 1、2 消息完成 MQTT 报文响应流程时间，即 QoS 1 消息收到 PUBACK 报文，QoS 2 消息收到 PUBCOMP 报文的时间。QoS 0 消息由于无响应报文，所以 QoS 0 消息的完成传输时间均以消息开始投递时间代替。因此使用 response 方式统计时延时，QoS 0 消息的时延将永远等于 0。

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
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

清除当前记录，然后重新开始统计

清除当前记录，然后重新开始统计

Authorizations:
basicAuthbearerAuth

Responses

API Keys

查看 API 密钥列表

查看 API 密钥列表

Authorizations:
bearerAuth

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
}

创建一个新的 API 密钥

创建一个新的 API 密钥

Authorizations:
bearerAuth
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
}

指定 API 密钥 ID 获取详情

指定 API 密钥 ID 获取详情

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
}

指定 API 密钥 ID 进行更新

指定 API 密钥 ID 进行更新

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
}

指定 API 密钥 ID 进行删除

指定 API 密钥 ID 进行删除

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

Banned

列出目前所有被封禁的客户端 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 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

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

清除全部黑名单数据。

清除全部黑名单数据。

Authorizations:
basicAuthbearerAuth

Responses

添加一个客户端 ID、用户名或者 IP 地址到黑名单。

添加一个客户端 ID、用户名或者 IP 地址到黑名单。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"

封禁方式，可以通过客户端 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" "clientid_re" "username_re" "peerhost_net"
Example: username

封禁方式，可以通过客户端 ID、用户名或者 IP 地址等方式进行封禁。

who
required
string
Example: Badass

封禁对象，具体的客户端 ID、用户名或者 IP 地址。

Responses

Response samples

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