CreateZecInstances

1. 接口描述

本接口用于创建一个或多个指定配置的ZEC实例。

准备工作

查询机型规格：调用DescribeZoneInstanceConfigInfos 可以查询到规格信息。
查询镜像：调用DescribeImages可以查询到镜像信息。
查询密钥对：调用 DescribeKeyPairs可以查询到密钥对ID信息。

注意事项

实例创建成功后将自动开机启动，实例状态变为RUNNING。
购买时需要确保账户账号状态正常。
调用本接口创建实例，支持代金券自动抵扣，详情请参考代金券选用规则。
本接口为异步接口，当创建实例请求下发成功后会返回一个实例ID列表，此时创建实例操作并未立即完成。在此期间实例的状态将会处于DEPLOYING，实例创建结果可以通过调用DescribeInstances 接口查询，如果实例状态由DEPLOYING变为RUNNING则代表创建成功，如果变为CREATE_FAILED则代表创建失败，创建过程中不可对实例进行任何操作。
单次最多能创建100台实例。

2. 请求参数

以下请求参数列表仅列出了接口中需要的请求参数

参数名称

必选

类型

描述

zoneId

是

String

实例所在节点ID。

instanceType

是

String

实例机型。具体取值可通过调用接口DescribeZoneInstanceConfigInfos来获得最新的规格表。

imageId

是

String

指定有效的镜像ID。可调用接口 DescribeImages取返回信息中的imageId字段。

resourceGroupId

否

String

实例所在的资源组ID。如果不指定资源组，则会放到默认的资源组中。

instanceName

否

String

实例显示名称。

范围2到63个字符。仅支持输入字母、数字、-和英文句点(.)。且必须以数字或字母开头和结尾。

购买多台实例，可以指定模式串[begin_number,bits]。begin_number：有序数值的起始值，取值支持[0,99999]，默认值为0。bits：有序数值所占的位数，取值支持[1,6]，默认值为6。注意模式串中不得有空格。购买1台时，例如server-[3,3]实例显示为server003；购买2台时，实例显示名分别为server003，server004。支持指定多个模式串，如server-[3,3]-[1,1]。

默认值为 instance。

instanceCount

否

Integer

指定创建ZEC实例的数量。

取值范围：1~100。默认值：1。

password

否

String

实例的密码。与keyId必须指定其中的一种。必须是8-16位，必须包含以下3种格式的字符：

大小写字母: [a-zA-Z]
数字: 0-9
特殊字符: `~!@$^*-_=+|;:,.?

keyId

否

String

密钥ID。与password必须指定其中的一种。

可调用接口DescribeKeyPairs来获得最新的密钥对信息。

关联密钥后，就可以通过对应的私钥来访问实例；密钥与密码不能同时指定，同时Windows操作系统不支持指定密钥。示例值：key-YWD2QFOl

internetChargeType

否

String

网络计费类型。

取值范围请看InternetChargeType。

trafficPackageSize

否

Float

流量包订购大小。

单位为TB。该值必须在internetChargeType = ByTrafficPackage时才会生效，默认值为0。

bandwidth

否

Integer

公网出带宽上限。

单位：Mbps。

不同机型带宽上限范围不一致，具体限制详见购买网络带宽。

subnetId

是

String

私有网络子网ID。

如果传入了公网IP的相关参数，请确保subnet支持公网配置。

lanIp

否

String

内网IP。如果内网IP被使用,则会默认分配一个。

systemDisk

否

SystemDisk

实例系统盘配置信息。若不指定该参数，则按照系统默认值进行分配。即操作系统要求的最小大小。

dataDisks

否

Array of DataDisk

实例数据盘配置信息。若不指定该参数，则默认不购买数据盘。目前只能附带1个数据盘。

timeZone

否

String

实例对应的时区，默认Asia/Shanghai

enableAgent

否

Boolean

是否开启agent，默认开启。

enableIpForward

否

Boolean

是否开启ip转发，默认关闭。

eipV4Type

否

String

公网ipv4的网络类型，如果指定请确保所选subnet的堆栈类型支持ipv4。当子网类型为IPV4时，该字段必传。

取值范围请看eipV4Type。

目前不支持ThreeLine。

eipBindType

否

BindType

公网EIP绑定模式。如果未指定，默认为普通NAT模式。默认值：FullNat

clusterId

否

String

带宽组id。当internetChargeType=BandwidthCluster时必传。

3. 响应结果

参数名称

类型

描述

instanceIdSet

Array of String

虚拟机实例ID列表。

当通过本接口来创建实例时会返回该参数，表示一个或多个实例ID。返回实例ID列表并不代表实例创建成功，可根据 DescribeInstances 接口查询返回的dataSet中对应实例的状态来判断创建是否完成：如果实例状态由DEPLOYING变为RUNNING则为创建成功；如果实例找不到或状态变为CREATE_FAILED则表示创建失败。

orderNumber

String

订单编号。

instances

Array of DiskWithInstance

随机器创建的数据盘id集合。如果请求中没有指定数据盘，返回空数组。

requestId

String

唯一请求 ID。

每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 代码示例

{% tabs %} {% tab title="示例" %} 1. 用最简单的参数创建一台实例 在上海1创建一台实例，规格为1c2g，系统盘为标准型 NVMe SSD，网络计费方式为流量计费，用密钥对登录，安装ubuntu24.04镜像。

``json POST /api/v2/zec HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateZecInstances

Request: { "zoneId": "asia-east-1a", "instanceType": "z2a.cpu.1", "imageId": "ubuntu2404_20240712", "instanceName": "Sherlock1126151625", "instanceCount": 1, "keyId": "key-rcfljdP5", "internetChargeType": "ByTrafficPackage", "subnetId": "1272168087751233112", "systemDisk": { "diskSize": 40, "diskCategory": "Standard NVMe SSD" } }

Response: { "requestId": "TA471524B-84E1-467B-AB77-75387BBD190B", "response": { "requestId": "TA471524B-84E1-467B-AB77-75387BBD190B", "instanceIdSet": [ "1298293022710045792" ], "instances": [ { "instanceId": "1298293022710045792", "diskIdSet": [] } ], "orderNumber": "1298293056927172914" } }


</div>

</div>

## 5. 开发者工具

Zenlayer Cloud API 2.0 提供了配套的[开发工具集（SDK）](../../api-introduction/toolkit/)，未来会陆续支持更多开发语言，方便快速接入和使用Zenlayer的产品和服务。

## 6. 错误码

下面包含业务逻辑中遇到的错误码，其他错误码见[公共错误码](../../api-introduction/instruction/commonerrorcode.md)

<table><thead><tr><th width="150">HTTP状态码</th><th>错误码</th><th>说明</th></tr></thead><tbody><tr><td>400</td><td>INVALID_PARAMETER_INSTANCE_NAME_EXCEED</td><td>参数instanceName超过了长度限制，请注意模式串中的bits总和不要超过指定长度。</td></tr><tr><td>400</td><td>INVALID_PARAMETER_INSTANCE_NAME_MALFORMED</td><td>参数instanceName格式不正确，请注意输入值在规定的字符内。</td></tr><tr><td>404</td><td>INVALID_IMAGE_NOT_FOUND</td><td>指定的镜像不存在。</td></tr><tr><td>404</td><td>INVALID_ZONE_NOT_FOUND</td><td>指定的可用区不存在。</td></tr><tr><td>404</td><td>INVALID_INSTANCE_TYPE_NOT_FOUND</td><td>指定的实例规格不存在。</td></tr><tr><td>403</td><td>INVALID_SUBNET_NOT_FOUND</td><td>指定的子网不存在。</td></tr><tr><td>403</td><td>INVALID_INSTANCE_COUNT_LIMITATION</td><td>机器创建数量超过了当前Team的总配额。</td></tr><tr><td>400</td><td>INVALID_KEY_PAIR_NOT_FOUND</td><td>指定的密钥对不存在。</td></tr><tr><td>400</td><td>RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT</td><td>所选资源未售卖。</td></tr><tr><td>403</td><td>INVALID_IMAGE_SIZE_EXCEED</td><td>指定的镜像大小大于系统盘大小。</td></tr><tr><td>400</td><td>INVALID_DISK_SIZE_LESS_MINIMUM</td><td>数据盘大小超过了最小限制。</td></tr><tr><td>400</td><td>INVALID_DISK_SIZE_EXCEED_MAXIMUM</td><td>数据盘大小超过了最大限制。</td></tr><tr><td>403</td><td>OPERATION_DENIED_SUBNET_ZONE_MISMATCH</td><td>创建虚拟机实例加入的子网和所选可用区不一致</td></tr><tr><td>400</td><td>OPERATION_FAILED_RESOURCE_GROUP_NOT_FOUND</td><td>指定的资源组不存在。</td></tr><tr><td>400</td><td>INVALID_PARAMETER_INSTANCE_NAME_EXCEED_MINIMUM_LENGTH</td><td>实例的名称超过了最小限制。</td></tr><tr><td>400</td><td>INVALID_PARAMETER_INSTANCE_NAME_EXCEED</td><td>实例的名称超过了最大限制。</td></tr><tr><td>400</td><td>INVALID_SYSTEM_DISK_EXCEED_LIMIT</td><td>指定的系统盘大小超过了指定限制。</td></tr><tr><td>400</td><td>INVALID_INSTANCE_TYPE_ZONE_NO_SELL</td><td>所选规格在所选区域已售罄或未开售。</td></tr><tr><td>403</td><td>OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT</td><td>指定的区域不支持对应的公网网络计费方式。</td></tr><tr><td>400</td><td>INVALID_PASSWORD_MALFORMED</td><td>输入的密码格式错误， 请检查字符都包含在规定的字符里。</td></tr><tr><td>404</td><td>INVALID_TIME_ZONE_NOT_FOUND</td><td>指定的时区不存在。</td></tr><tr><td>400</td><td>STOCK_INSUFFICIENT</td><td>实例库存不足。</td></tr><tr><td>400</td><td>INVALID_DISK_CATEGORY_TYPE</td><td>指定的云盘类型有误。</td></tr><tr><td>400</td><td>INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED</td><td>设定的流量包大小超过最大限制。</td></tr><tr><td>400</td><td>INVALID_PARAMETER_TRAFFIC_PACKAGE</td><td>设定的流量包大小值不合法，必须是0.1或1的倍数。</td></tr><tr><td>400</td><td>OPERATION_DENIED_EIP_UNSUPPORT_NETWORK_TYPE</td><td>指定的eip网络类型不支持实例的创建。</td></tr><tr><td>400</td><td>OPERATION_DENIED_EIP_INSUFFICIENT</td><td>EIP的库存不足。</td></tr><tr><td>400</td><td>OPERATION_DENIED_SUBNET_TYPE_NOT_SUPPORT</td><td>所选的子网堆栈类型不支持。</td></tr><tr><td>400</td><td>INVALID_IMAGE_IPV6_NOT_SUPPORT</td><td>所选的镜像不支持IPV6的堆栈类型。</td></tr><tr><td>400</td><td>INVALID_IMAGE_AGENT_NOT_SUPPORT</td><td>所选的镜像不支持agent。</td></tr><tr><td>404</td><td>INVALID_PASSWORD_KEY_PAIR_NOT_FOUND</td><td>实例密码或密钥对未指定。</td></tr><tr><td>400</td><td>INVALID_LOGIN_SETTING_CONFLICT</td><td>实例密码或密钥对不能同时指定。</td></tr><tr><td>400</td><td>OPERATION_DENIED_EIP_V4_TYPE_NOT_SPECIFIED</td><td>子网堆栈类型是ipv4，但没指定eipV4Type</td></tr><tr><td>400</td><td>UNSUPPORT_SUBNET_TYPE_FOR_INTERNET_CHARGE_TYPE</td><td>子网堆栈类型是ipv6，但不支持公网配置</td></tr><tr><td>400</td><td>INVALID_DISK_ILLEGAL_AMOUNT</td><td>随实例创建的数据盘大小超过限制。</td></tr></tbody></table>

##

最后更新于1天前