< EMQX Dedicated latest API Documentation 反馈文档问题
API docs by Redocly

EMQX Dedicated REST API (v5)

Download OpenAPI specification:

EMQX Dedicated REST API

Banned

清除全部黑名单数据。

清除全部黑名单数据。

Authorizations:
basicAuthbearerAuth

Responses

列出目前所有被封禁的客户端 ID、用户名和 IP 地址。

列出目前所有被封禁的客户端 ID、用户名和 IP 地址。

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

要获取的结果所在页码。

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

每页返回的结果数量。

clientid
string

使用精确的客户端 ID 查询封禁规则。

username
string

使用精确的用户名查询封禁规则。

peerhost
string
Example: peerhost=127.0.0.1

使用精确的 IP 地址查询封禁规则。

like_clientid
string

使用客户端 ID 正则表达式来匹配查询封禁规则。

like_username
string

使用用户名正则表达式来匹配查询封禁规则。

like_peerhost
string
Example: like_peerhost=127.0.0.1

使用 IP 地址正则表达式来匹配查询封禁规则。

like_peerhost_net
string
Example: like_peerhost_net=192.1.0.0/16

使用 CIDR 正则表达式来匹配查询封禁规则。

Responses

Response samples

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

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

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

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

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

integer or string

封禁的起始时间，格式为 rfc3339，默认为发起操作的时间。

by
string

封禁的发起者。

reason
string

封禁原因，记录当前对象被封禁的原因。

(integer or string) or string
Default: "infinity"

封禁的结束时间，格式为 rfc3339，默认值为发起操作的时间 + 1 年。

who
required
string

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

Responses

Request samples

Content type
application/json
{
  • "as": "username",
  • "at": "2021-10-25T21:48:47+08:00",
  • "by": "mgmt_api",
  • "reason": "Too many requests",
  • "until": "2030-11-11T10:24:00+08:00",
  • "who": "Banned name"
}

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

Clients

批量取消订阅

批量取消订阅

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

主题名称。

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
nl
integer
Default: 0

MQTT No Local 选项，控制客户端是否接收自己发布的消息。

qos
integer [ 0 .. 2 ]
Default: 0

消息服务质量（QoS）

rap
integer
Default: 0

客户端是否按原始发布方式保留 MQTT 保留消息的 Retain 标志。

rh
integer
Default: 0

保留消息处理（Retain handling）。

topic
required
string

主题名称。

Responses

Request samples

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

Response samples

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

踢出指定客户端

踢出指定客户端

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

列出客户端

列出客户端

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

要获取的结果所在页码。

node
string
Example: node=emqx@127.0.0.1

节点名称

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

每页返回的结果数量。

username
Array of strings

客户端连接时使用的用户名称。

ip_address
string
Example: ip_address=127.0.0.1

客户端的 IP 地址。

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

客户端的当前连接状态，可能的值包括：connected（已连接）、idle（空闲）、disconnected（已断开）。

clean_start
boolean

指示客户端是否使用全新的会话。

proto_ver
string

客户端使用的协议版本

like_clientid
string

模糊搜索 clientid 作为子字符串。

like_username
string

模糊搜索 username 作为子字符串。

integer or string

按大于或等于的方法搜索客户端会话创建时间，格式为 RFC3339 或时间戳（毫秒）。

integer or string

按小于或等于的方法搜索客户端会话创建时间，格式为 RFC3339 或时间戳（毫秒）。

integer or string

按大于或等于的方法搜索客户端连接创建时间，格式为 RFC3339 或时间戳（毫秒）。

integer or string

按小于或等于的方法搜索客户端连接创建时间，格式为 RFC3339 或时间戳（毫秒）。

clientid
Array of strings

客户端 ID。

Array of strings or string
Default: "all"

请求在响应中返回的客户端字段，多个字段以逗号分隔。

Responses

Response samples

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

获取指定客户端的订阅列表

获取指定客户端的订阅列表

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

取消订阅

取消订阅

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

主题名称。

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
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

客户端的 Inflight/MQueue 消息的 payload 编码格式。

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

客户端的未确认消息（inflight）/ 消息队列（mqueue）消息 payload 限制。
返回的所有消息总负载大小不会超过此值。
超出限制的消息将在响应中被静默省略。
唯一的例外是当第一条消息的负载已超过限制时，在这种情况下，该消息仍会被返回。

string or string or string
Example: position=none

一个不透明的 token，可用于后续请求以获取下一批结果：?position={prev_response.meta.position}。
用于替代 page 参数以遍历高度动态的数据。可以省略或设置为 none 以获取第一批数据。

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

每页返回的结果数量。

Responses

Response samples

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

批量订阅

批量订阅

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
nl
integer
Default: 0

MQTT No Local 选项，控制客户端是否接收自己发布的消息。

qos
integer [ 0 .. 2 ]
Default: 0

消息服务质量（QoS）

rap
integer
Default: 0

客户端是否按原始发布方式保留 MQTT 保留消息的 Retain 标志。

rh
integer
Default: 0

保留消息处理（Retain handling）。

topic
required
string

主题名称。

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

通过客户端 ID 批量踢出客户端

通过客户端 ID 批量踢出客户端

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

Responses

Request samples

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

获取客户端未确认消息。

获取客户端未确认消息。

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

客户端的 Inflight/MQueue 消息的 payload 编码格式。

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

客户端的未确认消息（inflight）/ 消息队列（mqueue）消息 payload 限制。
返回的所有消息总负载大小不会超过此值。
超出限制的消息将在响应中被静默省略。
唯一的例外是当第一条消息的负载已超过限制时，在这种情况下，该消息仍会被返回。

string or string or string
Example: position=none

一个不透明的 token，可用于后续请求以获取下一批结果：?position={prev_response.meta.position}。
用于替代 page 参数以遍历高度动态的数据。可以省略或设置为 none 以获取第一批数据。

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

每页返回的结果数量。

Responses

Response samples

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

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

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

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

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

Connectors

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

Test creating connector

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

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string or string
Default: "none"

认证配置。
- none：无认证。
- msk_iam：使用 MSK IAM 认证。注意：这仅在 EMQX 运行在 EC2 实例上时有效。
- basic auth：简单的用户名和密码认证。
- kerberos：使用 Kerberos GSSAPI 认证。

bootstrap_hosts
required
string

用逗号分隔的 host[:port] 主机列表。默认端口号为 9092。

connect_timeout
string
Default: "5s"

建立 TCP 连接时的最大等待时长（若启用认证，这个等待时长也包含完成认证所需时间）。

description
string
Default: ""

描述性文本。

enable
boolean
Default: true

启用 (是) 或 停用 (否) 该连接器。

metadata_request_timeout
string
Default: "5s"

刷新元数据时最大等待时长。

min_metadata_refresh_interval
string
Default: "3s"

刷新 Kafka broker 和 Kafka 主题元数据段最短时间间隔。设置太小可能会增加 Kafka 压力。

name
required
string

连接器的名称

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

连接器的标签

type
required
string
Value: "kafka_consumer"

连接器的类型。

Responses

Request samples

Content type
application/json
Example
{
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "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"
}

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

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
Example
{
  • "actions": [
    ],
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "node_status": [
    ],
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string or string
Default: "none"

认证配置。
- none：无认证。
- msk_iam：使用 MSK IAM 认证。注意：这仅在 EMQX 运行在 EC2 实例上时有效。
- basic auth：简单的用户名和密码认证。
- kerberos：使用 Kerberos GSSAPI 认证。

bootstrap_hosts
required
string

用逗号分隔的 host[:port] 主机列表。默认端口号为 9092。

connect_timeout
string
Default: "5s"

建立 TCP 连接时的最大等待时长（若启用认证，这个等待时长也包含完成认证所需时间）。

description
string
Default: ""

描述性文本。

enable
boolean
Default: true

启用 (是) 或 停用 (否) 该连接器。

metadata_request_timeout
string
Default: "5s"

刷新元数据时最大等待时长。

min_metadata_refresh_interval
string
Default: "3s"

刷新 Kafka broker 和 Kafka 主题元数据段最短时间间隔。设置太小可能会增加 Kafka 压力。

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

连接器的标签

Responses

Request samples

Content type
application/json
Example
{
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
Example
{
  • "actions": [
    ],
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "node_status": [
    ],
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

List connectors

列出所有创建的连接器。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create connector

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

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string or string
Default: "none"

认证配置。
- none：无认证。
- msk_iam：使用 MSK IAM 认证。注意：这仅在 EMQX 运行在 EC2 实例上时有效。
- basic auth：简单的用户名和密码认证。
- kerberos：使用 Kerberos GSSAPI 认证。

bootstrap_hosts
required
string

用逗号分隔的 host[:port] 主机列表。默认端口号为 9092。

connect_timeout
string
Default: "5s"

建立 TCP 连接时的最大等待时长（若启用认证，这个等待时长也包含完成认证所需时间）。

description
string
Default: ""

描述性文本。

enable
boolean
Default: true

启用 (是) 或 停用 (否) 该连接器。

metadata_request_timeout
string
Default: "5s"

刷新元数据时最大等待时长。

min_metadata_refresh_interval
string
Default: "3s"

刷新 Kafka broker 和 Kafka 主题元数据段最短时间间隔。设置太小可能会增加 Kafka 压力。

name
required
string

连接器的名称

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

连接器的标签

type
required
string
Value: "kafka_consumer"

连接器的类型。

Responses

Request samples

Content type
application/json
Example
{
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
Example
{
  • "actions": [
    ],
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "node_status": [
    ],
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

Rules

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

action
Array of strings

筛选包含任意给定动作 ID 的规则。当与 source ID 筛选一起使用时，规则必须包含匹配某些条件的 source 和动作。

source
Array of strings

筛选包含任意给定 source ID 的规则。当与动作 ID 筛选一起使用时，规则必须包含匹配某些条件的 source 和动作。

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

要获取的结果所在页码。

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

每页返回的结果数量。

Responses

Response samples

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

Create a rule

通过指定 ID 创建规则

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
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}”。
列表中的动作按顺序执行。这意味着如果其中一个动作执行缓慢，则以下所有动作都不会被执行直到它返回。
如果其中一个动作崩溃，在它之后的所有动作仍然会被按照原始顺序执行。
如果运行动作时出现任何错误，则会出现错误消息，并且相应的计数器会增加。

description
string
Default: ""

规则的描述

enable
boolean
Default: true

启用或禁用规则引擎

metadata
object

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

name
string
Default: ""

规则名字

sql
required
string

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

Responses

Request samples

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

Response samples

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

Delete rule

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

Get rule

通过 ID 查询规则

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

Update rule

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
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}”。
列表中的动作按顺序执行。这意味着如果其中一个动作执行缓慢，则以下所有动作都不会被执行直到它返回。
如果其中一个动作崩溃，在它之后的所有动作仍然会被按照原始顺序执行。
如果运行动作时出现任何错误，则会出现错误消息，并且相应的计数器会增加。

description
string
Default: ""

规则的描述

enable
boolean
Default: true

启用或禁用规则引擎

metadata
object

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

name
string
Default: ""

规则名字

sql
required
string

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

Responses

Request samples

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

Response samples

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

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

List rule events

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Apply a rule for testing

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
rule_engine.ctx_unsub (object) or rule_engine.ctx_sub (object) or rule_engine.ctx_schema_validation_failed (object) or rule_engine.ctx_message_transformation_failed (object) or rule_engine.ctx_pub (object) or rule_engine.ctx_dropped (object) or rule_engine.ctx_delivered (object) or rule_engine.ctx_acked (object) or rule_engine.ctx_delivery_dropped (object) or rule_engine.ctx_disconnected (object) or rule_engine.ctx_connected (object) or rule_engine.ctx_connack (object) or rule_engine.ctx_check_authz_complete (object) or rule_engine.ctx_check_authn_complete (object) or rule_engine.ctx_alarm_deactivated (object) or rule_engine.ctx_alarm_activated (object) or rule_engine.ctx_bridge_mqtt (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"
}

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

Authorization

删除 'all' 规则

删除 'all' 规则

Authorizations:
basicAuthbearerAuth

Responses

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

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

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

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

Responses

Request samples

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

Response samples

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

显示客户端规则列表。

显示客户端规则列表。

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

要获取的结果所在页码。

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

每页返回的结果数量。

like_clientid
string

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

Responses

Response samples

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

为指定客户端添加规则。

为指定客户端添加规则。

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

客户端 ID

Array of objects (emqx_authz_api_mnesia.rule_item)

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

要获取的结果所在页码。

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

每页返回的结果数量。

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

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

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

删除指定用户名的规则

删除指定用户名的规则

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

用户名

Responses

Response samples

Content type
application/json
{
  • "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
clientid
required
string
Example: client1

客户端 ID

Responses

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
{
  • "clientid": "client1",
  • "rules": [
    ]
}

设置指定客户端的规则

设置指定客户端的规则

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

客户端 ID

Request Body schema: application/json
clientid
required
string

客户端 ID

Array of objects (emqx_authz_api_mnesia.rule_item)

Responses

Request samples

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

Response samples

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

Actions

List bridges

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create bridge

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

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
connector
required
string

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

description
string
Default: ""

描述性文本。

enable
boolean
Default: true

启用（是）或停用（否）此动作。

Array of actions_and_sources.fallback_action_republish (object) or actions_and_sources.fallback_action_reference (object)
Default: []

如果此操作的查询失败，将触发的回退操作列表。

local_topic
string

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

name
required
string
required
object (action_disk_log.action_parameters)
object (actions_and_sources.action_resource_opts)
tags
Array of strings

连接器的标签

type
required
string
Value: "disk_log"

Responses

Request samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

Summarize actions

汇总动作

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available action types

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "http",
  • "cassandra",
  • "rabbitmq",
  • "rocketmq",
  • "syskeeper_forwarder",
  • "mongodb",
  • "iotdb",
  • "greptimedb",
  • "hstreamdb",
  • "confluent_producer",
  • "azure_event_hub_producer",
  • "gcp_pubsub_producer",
  • "sqlserver",
  • "pulsar",
  • "kafka_producer",
  • "influxdb",
  • "redis",
  • "datalayers",
  • "opents",
  • "s3tables",
  • "doris",
  • "kinesis",
  • "s3",
  • "mqtt",
  • "tdengine",
  • "timescale",
  • "snowflake",
  • "couchbase",
  • "oracle",
  • "clickhouse",
  • "azure_blob_storage",
  • "tablestore",
  • "disk_log",
  • "elasticsearch",
  • "matrix",
  • "pgsql",
  • "mysql",
  • "dynamo"
]

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

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

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

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
{
  • "code": "BAD_REQUEST",
  • "message": "string",
  • "rules": [
    ]
}

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
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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
connector
required
string

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

description
string
Default: ""

描述性文本。

enable
boolean
Default: true

启用（是）或停用（否）此动作。

Array of actions_and_sources.fallback_action_republish (object) or actions_and_sources.fallback_action_reference (object)
Default: []

如果此操作的查询失败，将触发的回退操作列表。

local_topic
string

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

required
object (action_disk_log.action_parameters)
object (actions_and_sources.action_resource_opts)
tags
Array of strings

连接器的标签

Responses

Request samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "parameters": {
    },
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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

Test creating bridge

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

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
connector
required
string

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

description
string
Default: ""

描述性文本。

enable
boolean
Default: true

启用（是）或停用（否）此动作。

Array of actions_and_sources.fallback_action_republish (object) or actions_and_sources.fallback_action_reference (object)
Default: []

如果此操作的查询失败，将触发的回退操作列表。

local_topic
string

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

name
required
string
required
object (action_disk_log.action_parameters)
object (actions_and_sources.action_resource_opts)
tags
Array of strings

连接器的标签

type
required
string
Value: "disk_log"

Responses

Request samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "type": "elasticsearch"
}

Response samples

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

Message Transformation

Enable or disable transformation

启用或停用一个特定的转换

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

转换名称

enable
required
boolean

启用或停用转换

Responses

Response samples

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

Test an input against a configuration

对输入数据进行转换测试

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
object (message_transformation_http_api.dryrun_input_message)
required
object (message_transformation.transformation)

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "transformation": {
    }
}

Response samples

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

Delete a transformation

删除一个转换

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

转换名称

Responses

Response samples

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

Lookup a transformation

查找一个转换

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

转换名称

Responses

Response samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

List transformations

列出转换

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Append a new transformation

向消息转换列表中添加新的转换

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

描述性文本。

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"
object (message_transformation.log_failure)
name
required
string
Array of objects (message_transformation.operation)
Default: []
string or string or string or string or string
Default: {"type":"none"}
string or string or string or string or string
Default: {"type":"none"}
tags
Array of strings

连接器的标签

required
Array of strings or string

Responses

Request samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Update a transformation

更新一个转换

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

描述性文本。

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"
object (message_transformation.log_failure)
name
required
string
Array of objects (message_transformation.operation)
Default: []
string or string or string or string or string
Default: {"type":"none"}
string or string or string or string or string
Default: {"type":"none"}
tags
Array of strings

连接器的标签

required
Array of strings or string

Responses

Request samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Get transformation metrics

获取一个特定转换的指标

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

转换名称

Responses

Response samples

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

Reorder all transformations

重新排序所有的消息转换

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
order
required
Array of strings

Responses

Request samples

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

Response samples

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

Reset transformation metrics

重置特定变换的指标

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

转换名称

Responses

Response samples

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

Schema Validation

List validations

列出验证规则。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Append a new validation

在验证规则列表中添加新的验证规则。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
Array of schema_validation.check_external_http (object) or schema_validation.check_protobuf (object) or schema_validation.check_avro (object) or schema_validation.check_json (object) or schema_validation.check_sql (object)

在验证过程中将执行的检查。它们将按照定义的顺序进行评估。

description
string
Default: ""

描述性文本。

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"

如果验证失败，将如何处理。

drop：违规消息将被直接丢弃，不进行进一步处理。
disconnect：消息不会被发布，发布客户端将被断开连接。
ignore：仅记录和追踪失败，不采取其他行动。

object (schema_validation.log_failure)
name
required
string

名称

strategy
required
string
Enum: "any_pass" "all_pass"

验证策略

tags
Array of strings

连接器的标签

required
Array of strings or string

此验证规则应验证的单个主题过滤器或主题过滤器列表。

Responses

Request samples

Content type
application/json
Example
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Update a validation

更新一条验证规则。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
Array of schema_validation.check_external_http (object) or schema_validation.check_protobuf (object) or schema_validation.check_avro (object) or schema_validation.check_json (object) or schema_validation.check_sql (object)

在验证过程中将执行的检查。它们将按照定义的顺序进行评估。

description
string
Default: ""

描述性文本。

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"

如果验证失败，将如何处理。

drop：违规消息将被直接丢弃，不进行进一步处理。
disconnect：消息不会被发布，发布客户端将被断开连接。
ignore：仅记录和追踪失败，不采取其他行动。

object (schema_validation.log_failure)
name
required
string

名称

strategy
required
string
Enum: "any_pass" "all_pass"

验证策略

tags
Array of strings

连接器的标签

required
Array of strings or string

此验证规则应验证的单个主题过滤器或主题过滤器列表。

Responses

Request samples

Content type
application/json
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Enable or disable validation

启用或停用某个特定验证规则。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

验证规则名称

enable
required
boolean

启用或停用验证规则。

Responses

Response samples

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

Get validation metrics

获取某个特定验证规则的指标。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

验证规则名称

Responses

Response samples

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

Reorder all validations

重新排序所有验证规则

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
order
required
Array of strings

Responses

Request samples

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

Response samples

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

Delete a validation

删除一条验证规则。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

验证规则名称

Responses

Response samples

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

Lookup a validation

查找一条验证规则

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

验证规则名称

Responses

Response samples

Content type
application/json
Example
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Reset validation metrics

重置某个特定验证规则的指标。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

验证规则名称

Responses

Response samples

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

Subscriptions

获取集群的订阅列表。

获取集群的订阅列表。

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

要获取的结果所在页码。

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

每页返回的结果数量。

node
string
Example: node=emqx@127.0.0.1

Node name

clientid
string

Client ID

qos
integer [ 0 .. 2 ]
Example: qos=0

QoS

topic
string

Topic, url encoding

match_topic
string

Match topic string, url encoding

share_group
string

Shared subscription group name

durable
boolean

Filter subscriptions by durability

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Schema Registry

Delete registered schema

删除一个 schema。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

Schema 的名称。

Responses

Response samples

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

Get registered schema

通过名称获取一个 schema。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

Schema 的名称。

Responses

Response samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "name": "my_avro_schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

Update a schema

更新一个现有的 schema。

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

Schema 的名称。

Request Body schema: application/json
One of
description
string
Default: ""

改 schema 的描述。

required
object (schema_registry.external_http_params)
type
required
string
Value: "external_http"

对于外部 HTTP，必须设置为 external_http。

Responses

Request samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

Response samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "name": "my_avro_schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

List registered schemas

列出所有已注册的 schema。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register a new schema

注册一个新的 schema。

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
description
string
Default: ""

改 schema 的描述。

name
required
string

Schema 的一个名称，将用作其标识符。

required
object (schema_registry.external_http_params)
type
required
string
Value: "external_http"

对于外部 HTTP，必须设置为 external_http。

Responses

Request samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "name": "my_avro_schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

Response samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "name": "my_avro_schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

Upload a Protobuf bundle for a new schema

为新 Schema 上传 Protobuf 包

Authorizations:
basicAuthbearerAuth
Request Body schema: multipart/form-data
bundle
string <binary>
description
string
name
string
root_proto_file
string

Responses

Response samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "name": "my_avro_schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

Upload a Protobuf bundle for an existing schema

为现有 Schema 上传 Protobuf 包

Authorizations:
basicAuthbearerAuth
Request Body schema: multipart/form-data
bundle
string <binary>
description
string
name
string
root_proto_file
string

Responses

Response samples

Content type
application/json
{
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

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
clientid
string
Deprecated
payload
required
string

MQTT 消息体.

payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT 消息体的编码方式，可以是 base64 或 plain。当设置为 base64 时，消息在发布前会先被解码，可以用于发布二进制等数据。

object (emqx_mgmt_api_publish.message_properties)
qos
integer [ 0 .. 2 ]
Default: 0

QoS

retain
boolean
Default: false

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

topic
required
string

主题

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
clientid
string
Deprecated
payload
required
string

MQTT 消息体.

payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT 消息体的编码方式，可以是 base64 或 plain。当设置为 base64 时，消息在发布前会先被解码，可以用于发布二进制等数据。

object (emqx_mgmt_api_publish.message_properties)
qos
integer [ 0 .. 2 ]
Default: 0

QoS

retain
boolean
Default: false

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

topic
required
string

主题

Responses

Request samples

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

Response samples

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

Authentication

删除内置数据库认证器中的指定用户数据。

删除内置数据库认证器中的指定用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
user_id
required
string

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

Responses

Response samples

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

获取内置数据库认证器中的指定用户数据。

获取内置数据库认证器中的指定用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
user_id
required
string

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

Responses

Response samples

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

更新内置数据库认证器中的指定用户数据。

更新内置数据库认证器中的指定用户数据。

Authorizations:
basicAuthbearerAuth
path Parameters
user_id
required
string

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

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

Responses

Request samples

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

Response samples

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

获取内置数据库认证器中的用户列表。

获取内置数据库认证器中的用户列表。

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

要获取的结果所在页码。

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

每页返回的结果数量。

like_user_id
string

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

is_superuser
boolean

是否是超级用户。

Responses

Response samples

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

向内置数据库认证器添加用户数据。

向内置数据库认证器添加用户数据。

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

Responses

Request samples

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

Response samples

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

为内置数据库认证器导入用户数据。

为内置数据库认证器导入用户数据。

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

The import file template type, enum with plain,hash

Request Body schema: application/json

Import body

object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "failed": 0,
  • "override": 0,
  • "skipped": 0,
  • "success": 0,
  • "total": 0
}

Retainer

删除所有保留消息

删除所有保留消息

Authorizations:
basicAuthbearerAuth

Responses

查看保留消息列表

查看保留消息列表

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

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

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

要获取的结果所在页码。

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

每页返回的结果数量。

Responses

Response samples

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

删除对应的消息

删除对应的消息

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

主题

Responses

Response samples

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

不支持主题通配符

不支持主题通配符

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

主题

Responses

Response samples

Content type
application/json
{
  • "from_clientid": "string",
  • "from_username": "string",
  • "msgid": "string",
  • "payload": "string",
  • "publish_at": "string",
  • "qos": 0,
  • "topic": "string"
}

Metrics

当前监控（统计）数据，例如整个集群中的连接数和连接速率。

当前监控（统计）数据，例如整个集群中的连接数和连接速率。

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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