功能介绍
创建一台或多台 云服务器 。
V1.1版本创建 云服务 器的接口兼容了V1版本创建云服务器（按需）的功能，同时合入新功能，支持创建包年/包月的弹性云服务器。
本接口为异步接口，当前创建云服务器请求下发成功后会返回job_id，此时创建云服务器并没有立即完成，需要通过调用查询任务的执行状态查询job状态，当Job状态为 SUC CES S 时代表云服务器创建成功。
本接口支持在HTTP请求消息头中设置X-Client-Token请求头，保证请求幂等性。详细信息请参考请求幂等性说明。
- 密钥对
接口调用方法：使用key_name字段，指定弹性云服务器登录时使用的密钥文件，key_name字段的使用方法请参见表2。
- 密码
指使用设置初始密码方式作为弹性云服务器的鉴权方式，此时，您可以通过用户名密码方式登录弹性云服务器，Linux操作系统时为root用户的初始密码，Windows操作系统时为Administrator用户的初始密码。
接口调用方法：使用adminPass字段，指定管理员帐号的初始登录密码，adminPass字段的使用方法请参见表2。对于 镜像 已安装Cloud-init的Linux云服务器，如果需要使用密文密码，可以使用user_data字段进行密码注入，具体请参见表2。
对于安装Cloud-init镜像的Linux云服务器，若指定user_data字段，则adminPass字段无效。
购买操作示例：
接口约束
- 创建包年/包月云服务器时，支持自动支付和手动支付。
- 如果将请求中的isAutoPay字段设置为true，表示采用自动支付方式，系统会自动匹配账户支持的付款方式进行扣费。
- 自动支付支持的付款方式和顺序如下：
折扣优惠（每次只能使用一项）→代金券（每次只能使用一张）→现金券或储值卡（每次可使用多张，可同时使用）→账户余额（先扣现金额度后扣信用额度）或月末结算
- 如果上述付款方式无法完成支付，系统会自动生成一个待支付订单，您可以手动在控制台上选择支付方式进行支付。
自动支付的更多内容请参见自动支付。
- 自动支付支持的付款方式和顺序如下：
- 如果将请求中的isAutoPay字段设置为false，表示采用手动支付方式，系统会自动生成一个待支付订单，您可以手动在控制台上选择支付方式进行支付。
- 如果将请求中的isAutoPay字段设置为true，表示采用自动支付方式，系统会自动匹配账户支持的付款方式进行扣费。
- 创建按需计费云服务器时，系统会自动匹配适用的代金券进行使用。
- 如果您需要退订该包年/包月资源，请参考“退订包年/包月资源”。
调试
您可以在API Explorer中调试该接口。
URI
- URI格式
- 参数说明
参数
是否必选
描述
project_id
是
项目ID
获取方法请参见 获取项目ID
请求消息
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
server |
是 |
Object |
|
|
dry_run |
否 |
Boolean |
是否只预检此次请求，默认为false。
|
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
imageRef |
是 |
String |
待创建云服务器的系统镜像，需要指定已创建镜像的ID，ID格式为通用唯一识别码（Universally Unique Identifier，简称UUID）。 |
|
flavorRef |
是 |
String |
待创建云服务器的系统规格的ID。 已上线的规格请参见《弹性云服务器产品介绍》的“实例类型与规格”章节。 |
|
name |
是 |
String |
云服务器名称。 创建的云服务器数量（count字段对应的值）等于1时，云服务器名称只能由中文字符、英文字母、数字及“_”、“-”组成，且长度为[1-64]个字符。 创建的云服务器数量（count字段对应的值）大于1时，可以使用“自动排序”和“正则排序”设置有序的云服务器名称。 请参考创建多台云服务器云主机时怎样设置有序的云服务器云主机名称？ 取值范围：
|
|
user_data |
否 |
String |
创建云服务器过程中待注入实例自定义数据。支持注入文本、文本文件。 说明：
更多关于待注入实例自定义数据的信息，请参见《弹性云服务器用户指南 》的“用户数据注入”章节。 示例： base64编码前：
base64编码后：
|
|
adminPass |
否 |
String |
如果需要使用密码方式登录云服务器，可使用adminPass字段指定云服务器管理员帐户初始登录密码。其中，Linux管理员帐户为root，Windows管理员帐户为Administrator。 密码复杂度要求：
|
|
key_name |
否 |
String |
如果需要使用SSH密钥方式登录云服务器，请指定已创建密钥的名称。 密钥可以通过密钥创建接口进行创建（请参见创建和导入SSH密钥），或使用SSH密钥查询接口查询已有的密钥（请参见查询SSH密钥列表 ）。 约束： 当创建云服务器的extendparam字段中chargingMode为prePaid时（即包年包月的弹性云服务器），key_name参数必须配合metadata字段使用。详情请参见创建云服务器的metadata字段数据结构说明，以及请求示例1。 |
|
vpcid |
是 |
String |
待创建云服务器所属 虚拟私有云 （简称VPC），需要指定已创建VPC的ID，UUID格式。 |
|
nics |
是 |
Array of objects |
约束：
|
|
publicip |
否 |
Object |
配置云服务器的弹性IP信息，弹性IP有三种配置方式。
详情请参见publicip字段数据结构说明 |
|
count |
否 |
Integer |
创建云服务器数量。 约束：
|
|
isAutoRename |
否 |
Boolean |
云服务器名称是否允许重名。默认为False，当count大于1的时候该参数生效。
|
|
root_volume |
是 |
Object |
云服务器对应系统盘相关配置。 创建包年/包月的弹性云服务器的时候，创建的系统盘/数据盘也是包年/包月，周期和弹性云服务器一致 |
|
data_volumes |
否 |
Array of objects |
云服务器对应数据盘相关配置。每一个数据结构代表一块待创建的数据盘。 约束：目前弹性云服务器最多可挂载59块数据盘(部分规格只支持23块数据盘） |
|
security_groups |
否 |
Array of objects |
云服务器对应安全组信息。 约束：当该值指定为空时，默认给云服务器绑定default安全组。 |
|
availability_zone |
否 |
String |
待创建云服务器所在的可用区，需要指定可用分区名称。 说明：
如果为空，会自动指定一个符合要求的可用区。 |
|
batch_create_in_multi_az |
否 |
Boolean |
是否支持随机多AZ部署，默认为false。
当availability_zone为空时该字段生效。 |
|
extendparam |
否 |
Object |
创建云服务器附加信息。 详情请参见表9 |
|
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 |
弹性云服务器的标签。详情请参见server_tags字段数据结构说明 说明：
|
|
description |
否 |
String |
云服务器描述信息，默认为空字符串。
|
|
auto_terminate_time |
否 |
String |
该字段尚不支持，功能即将上线，敬请期待。 自动释放时间。 按照ISO8601标准表示，并使用UTC +0时间，格式为yyyy-MM-ddTHH:mm:ssZ。 如果秒（ss）取值不是 00，则自动取为当前分钟（mm）开始时。 最短释放时间为当前时间半小时之后。 最长释放时间不能超过当前时间三年。 示例：2020-09-25T12:05:00Z 说明：
仅按需实例支持设置自动释放时间。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
subnet_id |
是 |
String |
待创建云服务器所在的子网信息。 需要指定vpcid对应VPC下已创建的子网（subnet）的网络ID，UUID格式。 可以通过VPC服务查询子网列表接口查询。 |
|
ip_address |
否 |
String |
待创建云服务器网卡的IP地址，IPv4格式。 约束：
|
|
ipv6_enable |
否 |
Boolean |
是否支持ipv6。取值为true时，表示此网卡支持ipv6。 |
|
ipv6_bandwidth |
否 |
Object |
绑定的共享带宽信息，详情请参见ipv6_bandwidth字段数据结构说明。 |
|
allowed_address_pairs |
否 |
约束：IP地址不允许为 “0.0.0.0/0”
|
|
名称 |
是否必选 |
参数类型 |
说明 |
|---|---|---|---|
|
ip_address |
否 |
String |
IP地址。 约束：不支持0.0.0.0/0 如果allowed_address_pairs配置地址池较大的CIDR（掩码小于24位），建议为该port配置一个单独的安全组。 |
|
mac_address |
否 |
String |
MAC地址。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
volumetype |
是 |
String |
云服务器系统盘对应的磁盘类型，需要与系统所提供的磁盘类型相匹配。 目前支持“SATA”，“SAS”，“GPSSD”，“SSD”，“ESSD”。
当指定的云硬盘类型在avaliability_zone内不存在时，则创建云硬盘失败。 说明：
|
|
size |
否 |
Integer |
系统盘大小，容量单位为GB， 输入大小范围为[1,1024]。 约束：
|
|
extendparam |
否 |
Object |
磁盘的产品信息。 详情请参见创建磁盘的extendparam字段数据结构说明。 |
|
cluster_type |
否 |
String |
云服务器系统盘对应的磁盘存储类型。 磁盘存储类型枚举值：DSS（专属存储类型） 该参数需要与“cluster_id”配合使用，仅当“cluster_id”不为空时，才可以成功创建专属存储类型的磁盘。 |
|
cluster_id |
否 |
String |
云服务器系统盘对应的存储池的ID。 |
|
hw:passthrough |
否 |
Boolean |
设置云硬盘的设备类型：
说明：
非擎天规格仅支持设置系统盘为VBD类型。 |
|
metadata |
否 |
Object |
创建云硬盘的metadata信息，metadata中的key和value长度不大于255个字节。 仅在创建加密盘时使用metadata字段。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
volumetype |
是 |
String |
云服务器数据盘对应的磁盘类型，需要与系统所提供的磁盘类型相匹配。 目前支持“SATA”，“SAS”，“GPSSD”，“SSD”，“ESSD”。
当指定的云硬盘类型在avaliability_zone内不存在时，则创建云硬盘失败。 说明：
|
|
size |
是 |
Integer |
数据盘大小，容量单位为GB，输入大小范围为[10,32768]。 如果使用数据盘镜像创建数据盘时，size取值不能小于创建数据盘镜像的源数据盘的大小。 |
|
shareable |
否 |
Boolean |
是否为共享磁盘。true为共享盘，false为普通云硬盘。 说明：
该字段已废弃，请使用multiattach。 |
|
multiattach |
否 |
Boolean |
创建共享磁盘的信息。
说明：
|
|
hw:passthrough |
否 |
Boolean |
设置云硬盘的设备类型：
说明：
非擎天规格仅支持设置系统盘为VBD类型。 |
|
extendparam |
否 |
Object |
磁盘的产品信息。 详情请参见表7。 |
|
cluster_type |
否 |
String |
云服务器数据盘对应的磁盘存储类型。 磁盘存储类型枚举值：DSS（专属存储类型） 该参数需要与“cluster_id”配合使用，仅当“cluster_id”不为空时，才可以成功创建专属存储类型的磁盘。 |
|
cluster_id |
否 |
String |
云服务器数据盘对应的存储池的ID。 |
|
data_image_id |
否 |
String |
数据镜像的ID，UUID格式。 如果使用数据盘镜像创建数据盘，则data_image_id为必选参数，且不支持使用metadata。 |
|
metadata |
否 |
Object |
创建云硬盘的metadata信息，metadata中的key和value长度不大于255个字节。 仅在创建加密盘时使用metadata字段。 如果使用数据盘镜像创建数据盘，不支持使用metadata。 |
|
delete_on_termination |
否 |
Boolean |
数据盘随实例释放策略
默认值：false 说明：
该字段仅按需、竞价实例支持。 |
响应消息
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
job_id |
String |
提交任务成功后返回的任务ID，用户可以使用该ID对任务执行情况进行查询。如何根据job_id来查询Job的执行状态，请参考查询Job状态。 |
|
order_id |
String |
订单号，创建包年包月的弹性云服务器时返回该参数。 说明：
|
|
serverIds |
Array of strings |
云服务器ID列表。 说明：
通过云服务器ID查询云服务器详情 ，若返回404 可能云服务器还在创建或者已经创建失败。 |
异常响应请参考响应（任务类），异常响应要素说明。
请求示例
- 创建一台包年/包月云服务器，操作系统为CentOS 7.6 64bit，1U1G，绑定1M带宽的 弹性公网IP ，采用密钥方式登录鉴权。
POST https://{endpoint}/v1.1/{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 }, { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s2.small.1", "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", "security_groups": [ { "id": "6242ef48-4d35-49c8-8711-a6e54902e44a" } ], "nics": [ { "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08" } ], "publicip": { "eip": { "iptype": "5_sbgp", "bandwidth": { "size": 1, "sharetype": "PER" } } }, "key_name": "id_rsa", "count": 1, "metadata": { "op_svc_userid": "f79791beca3c48159ac2553fff22e166" }, "extendparam": { "chargingMode": "prePaid", "periodType": "month", "periodNum": 1, "isAutoRenew": "true", "isAutoPay": "true", "ent erp rise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb" }, "os:scheduler_hints": { "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc" } } } - 创建一台包年/包月云服务器，操作系统为CentOS 7.6 64bit，1U1G，绑定1M带宽的弹性 公网IP ，采用密码方式登录鉴权。
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "server": { "availability_zone":"az1-dc1", "name": "newserver", "adminPass": "P@ssw0rd123", "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", "root_volume": { "volumetype": "SSD" }, "data_volumes": [ { "volumetype": "SSD", "size": 100 }, { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s2.small.1", "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", "security_groups": [ { "id": "6242ef48-4d35-49c8-8711-a6e54902e44a" } ], "nics": [ { "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08" } ], "publicip": { "eip": { "iptype": "5_sbgp", "bandwidth": { "size": 1, "sharetype": "PER" } } }, "key_name": "", "count": 1, "metadata": {}, "extendparam": { "chargingMode": "prePaid", "periodType": "month", "periodNum": 1, "isAutoRenew": "true", "isAutoPay": "true", "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb" }, "os:scheduler_hints": { "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc" } } } - 创建一台包年/包月云服务器，操作系统为CentOS 7.6 64bit，1U1G，绑定1M带宽的按需按流量计费的弹性公网IP，采用密钥方式登录鉴权。
POST https://{endpoint}/v1.1/{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 }, { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s2.small.1", "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", "security_groups": [ { "id": "6242ef48-4d35-49c8-8711-a6e54902e44a" } ], "nics": [ { "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08" } ], "publicip": { "eip": { "iptype": "5_sbgp", "bandwidth": { "size": 1, "sharetype": "PER", "chargemode": "traffic" }, "extendparam": { "chargingMode": "postPaid" } } }, "key_name": "id_rsa", "count": 1, "metadata": { "op_svc_userid": "f79791beca3c48159ac2553fff22e166" }, "extendparam": { "chargingMode": "prePaid", "periodType": "month", "periodNum": 1, "isAutoRenew": "true", "isAutoPay": "true", "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb" }, "os:scheduler_hints": { "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc" } } } - 创建一台包年/包月云服务器，操作系统为CentOS 7.6 64bit，1U1G，绑定共享带宽的弹性公网IP，采用密钥方式登录鉴权。
POST https://{endpoint}/v1.1/{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 }, { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s2.small.1", "vpcid": "2a6f4aa6-d93e-45f5-a8cb-b030dbf8cd68", "security_groups": [ { "id": "6242ef48-4d35-49c8-8711-a6e54902e44a" } ], "nics": [ { "subnet_id": "ef039b60-6a14-42d1-963b-687b627fea08" } ], "publicip": { "eip": { "iptype": "5_sbgp", "bandwidth": { "id": "a0d4b26f-699d-49a0-bcc8-6f707a925abf", "sharetype": "WHOLE" } } }, "key_name": "id_rsa", "count": 1, "metadata": { "op_svc_userid": "f79791beca3c48159ac2553fff22e166", "agency_name": "test" }, "extendparam": { "chargingMode": "prePaid", "periodType": "month", "periodNum": 1, "isAutoRenew": "true", "isAutoPay": "true", "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb" }, "os:scheduler_hints": { "group": "cdbbfffe-ef18-47b4-a5c8-f61a984c0ecc" } } }
- 发送预校验请求，检查创建云服务器的请求消息是否填写了必选参数，请求格式是否正确。
POST https://{endpoint}/v1.1/{project_id}/cloudservers { "dry_run": true, "server": { "availability_zone":"az1-dc1", "name": "server", "imageRef": "ff49b1f1-3e3e-4913-89c6-a026041661e8", "root_volume": { "volumetype": "SSD" }, "data_volumes": [ { "volumetype": "SSD", "size": 100 }, { "volumetype": "SSD", "size": 100, "multiattach": true, "hw:passthrough": true } ], "flavorRef": "s2.large.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" } }
响应示例
{
"job_id": "ff808082739334d80173943ec9b42130",
"order_id": "CS2007281506xxxxx",
"serverIds": [
"fe0528f0-5b1c-4c8c-9adf-e5d5047b8c17",
"679854ae-a50d-40c9-8132-b19bf3a306a1"
]
}
或
{
"error": {
"code": "Ecs.0005",
"message": "request body is illegal."
}
}
或
{
"error": {
"message": "privateIp [%s] is not in this subnet [%s]",
"code": "Ecs.0005",
"details": [
{
"code": "Ecs.0039"
}
]
}
}
返回值
请参考通用请求返回值。
错误码
请参考错误码。
