创建云服务器(按需)
功能介绍
创建一台或多台按需付费方式的云服务器。
本接口为异步接口,当前创建云服务器请求下发成功后会返回job_id,此时创建云服务器并没有立即完成,需要通过调用查询任务的执行状态查询job状态,当Job状态为SUCCESS时代表云服务器创建成功。
本接口支持在HTTP请求消息头中设置X-Client-Token请求头,保证请求幂等性。详细信息请参考请求幂等性说明。
调用接口前,您需要了解API认证鉴权。
调用接口前,您需要提前获取到地区和终端节点。
弹性云服务器的登录鉴权方式包括两种:密钥对、密码。为安全起见,推荐使用密钥对方式。
- 密钥对
接口调用方法:使用key_name字段,指定弹性云服务器登录时使用的密钥文件。
- 密码
指使用设置初始密码方式作为弹性云服务器的鉴权方式,此时,您可以通过用户名密码方式登录弹性云服务器,Linux操作系统时为root用户的初始密码,Windows操作系统时为Administrator用户的初始密码。
- 镜像密码
使用Linux操作系统私有镜像创建云服务器,支持使用私有镜像的密码。
接口调用方法:使用镜像密码,则无需指定key_name、adminPass字段。
接口约束
创建按需计费云服务器时,系统会自动匹配适用的代金券进行使用。
调试
您可以在API Explorer中调试该接口。
URI
POST /v1/{project_id}/cloudservers
请求消息
请求参数
请求参数如表2所示。
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
server |
是 |
Object |
参数解释: 弹性云服务器信息,请参见表3。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
dry_run |
否 |
Boolean |
参数解释: 是否预检此次请求。配置为预检时,此次请求不会创建实例。 约束限制: 不涉及 取值范围:
默认取值: false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
imageRef |
是 |
String |
参数解释: 待创建云服务器的系统镜像,需要指定已创建镜像的ID。ID格式为通用唯一识别码(Universally Unique Identifier,简称UUID)。 镜像的ID可以从控制台或者参考《镜像服务API参考》的“查询镜像列表”的章节获取。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
flavorRef |
是 |
String |
参数解释: 待创建云服务器的系统规格的ID。 已上线的规格请参见《弹性云服务器产品介绍》的“实例类型与规格”章节。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
name |
是 |
String |
参数解释: 云服务器名称。 创建的云服务器数量(count字段对应的值)大于1时,可以使用“自动排序”和“正则排序”设置有序的云服务器名称。 请参考创建多台云服务器云主机时怎样设置有序的云服务器云主机名称? 约束限制:
取值范围: 只能由中文字符、英文字母、数字及“_”、“-”、“.”组成,且长度为[1-128]个英文字符或[1-64]个中文字符。 默认取值: 不涉及 |
user_data |
否 |
String |
参数解释: 创建云服务器过程中待注入实例自定义数据。支持注入文本、文本文件。 示例: base64编码前:
base64编码后:
更多关于待注入实例自定义数据的信息,请参见《弹性云服务器用户指南 》的“用户数据注入”章节。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
adminPass |
否 |
String |
参数解释: 如果需要使用密码方式登录云服务器,可使用adminPass字段指定云服务器管理员账户初始登录密码。其中,Linux管理员账户为root,Windows管理员账户为Administrator。 约束限制:
取值范围:
默认取值: 不涉及 |
key_name |
否 |
String |
参数解释: 如果需要使用SSH密钥方式登录云服务器,请指定已创建密钥的名称。 密钥可以通过密钥创建接口进行创建(请参见创建和导入SSH密钥对),或使用SSH密钥查询接口查询已有的密钥(请参见查询SSH密钥对列表)。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
vpcid |
是 |
String |
参数解释: 待创建云服务器所属虚拟私有云(简称VPC),需要指定已创建VPC的ID,UUID格式。 VPC的ID可以从控制台或者参考《虚拟私有云接口参考》的“查询VPC”章节获取。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
nics |
是 |
Array of objects |
参数解释: 待创建云服务器的网卡信息。详情请参见表4。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
publicip |
否 |
Object |
参数解释: 配置云服务器的弹性公网IP信息,弹性公网IP有三种配置方式。
详情请参见表1。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
count |
否 |
Integer |
参数解释: 创建云服务器数量。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
isAutoRename |
否 |
Boolean |
参数解释: 批量创建时是否使用相同的名称。 约束限制: 当count大于1的时候该参数生效。 取值范围:
默认取值: false |
root_volume |
是 |
Object |
参数解释: 云服务器对应系统盘相关配置。 详情请参见表6。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
data_volumes |
否 |
Array of objects |
参数解释: 云服务器对应数据盘相关配置。每一个数据结构代表一块待创建的数据盘。 约束限制: 目前云服务器最多可挂载59块数据盘(部分规格只支持23块数据盘) 详情请参见表7。 取值范围: 不涉及 默认取值: 不涉及 |
security_groups |
否 |
Array of objects |
参数解释: 云服务器对应安全组信息。 约束限制: 当该值指定为空时,默认给云服务器绑定default安全组。 详情请参见表2。 取值范围: 不涉及 默认参数: 不涉及 |
availability_zone |
否 |
String |
参数解释: 待创建云服务器所在的可用区,需要指定可用分区名称。 可通过接口查询可用区列表(废弃)获取,也可参考地区和终端节点获取。 约束限制:
取值范围: 不涉及 默认参数: 不涉及 |
batch_create_in_multi_az |
否 |
Boolean |
参数解释: 是否支持随机多AZ部署。 约束限制: 当availability_zone为空时该字段生效。 取值范围:
默认取值: false |
extendparam |
否 |
Object |
参数解释: 创建云服务器附加信息。 详情请参见表8。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
metadata |
否 |
Map<String,String> |
参数解释: 创建云服务器元数据。 可以通过元数据自定义键值对。系统预留键值对请参见表11。 约束限制: 如果元数据中包含了敏感数据,您应当采取适当的措施来保护敏感数据,比如限制访问范围、加密等。 取值范围:
默认取值: 不涉及 |
os:scheduler_hints |
否 |
Object |
参数解释: 云服务器调度信息,例如设置云服务器组。 详情请参见表12。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
tags |
否 |
Array of strings |
参数取值: 弹性云服务器的标签。标签的格式为“key.value”。 约束限制:
其中,key的长度不超过36个字符,value的长度不超过43个字符。 取值范围:
默认取值: 不涉及 |
server_tags |
否 |
Array of objects |
参数解释: 弹性云服务器的标签。详情请参见表14。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
description |
否 |
String |
参数解释: 云服务器描述信息。 约束限制: 不能包含“<” 和 “>”。 取值范围: 长度最多允许85个字符。 默认取值: 空字符串 |
auto_terminate_time |
否 |
String |
参数解释: 定时删除时间。 约束限制:
取值范围: 按照ISO8601标准表示,并使用UTC +0时间,格式为yyyy-MM-ddTHH:mm:ssZ。 示例:2020-09-25T12:05:00Z 默认取值: 不涉及 |
cpu_options |
否 |
Object |
参数解释: 自定义CPU选项。 详情请参见表8。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
enclave_options |
否 |
Object |
参数解释: 自定义enclave_options项。 详情请参见表9 enclave_options数据结构说明。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
security_options |
否 |
Object |
参数解释: 安全启动选项security_options。 详情请参见表10。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
serial_console_options |
否 |
Object |
参数解释: 是否支持串口登录。 详情请参见表11。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
metadata_options |
否 |
Object |
参数解释: 实例元数据配置。 详情请参见表12。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
port_id |
否 |
String |
参数解释: 网卡ID,UUID格式。 当该字段不为空时,表示挂载指定的网卡。 网卡ID可以从虚拟私有云的“查询端口列表”章节查询到。
约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
subnet_id |
否 |
String |
参数解释: 待创建云服务器所在的子网信息。 约束限制: 需要指定vpcid对应VPC下已创建的子网(subnet)的网络ID,UUID格式。 可以通过VPC服务查询子网列表接口查询。 取值范围: 不涉及 默认取值: 不涉及 |
ip_address |
否 |
String |
参数解释: 待创建云服务器网卡的IP地址,IPv4格式。
约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
ipv6_enable |
否 |
Boolean |
参数解释: 是否支持ipv6。 约束限制: 不涉及 取值范围:
默认取值: false |
ipv6_bandwidth |
否 |
Object |
参数解释: 绑定的共享带宽信息,详情请参见ipv6_bandwidth字段数据结构说明。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
allowed_address_pairs |
否 |
Array of allow_address_pairs objects |
参数解释: IP/Mac对列表,详情请参见表5(扩展属性)。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
名称 |
是否必选 |
参数类型 |
说明 |
---|---|---|---|
ip_address |
否 |
String |
参数解释: IP地址。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
mac_address |
否 |
String |
参数解释: MAC地址。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
volumetype |
是 |
String |
参数解释: 云服务器系统盘对应的磁盘类型。 了解不同磁盘类型的详细信息,请参见磁盘类型及性能介绍。 约束限制:
取值范围:
目前支持“SATA”,“SAS”,“GPSSD”,“SSD”,“ESSD”,“GPSSD2”和“ESSD2”。
默认取值: 不涉及 |
size |
否 |
Integer |
参数解释: 系统盘大小,容量单位为GiB。 约束限制:
说明:
镜像系统盘的最小值(镜像的min_disk属性)可在控制台上单击镜像详情查看。或通过调用“查询镜像详情(OpenStack原生)”API获取,详细操作请参考《镜像服务API参考》中“查询镜像详情(OpenStack原生)”章节。 取值范围: 输入大小范围为[1,1024] 默认取值: 不涉及 |
extendparam |
否 |
Object |
参数解释: 磁盘的产品信息。 详情请参见创建磁盘的extendparam字段数据结构说明。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
cluster_type |
否 |
String |
参数解释: 云服务器系统盘对应的磁盘存储类型。 约束限制: 该参数需要与“cluster_id”配合使用,仅当“cluster_id”不为空时,才可以成功创建专属存储类型的磁盘。 取值范围: 磁盘存储类型枚举值:DSS(专属存储类型) 默认取值: 不涉及 |
cluster_id |
否 |
String |
参数解释: 云服务器系统盘对应的存储池的ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
hw:passthrough |
否 |
Boolean |
参数解释: 设置云硬盘的设备类型。 约束限制: 非QingTian规格仅支持设置系统盘为VBD类型。
取值范围:
默认取值: 参数未指定或者指定非Boolean类型的字符,默认创建VBD类型磁盘。 |
metadata |
否 |
Object |
参数解释: 创建云硬盘的metadata信息。详情请参见创建磁盘的metadata字段数据结构说明。 约束限制: 仅在创建加密盘时使用metadata字段。 取值范围: metadata中的key和value长度不大于255个字节。 默认取值: 不涉及 |
iops |
否 |
Integer |
参数解释: 为云硬盘配置iops。 了解GPSSD2、ESSD2类型云硬盘的iops,请参见磁盘类型及性能介绍。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
throughput |
否 |
Integer |
参数解释: 为云硬盘配置吞吐量,单位是MiB/s。 了解GPSSD2类型云硬盘的吞吐量大小范围,请参见磁盘类型及性能介绍。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
volumetype |
是 |
String |
参数解释: 云服务器数据盘对应的磁盘类型。 了解不同磁盘类型的详细信息,请参见磁盘类型及性能介绍。 约束限制:
取值范围:
目前支持“SATA”,“SAS”,“GPSSD”,“SSD”,“ESSD”,“GPSSD2”和“ESSD2”。
默认取值: 不涉及 |
size |
是 |
Integer |
参数解释: 数据盘大小,容量单位为GiB。 约束限制: 如果使用数据盘镜像创建数据盘时,size取值不能小于创建数据盘镜像的源数据盘的大小。 取值范围: 输入大小范围为[10,32768]。 默认取值: 不涉及 |
shareable |
否 |
Boolean |
参数解释: 是否为共享磁盘。 约束限制: 该字段已废弃,请使用multiattach。 取值范围:
默认取值: false |
multiattach |
否 |
Boolean |
参数解释: 创建共享磁盘的信息。 约束限制: shareable当前为废弃字段,如果确实需要同时使用shareable字段和multiattach字段,此时,请确保两个字段的参数值相同。当不指定该字段时,系统默认创建普通云硬盘。 取值范围:
默认取值: false |
hw:passthrough |
否 |
Boolean |
参数解释: 设置云硬盘的设备类型。 约束限制: 非QingTian规格仅支持设置系统盘为VBD类型。
取值范围:
默认取值: 不涉及 |
extendparam |
否 |
Object |
参数解释: 磁盘的产品信息。 详情请参见表7。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
cluster_type |
否 |
String |
参数解释: 云服务器数据盘对应的磁盘存储类型。 约束限制: 该参数需要与“cluster_id”配合使用,仅当“cluster_id”不为空时,才可以成功创建专属存储类型的磁盘。 取值范围: 磁盘存储类型枚举值:DSS(专属存储类型) 默认取值: 不涉及 |
cluster_id |
否 |
String |
参数解释: 云服务器数据盘对应的存储池的ID。 约束限制: 不涉及 取值范围: 不涉及 默认取值: 不涉及 |
data_image_id |
否 |
String |
参数解释: 数据镜像的ID,UUID格式。 约束限制: 如果使用数据盘镜像创建数据盘,则data_image_id为必选参数,且不支持使用metadata。 取值范围: 不涉及 默认取值: 不涉及 |
metadata |
否 |
Object |
参数解释: 创建云硬盘的metadata信息。 详情请参见创建磁盘的metadata字段数据结构说明。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
delete_on_termination |
否 |
Boolean |
参数解释: 数据盘随实例释放策略。 约束限制: 该字段仅按需、竞价实例支持。 取值范围:
默认取值: false |
iops |
否 |
Integer |
参数解释: 为云硬盘配置iops。 了解GPSSD2、ESSD2类型云硬盘的iops,请参见磁盘类型及性能介绍。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
throughput |
否 |
Integer |
参数解释: 为云硬盘配置吞吐量,单位是MiB/s。 了解GPSSD2类型云硬盘的吞吐量大小范围,请参见磁盘类型及性能介绍。 约束限制:
取值范围: 不涉及 默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
hw:cpu_threads |
否 |
integer |
参数解释: 用于控制CPU是否开启超线程。 约束限制: 需要同时满足如下条件,才能设置为“关闭超线程”:
取值范围:
默认取值: 不涉及 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
enabled |
是 |
Boolean |
参数解释: enclave使能开关。 约束限制: 不涉及 取值范围:
默认取值: false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
secure_boot_enabled |
是 |
Boolean |
参数解释: 安全启动开关。 约束限制: 不涉及 取值范围:
默认取值: false |
tpm_enabled |
是 |
Boolean |
参数解释: tpm启动开关。 约束限制: 不涉及 取值范围:
默认取值: false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
enabled |
否 |
String |
参数解释: 是否支持串口登录。 约束限制: 不涉及 取值范围:
默认取值: false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
http_endpoint |
否 |
String |
参数解释: 是否启用IMDS服务,默认enabled。 约束限制: 不涉及 取值范围:
默认取值: disabled |
http_tokens |
否 |
String |
参数解释: 是否要求携带token,默认optional。 约束限制: 不涉及 取值范围:
默认取值: required |
响应消息
参数 |
参数类型 |
描述 |
---|---|---|
job_id |
String |
参数解释: 提交任务成功后返回的任务ID,用户可以使用该ID对任务执行情况进行查询。如何根据job_id来查询Job的执行状态,请参考查询Job状态。 取值范围: 不涉及 |
serverIds |
Array of strings |
参数解释: 云服务器ID列表。
说明:
通过云服务器ID查询云服务器详情 ,若返回404 可能云服务器还在创建或者已经创建失败。 取值范围: 不涉及 |
异常响应请参考响应(任务类),异常响应要素说明。
请求示例
- 创建一台按需计费云服务器,操作系统为CentOS 7.6 64bit,4U8G,磁盘类型为“SSD”,绑定10M的按带宽计费的弹性公网IP,采用密钥方式登录鉴权。
POST https://{endpoint}/v1/{project_id}/cloudservers { "server": { "availability_zone":"az1-dc1", "name": "newserver", "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", "root_volume": { "volumetype": "SSD" }, "data_volumes": [ { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s3.xlarge.2", "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", "security_groups": [ { "id": "507ca48f-814c-4293-8706-300564d54620" } ], "nics": [ { "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83" } ], "publicip": { "eip": { "iptype": "5_bgp", "bandwidth": { "size": 10, "sharetype": "PER" } } }, "key_name": "sshkey-123", "count": 1, "extendparam": { "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb" }, "server_tags": [ { "key": "key1", "value": "value1" } ], "metadata": { "op_svc_userid": "8ea65f4099ba412883e2a0da72b96873", "agency_name": "test" } } }
- 发送预校验请求,检查创建弹性云服务器的请求消息是否填写了必选参数,请求格式是否正确。
POST https://{endpoint}/v1/{project_id}/cloudservers { "dry_run": true, "server": { "availability_zone":"az1-dc1", "name": "newserver", "imageRef": "1189efbf-d48b-46ad-a823-94b942e2a000", "root_volume": { "volumetype": "SSD" }, "data_volumes": [ { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s3.xlarge.2", "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", "security_groups": [ { "id": "507ca48f-814c-4293-8706-300564d54620" } ], "nics": [ { "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83" } ], "key_name": "sshkey-123", "count": 1 } }
响应示例
{ "job_id": "ff808082739334d80173941567f21d4f", "serverIds": [ "118258c5-0c6a-4e73-8b51-8d1ea3272e1b", "e51b9e20-7088-4914-a4f3-6c76bcfed0be" ] }
或
{ "error": { "code": "request body is illegal.", "message": "Ecs.0005" } }
或
{ "error": { "message": "privateIp [%s] is not in this subnet [%s]", "code": "Ecs.0005", "details": [ { "code": "Ecs.0039" } ] } }
返回值
请参考通用请求返回值。
错误码
请参考错误码。