部署管理 API

本页介绍如何通过平台 API 获取部署列表、查询部署详情和连接信息、启动和停止部署、创建部署，以及创建部署 API Key。

获取部署列表

URI

GET /deployments

TIP

该方法 60 分钟内只能请求 60 次。

请求消息

无

响应消息

200:

名称	类型	描述
connections	Number	连接数规格。
tps	Number	TPS 规格。
createAt	String	部署创建时间。
deploymentID	String	部署 ID。
deploymentName	String	部署名称。
deploymentType	String	部署类型，"serverless" 为 Serverless 版，"dedicated" 为专有版。
platform	String	云服务商。
projectName	String	项目名称。
region	String	云主机所在地区。
status	String	部署运行状态： "running" 为运行中， "starting" 为创建过程中， "stopped" 为停止状态。
version	String	部署版本。

401: API Key 认证失败。
403: API Key 没有权限访问。
429: 请求次数超过限制。

请求示例

bash

curl -u key:secret -X GET {api}/deployments

响应示例

JSON

[
    {
        "connections": 1000,
        "tps": 1000,
        "createAt": "2024-11-21 02:51",
        "deploymentID": "mdfba81f",
        "deploymentName": "deployment-mdfba81f",
        "deploymentType": "serverless",
        "platform": "阿里云",
        "projectName": "default",
        "region": "杭州",
        "status": "stopped",
        "version": "v5"
    },
    {
        "connections": 1000,
        "tps": 1000,
        "createAt": "2025-04-17 08:36",
        "deploymentID": "b1f77113",
        "deploymentName": "deployment-b1f77113",
        "deploymentType": "dedicated",
        "platform": "阿里云",
        "projectName": "test",
        "region": "杭州",
        "status": "running",
        "version": "v5"
    }
]

查询部署详情和连接信息

URI

GET /deployments/{deployment_id}

TIP

该方法 60 分钟内只能请求 60 次。{deployment_id} 为部署 ID，非部署名称。

请求消息

无

响应消息

200:

名称	类型	描述
connections	Number	连接数规格。
tps	Number	TPS 规格。
createAt	String	部署创建时间。
deploymentID	String	部署 ID。
deploymentName	String	部署名称。
deploymentType	String	部署类型，"dedicated" 为专有版。
platform	String	云服务商。
region	String	云主机所在地区。
status	String	部署运行状态： "running" 为运行中， "starting" 为创建过程中， "stopped" 为停止状态。
connection	Object 或 null	部署连接信息。部署处于运行中时，该对象包含连接地址、全部可用端口及其状态，以及 API 地址。部署未处于运行中时，该字段为 `null`。

401: API Key 认证失败。
403: API Key 没有权限访问。
404: 未找到部署。
429: 请求次数超过限制。

请求示例

bash

curl -u key:secret -X GET {api}/deployments/w41b11c0

响应示例

JSON

{
    "connections": 1000,
    "tps": 1000,
    "createAt": "2024-07-22 05:32",
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "deploymentType": "dedicated",
    "platform": "阿里云",
    "region": "杭州",
    "status": "running",
    "connection": {
        "address": "mqtt.example.com",
        "ports": [
            {"protocol": "mqtt", "port": 1883, "status": "running"},
            {"protocol": "mqtts", "port": 8883, "status": "running"},
            {"protocol": "ws", "port": 8083, "status": "running"},
            {"protocol": "wss", "port": 8084, "status": "running"}
        ],
        "apiEndpoint": "https://mqtt.example.com:8443/api/v5"
    }
}

以上地址和端口仅为示例，请使用目标部署实际返回的值，并仅连接 status 为 running 的端口。

对于未处于运行中的部署，响应中包含 "connection": null：

json

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "status": "stopped",
    "connection": null
}

创建部署 API Key

可以使用平台 API Key 为运行中的专有版或弹性专有版部署创建部署 API Key。Serverless 部署或未处于运行中的部署不支持此操作。

平台 API Key 必须具有 Deployment_API_Key 功能权限，并有权访问目标项目。目标部署必须属于同一账号。每个部署最多有 5 个部署 API Key；每个平台 API Key 每小时最多成功创建 2 个部署 API Key。

URI

POST /deployments/{deployment_id}/applications

{deployment_id} 为部署 ID，不是部署名称。

请求消息

请求体可省略。如果提供请求体，必须使用 application/json，并包含 whitelist 字段。

名称	类型	必填	描述
`whitelist`	Object	提供请求体时必填	部署 API 权限，格式为 API 路径到允许的 HTTP 方法数组的映射。指定的路径和方法必须是该部署可用权限的子集。
`description`	String 或 null	否	Key 描述，最多 128 个字符；省略时默认为空字符串。

例如，"/api/v5/clients": ["GET"] 仅授予查询客户端的权限。可以在同一白名单中为不同路径指定不同方法；未列出的权限不会授予新 Key。请根据部署实际可用的 API 权限，仅授予所需权限。

重要提示

不传请求体时，新 Key 将获得该部署的全部可用 API 权限。空 JSON 对象 {} 与不传请求体不同，会被拒绝。白名单无效或 Content-Type 错误时，请求也会被拒绝，且不会创建 Key。

响应消息

201: 创建成功。

名称	类型	描述
`appID`	String	新部署 API Key 的 App ID（AK）。
`appSecret`	String	新部署 API Key 的 App Secret（SK），仅在创建时返回一次。

400: 部署类型或状态不支持此操作、请求的权限不可用，或部署已达到 Key 数量上限。
401: 平台 API Key 认证失败。
403: 平台 API Key 缺少功能或目标项目权限。
404: 未找到部署。
415: 请求体的媒体类型不受支持。
422: 请求参数或请求体无效。
429: 请求次数超过限制。

请求示例

以下示例创建一个仅允许查询客户端及查询、创建内置认证用户的 Key。先将环境变量设置为平台 API 地址、平台 API Key 凭据和目标部署 ID。

bash

curl --user "$PLATFORM_API_KEY:$PLATFORM_API_SECRET" \
  -X POST "$PLATFORM_API_ENDPOINT/deployments/$DEPLOYMENT_ID/applications" \
  -H "Content-Type: application/json" \
  -d '{
    "whitelist": {
      "/api/v5/clients": ["GET"],
      "/api/v5/authentication/password_based:built_in_database/users": ["GET", "POST"]
    },
    "description": "Application API access"
  }'

PLATFORM_API_ENDPOINT 是以 /public_api/v1 结尾的平台 API 地址。示例中的 /api/v5/ 权限适用于提供这些权限的部署；实际可用路径和方法取决于部署。

响应示例

json

{
  "appID": "example-app-id",
  "appSecret": "example-app-secret"
}

请立即安全保存 appSecret，后续无法再次获取明文。新 Key 会显示在 Console 中，审计日志不会显示 Secret。调用部署 API 时，使用部署详情的 connection.apiEndpoint 作为 API 地址，并使用返回的 appID 和 appSecret 进行 Basic Auth；不要将平台 API Key 用作部署 API 凭据。

停止部署

URI

POST /deployments/{deployment_id}/stop

TIP

该方法 60 分钟内只能请求 5 次。{deployment_id} 为部署 ID，非部署名称。仅适用于专有版部署。

请求消息

无

响应消息

201:

名称	类型	描述
deploymentID	String	部署 ID。
deploymentName	String	部署名称。
operation	String	操作类型，"stopping" 为停止操作。

401: API Key 认证失败。
403: API Key 没有权限访问。
404: 未找到部署。
422: 无效的请求参数。
429: 请求次数超过限制。

请求示例

bash

curl -u key:secret -X POST {api}/deployments/w41b11c0/stop

响应示例

JSON

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "stopping"
}

启动部署

URI

POST /deployments/{deployment_id}/start

TIP

该方法 60 分钟内只能请求 5 次。{deployment_id} 为部署 ID，非部署名称。仅适用于专有版部署。

请求消息

无

响应消息

201:

名称	类型	描述
deploymentID	String	部署 ID。
deploymentName	String	部署名称。
operation	String	操作类型，"starting" 为开启操作。

401: API Key 认证失败。
403: API Key 没有权限访问。
404: 未找到部署。
422: 无效的请求参数。
429: 请求次数超过限制。

请求示例

bash

curl -u key:secret -X POST {api}/deployments/w41b11c0/start

响应示例

JSON

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "starting"
}

创建部署

URI

POST /deployments

TIP

每个平台 API Key 每小时最多可以成功创建 2 个部署。部署将在默认项目中创建，并按小时计费。支持创建 EMQX v5 和 v6 部署。

请求消息

名称	类型	必填	描述
platform	String	是	部署所在的云平台。详细支持的平台见下表。
region	String	是	部署创建的地区。详细支持的地区见下表。
connections	Number	是	部署的连接数。详细规格见下表。Serverless 部署仅支持 1,000 连接数/1,000 TPS。Dedicated 部署支持从 1,000 到 10,000 连接数不等的规格。
tps	Number	是	部署的 TPS。详细规格见下表。Serverless 部署仅支持 1,000 连接数/1,000 TPS。Dedicated 部署支持从 1,000 到 20,000 TPS 不等的规格。
deploymentType	String	是	部署版本。必须为 "serverless" 或 "dedicatedFlex"。
deploymentName	String	否	部署名称。如不填，系统将自动生成默认名称。
deploymentVersion	String	是	部署版本号。支持 "v5" 和 "v6"。
projectID	String	是	项目 ID。可通过项目列表获取。
freeTrial	Boolean	是	是否为免费试用部署。必须设置为 `false`。

支持的平台和地区

云平台名称	云平台代码	区域名称	区域代码	支持 Serverless	支持专有版
阿里云	aliyun	杭州	cn-hangzhou	✅	✅
		上海	cn-shanghai		✅
		北京	cn-beijing		✅
		深圳	cn-shenzhen		✅
		成都	cn-chengdu		✅
华为云	huawei	华南-广州	cn-south-1		✅
		华东-上海一	cn-east-3		✅
		华北-北京四	cn-north-4		✅
		西南-贵阳一	cn-southwest-2		✅
腾讯云	tencent	广州	ap-guangzhou		✅
		上海	ap-shanghai		✅
		北京	ap-beijing		✅
AWS 中国	aws_cn	宁夏	cn-northwest-1		✅
		北京	cn-north-1		✅

不同部署类型支持的连接数和 TPS 规格：

连接数	TPS
1,000	1,000

连接数	TPS
1,000	1,000
2,000	2,000
5,000	10,000
10,000	20,000

响应消息

201:

名称	类型	描述
createAt	String	部署创建时间。
deploymentID	String	部署的唯一标识符。
deploymentName	String	部署名称。
deploymentType	String	部署版本（"dedicatedFlex" 或 "serverless"）。
platform	String	云平台标识符。
ports	Object	不同协议的端口配置。
projectID	String	部署所属项目的 ID。
region	String	云地区标识符。
regionLabel	String	可读的地区名称。
spec	Object	部署规格，包括连接数、版本等。
status	String	部署的当前状态（运行中、已停止、等待中）。
subscription	Boolean	是否为订阅部署。
userID	String	部署所有者的用户 ID。

400: 请求错误
401: API Key 认证失败
403: API Key 没有权限访问
422: 无效的请求参数
429: 该平台 API Key 每小时已成功创建 2 个部署，达到限流上限。

请求示例

bash

curl -u key:secret -X POST {api}/deployments \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "aliyun",
    "region": "cn-hangzhou",
    "connections": 1000,
    "tps": 1000,
    "deploymentType": "dedicatedFlex",
    "deploymentVersion": "v5",
    "projectID": "00000001",
    "freeTrial": false
  }'

响应示例

json

{
    "createAt": "2025-04-17 15:30",
    "deploymentID": "i9d0961f",
    "deploymentName": "deployment-i9d0961f",
    "deploymentType": "dedicatedFlex",
    "platform": "aliyun",
    "ports": {
        "1883": {
            "status": "running",
            "protocol": "mqtt"
        },
        "8083": {
            "status": "running",
            "protocol": "ws"
        },
        "8084": {
            "status": "running",
            "protocol": "wss"
        },
        "8883": {
            "status": "running",
            "protocol": "mqtts"
        }
    },
    "projectID": "00000001",
    "region": "cn-hangzhou",
    "regionLabel": "杭州",
    "spec": {
        "connections": 1000,
        "deploymentVersion": "v5",
        "freeTraffic": 100,
        "node": 2,
        "protection": false,
        "tps": 1000,
        "version": 5.2
    },
    "status": "pending",
    "subscription": false,
    "tls": null,
    "userID": "00000001"
}

创建弹性专有版部署

扩展认证

扩展授权

告警

告警处理指南

CoAP 协议网关

规则

基于 LLM 的 MQTT 数据处理

Schema 管理

Serverless 部署 API

部署管理 API ​

获取部署列表 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

查询部署详情和连接信息 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

创建部署 API Key ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

停止部署 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

启动部署 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

创建部署 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

部署管理 API

获取部署列表

URI

请求消息

响应消息

请求示例

响应示例

查询部署详情和连接信息

URI

请求消息

响应消息

请求示例

响应示例

创建部署 API Key

URI

请求消息

响应消息

请求示例

响应示例

停止部署

URI

请求消息

响应消息

请求示例

响应示例

启动部署

URI

请求消息

响应消息

请求示例

响应示例

创建部署

URI

请求消息

响应消息

请求示例

响应示例