部署管理 API

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

获取部署列表

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: 请求次数超过限制。

请求示例

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

响应示例

[
    {
        "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" 为停止状态。

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

请求示例

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

响应示例

{
    "connections": 1000,
    "tps": 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: 请求次数超过限制。

请求示例

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

响应示例

{
    "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: 请求次数超过限制。

请求示例

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

响应示例

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

创建部署

URI

POST /deployments

TIP

该方法 60 分钟内只能请求 1 次。部署将在默认项目中创建，并按小时计费。目前支持创建 v5 和 v6 版本的 EMQX。

请求消息

名称	类型	必填	描述
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: 无效的请求参数

请求示例

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

响应示例

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