# 部署管理 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:** 请求次数超过限制。 ### 请求示例 ```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" 为停止状态。 | - **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" } ``` ## 停止部署 ### 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 连接数不等的规格。 | | tps | Number | 是 | 部署的 TPS。详细规格见下表。Serverless 部署仅支持 1,000 连接数/1,000 TPS。Dedicated 部署支持从 1,000 到 20,000 TPS 不等的规格。 | | deploymentType | String | 是 | 部署版本。必须为 "serverless" 或 "dedicated"。 | ::: tip 支持的平台和地区 | 云平台名称 | 云平台代码 | 区域名称 | 区域代码 | 支持 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 规格： :::: tabs ::: tab "Serverless 版本" | 连接数 | TPS | |----------|----------| | 1,000 | 1,000 | ::: ::: tab "专有版" | 连接数 | 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, "tps": 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" } ```