部署管理 API

本页介绍了如何通过 API 获取部署列表、查询指定部署状态、启动、停止和创建部署。

获取部署列表

URI

GET /deployments

TIP

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

请求消息

无

响应消息

200:

名称	类型	描述
connections	Number	连接数规格。
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,
        "createAt": "2024-11-21 02:51",
        "deploymentID": "mdfba81f",
        "deploymentName": "deployment-mdfba81f",
        "deploymentType": "serverless",
        "platform": "阿里云",
        "projectName": "default",
        "region": "杭州",
        "status": "stopped",
        "version": "v5"
    },
    {
        "connections": 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	连接数规格。
createAt	String	部署创建时间。
deploymentID	String	部署 ID。
deploymentName	String	部署名称。
deploymentType	String	部署类型，"dedicated" 为专有版。
platform	String	云服务商。
region	String	云主机所在地区。
status	String	部署运行状态： "running" 为运行中， "starting" 为创建过程中， "stopped" 为停止状态。

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

请求示例

bash

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

响应示例

JSON

{
    "connections": 1000,
    "createAt": "2024-07-22 05:32",
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "deploymentType": "dedicated",
    "platform": "阿里云",
    "region": "杭州",
    "status": "running"
}

停止部署

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

该方法 60 分钟内只能请求 1 次。部署将在默认项目中创建。请注意，目前仅支持创建 v5 版本的 EMQX。

请求消息

名称	类型	必填	描述
platform	String	是	部署所在的云平台。详细支持的平台见下表。
region	String	是	部署创建的地区。详细支持的地区见下表。
connections	Number	是	部署的连接数。详细规格见下表。Serverless 部署仅支持 1,000 连接数/1,000 TPS。Dedicated 部署支持从 1,000 到 10,000 连接数不等的规格。
deploymentType	String	是	部署版本。必须为 "serverless" 或 "dedicated"。

支持的平台和地区

云平台名称	云平台代码	区域名称	区域代码	支持 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	部署版本（专有版或 serverless）。
freeTrial	Boolean	是否为免费试用部署。
platform	String	云平台标识符。
ports	Object	不同协议的端口配置。
projectID	String	部署所属项目的 ID。null 表示默认项目。
region	String	云地区标识符。
regionLabel	String	可读的地区名称。
spec	Object	部署规格，包括连接数、版本等。
status	String	部署的当前状态（运行中、已停止、等待中）。
subscription	Boolean	是否为订阅部署。
userID	String	部署所有者的用户 ID。

400: 请求错误
401: API Key 认证失败
403: API Key 没有权限访问
422: 无效的请求参数

请求示例

bash

curl -u key:secret -X POST {api}/deployments \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "aliyun",
    "region": "cn-hangzhou",
    "connections": 1000,
    "deploymentType": "dedicated"
  }'

响应示例

json

{
    "createAt": "2025-04-17 15:30",
    "deploymentID": "i9d0961f",
    "deploymentName": "deployment-i9d0961f",
    "deploymentType": "dedicated",
    "freeTrial": false,
    "platform": "aliyun",
    "ports": {
        "1883": {
            "status": "running",
            "protocol": "mqtt"
        },
        "8083": {
            "status": "running",
            "protocol": "ws"
        },
        "8084": {
            "status": "running",
            "protocol": "wss"
        },
        "8883": {
            "status": "running",
            "protocol": "mqtts"
        }
    },
    "projectID": null,
    "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"
}

创建专有版部署

扩展认证

扩展授权

单点登录 (SSO)

告警

CoAP 协议网关

平台 API

部署 API

Serverless 部署 API

部署管理 API

获取部署列表

URI

请求消息

响应消息

请求示例

响应示例

查看指定部署的状态

URI

请求消息

响应消息

请求示例

响应示例

停止部署

URI

请求消息

响应消息

请求示例

响应示例

启动部署

URI

请求消息

响应消息

请求示例

响应示例

创建部署

URI

请求消息

响应消息

请求示例

响应示例

Serverless 部署 API

部署管理 API ​

获取部署列表 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

查看指定部署的状态 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

停止部署 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

启动部署 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

创建部署 ​

URI ​

请求消息 ​

响应消息 ​

请求示例 ​

响应示例 ​

部署管理 API

获取部署列表

URI

请求消息

响应消息

请求示例

响应示例

查看指定部署的状态

URI

请求消息

响应消息

请求示例

响应示例

停止部署

URI

请求消息

响应消息

请求示例

响应示例

启动部署

URI

请求消息

响应消息

请求示例

响应示例

创建部署

URI

请求消息

响应消息

请求示例

响应示例