CreateInstances

1. 接口描述

调用本接口用于创建一个或多个指定配置的虚拟机实例。

准备工作

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

注意事项

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

2. 请求参数

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

参数名称必选类型描述

参数名称	必选	类型	描述
zoneId	是	String	实例所在节点ID。
instanceChargeType	是	String	付费类型。 PREPAID：预付费，即包年包月 POSTPAID：后付费
instanceChargePrepaid	否	ChargePrepaid	预付费模式。即包年包月相关参数设置。通过该参数可以指定包年包月实例的购买时长等属性。若指定实例的付费模式为预付费则该参数必传。
instanceType	是	String	实例机型。具体取值可通过调用接口`DescribeZoneInstanceConfigInfos`来获得最新的规格表。
imageId	是	String	指定有效的镜像ID。可通过以下方式获取可用的镜像ID：通过调用接口 `DescribeImages`取返回信息中的`imageId`字段。
resourceGroupId	否	String	实例所在的资源组ID。如果不指定资源组，则会放到默认的资源组中。
instanceName	否	String	实例显示名称。不得超过64个字符。仅支持输入字母、数字、-和英文句点(.)。购买多台实例，可以指定模式串`[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	指定创建VM实例的数量。取值范围：1~100。默认值：1。
password	否	String	实例的密码。必须是8-16位，必须包含以下4种格式的字符：小写字母: [a-z] 大写字母: [A-Z] 数字: 0-9 特殊字符: `!@#$%^+*()`
keyId	否	String	密钥ID。关联密钥后，就可以通过对应的私钥来访问实例；密钥与密码不能同时指定，同时Windows操作系统不支持指定密钥。示例值：key-YWD2QFOl
internetChargeType	是	String	网络计费类型。取值范围请看InternetChargeType。
internetMaxBandwidthOut	否	Integer	公网出带宽上限。单位：Mbps。默认值：1Mbps。不同机型带宽上限范围不一致，具体限制详见购买网络带宽。
trafficPackageSize	否	Float	流量包订购大小。单位为TB。该值仅限当 `internetChargeType` = `ByTrafficPackage` 生效。如果没有传则会默认以赠送的流量包大小
subnetId	是	String	私有网络子网ID 。
systemDisk	否	SystemDisk	实例系统盘配置信息。若不指定该参数，则按照系统默认值进行分配。即操作系统要求的最小大小。
dataDisks	否	Array of DataDisk	实例数据盘配置信息。若不指定该参数，则默认不购买数据盘。目前只能附带10个数据盘
securityGroupId	否	String	安全组ID。该参数可以通过调用 DescribeSecurityGroups 的返回值中的sgId字段来获取。

zoneId

是

String

实例所在节点ID。

instanceChargeType

是

String

付费类型。

PREPAID：预付费，即包年包月 POSTPAID：后付费

instanceChargePrepaid

否

ChargePrepaid

预付费模式。即包年包月相关参数设置。通过该参数可以指定包年包月实例的购买时长等属性。若指定实例的付费模式为预付费则该参数必传。

instanceType

是

String

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

imageId

是

String

指定有效的镜像ID。可通过以下方式获取可用的镜像ID：通过调用接口 DescribeImages取返回信息中的imageId字段。

resourceGroupId

否

String

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

instanceName

否

String

实例显示名称。

不得超过64个字符。仅支持输入字母、数字、-和英文句点(.)。

购买多台实例，可以指定模式串[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

指定创建VM实例的数量。

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

password

否

String

实例的密码。必须是8-16位，必须包含以下4种格式的字符：

小写字母: [a-z]
大写字母: [A-Z]
数字: 0-9
特殊字符: !@#$%^+*()

keyId

否

String

密钥ID。

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

internetChargeType

是

String

网络计费类型。

取值范围请看InternetChargeType。

internetMaxBandwidthOut

否

Integer

公网出带宽上限。

单位：Mbps。默认值：1Mbps。不同机型带宽上限范围不一致，具体限制详见购买网络带宽。

trafficPackageSize

否

Float

流量包订购大小。

单位为TB。该值仅限当 internetChargeType = ByTrafficPackage 生效。如果没有传则会默认以赠送的流量包大小

subnetId

是

String

私有网络子网ID 。

systemDisk

否

SystemDisk

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

dataDisks

否

Array of DataDisk

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

securityGroupId

否

String

安全组ID。该参数可以通过调用 DescribeSecurityGroups 的返回值中的sgId字段来获取。

3. 响应结果

参数名称类型描述

参数名称	类型	描述
instanceIdSet	Array of String	虚拟机实例ID列表。当通过本接口来创建实例时会返回该参数，表示一个或多个实例`ID`。返回实例`ID`列表并不代表实例创建成功，可根据 `DescribeInstances` 接口查询返回的dataSet中对应实例的状态来判断创建是否完成：如果实例状态由`DEPLOYING`(部署中)或`PENDING（待创建）`变为`RUNNING`(运行中)，则为创建成功；如果实例找不到或状态变为`CREATE_FAILED`，表示创建失败。
orderNumber	String	订单编号。
instances	Array of DiskWithInstance	随机器创建的数据盘id集合。如果请求中没有指定数据盘，返回空数组。
requestId	String	唯一请求 ID。每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

instanceIdSet

Array of String

虚拟机实例ID列表。

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

orderNumber

String

订单编号。

instances

Array of DiskWithInstance

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

requestId

String

唯一请求 ID。

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

4. 代码示例

1. 用最简单的参数创建一台后付费的实例 在首尔A创建一台后付费实例，规格为1c2g，其带宽计费为固定带宽，密码随机生成，不安装任何镜像，带宽大小为默认的1Mbps。

POST /api/v2/vm HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "zoneId":"SEL-A",
    "instanceType":"c.1c2g",
    "imageId":"img-yKK4q6XybymPgfx7ynUUqC3N8",
    "instanceChargeType":"POSTPAID",
    "internetChargeType":"ByBandwidth"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
        "instanceIdSet": ["instanceId1"],
        "orderNumber" : "the id of order number",
        "instances":[{"instanceId":"instanceId1","diskIdSet":[]}]
    }
}

2. 在1的基础上附带一块大小为40GB的标准数据盘 在首尔A创建一台后付费实例，规格为1c2g，其带宽计费为固定带宽，密码随机生成，不安装任何镜像，带宽大小为默认的1Mbps，附带一块40GB的标准类型的数据盘。

POST /api/v2/vm HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "zoneId": "SEL-A",
    "instanceType": "c.1c2g",
    "imageId": "img-yKK4q6XybymPgfx7ynUUqC3N8",
    "instanceChargeType": "POSTPAID",
    "internetChargeType": "ByBandwidth",
    "dataDisks": [
        {
            "diskSize": 40,
            "diskCategory": "STANDARD"
        }
    ]
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
        "instanceIdSet": ["instanceId1"],
        "orderNumber" : "the id of order number",
        "instances":[{"instanceId":"instanceId1","diskIdSet":["diskId1"]}]
    }
}

3. 创建2台预付费的实例 在首尔A 创建2台预付费付费实例，周期为2个月，规格为1c2g，两台实例的名称分别为：SEL-1C2G-01, SEL-1C2G-02, 密码Password-12345~，镜像ID: image-xxxxx，带宽计费为固定带宽，带宽大小为10Mbps。

POST /api/v2/vm HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "instanceChargeType": "PREPAID",
    "instanceCount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-1C2G-[1,2]",
    "internetMaxBandwidthOut": 10,
    "password": "Password-12345~",
    "instanceType": "c.1c2g",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A", 
    "imageId": "image-xxxxx"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": [
            "instanceId3",
            "instanceId4"
        ],
        "orderNumber": "the id of order number",
        "instances": [
            {
                "instanceId": "instanceId3",
                "diskIdSet": []
            },
            {
                "instanceId": "instanceId4",
                "diskIdSet": []
            }
        ]
    }
}

4. 创建2台预付费的实例，其网络计费方式为流量包 和2类似，不同的是本次创建的网络计费方式是流量包，其流量包大小为 10TB。带宽大小为100Mbps。

POST /api/v2/vm HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
<Common Request Params>

Request:
{
    "instanceChargeType": "PREPAID",
    "instanceCount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-1C2G-[1,2]",
    "internetMaxBandwidthOut": 100,
    "password": "Password-12345~",
    "instanceType": "c.1c2g",
    "internetChargeType": "ByTrafficPackage",
    "trafficPackageSize": 10,
    "zoneId": "SEL-A", 
    "imageId": "image-xxxxx"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId5", "instanceId6"],
        "orderNumber" : "the id of order number",
        "instances": [
            {
                "instanceId": "instanceId5",
                "diskIdSet": []
            },
            {
                "instanceId": "instanceId6",
                "diskIdSet": []
            }
        ]
    }
}

5. 开发者工具

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

6. 错误码

下面包含业务逻辑中遇到的错误码，其他错误码见公共错误码

HTTP状态码	错误码	说明
400	INVALID_PARAMETER_INSTANCE_NAME_EXCEED	参数instanceName超过了长度限制，请注意模式串中的bits总和不要超过指定长度。
400	INVALID_PARAMETER_INSTANCE_NAME_MALFORMED	参数instanceName格式不正确，请注意输入值在规定的字符内。
403	OPERATION_FILED_INTERNET_CHARGE_TYPE_NOT_SUPPORT	指定的网络计费类型在当前区域不支持。
404	INVALID_IMAGE_NOT_FOUND	未找到指定的镜像。
404	INVALID_ZONE_NOT_FOUND	指定的可用区不存在。
404	INVALID_INSTANCE_TYPE_NOT_FOUND	未找到指定的实例规格。
403	INVALID_PARTITION_IMAGE_NOT_SET	自定义分区必须指定操作系统才可以进行。
403	OPERATION_DENIED_INSTANCE_QUOTA_EXCEED	机器创建数量超过了当前Team的总配额。
400	INVALID_BANDWIDTH_VALUE_EXCEED_MAXIMUM	指定的带宽大小超过了机型允许的最大范围限制。
400	INVALID_PARAMETER_VALUE_PASSWORD_MALFORMED	无效密码。指定的密码不符合密码复杂度限制。例如密码长度不符合限制等。
400	RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT	所选资源未售卖。
403	OPERATION_DENIED_CHARGE_TYPE_NOT_SUPPORT	该区域所选择的付费类型不支持。
400	RESOURCES_SOLDOUT_INSTANCE_TYPE	指定的实例机型已售罄。
400	INVALID_DISK_SIZE_LESS_MINIMUM	数据盘大小小于了最小值。
400	INVALID_DISK_SIZE_EXCEED_MAXIMUM	数据盘大小超过了最大限制。
403	OPERATION_DENIED_SUBNET_ZONE_MISMATCH	创建虚拟机实例加入的子网和所选可用区不一致
400	INVALID_SYSTEM_DISK_SIZE	无效系统盘大小，必须是10的倍数。
400	INVALID_SYSTEM_DISK_EXCEED_LIMIT	指定的系统盘大小超过了指定限制。
400	INVALID_INSTANCE_TYPE_ZONE_NO_SELL	所选规格在所选区域已售罄或未开售。
400	INVALID_DISK_ZONE_NO_SELL	当前区域数据盘不可用或已售罄，无法创建数据盘。
403	OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT	指定的区域不支持对应的公网网络计费方式。
400	INVALID_PASSWORD_MALFORMED	输入的密码格式错误，请检查字符都包含在规定的字符里。
400	INVALID_PARAMETER_BANDWIDTH_EXCEED	设置的公网带宽出口超过最大限制。
403	OPERATION_DENIED_SUBNET_IP_INSUFFICIENT	指定的子网内无足够可用的私有IP
400	INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED	设定的流量包大小超过最大限制。
400	INVALID_PARAMETER_TRAFFIC_PACKAGE	设定的流量包大小值不合法，必须是0.1或1的倍数。
403	INVALID_REGION_SECURITY_GROUP_NOT_SUPPORT	区域不支持安全组。

HTTP状态码

错误码

说明

400

INVALID_PARAMETER_INSTANCE_NAME_EXCEED

参数instanceName超过了长度限制，请注意模式串中的bits总和不要超过指定长度。

400

INVALID_PARAMETER_INSTANCE_NAME_MALFORMED

参数instanceName格式不正确，请注意输入值在规定的字符内。

403

OPERATION_FILED_INTERNET_CHARGE_TYPE_NOT_SUPPORT

指定的网络计费类型在当前区域不支持。

404

INVALID_IMAGE_NOT_FOUND

未找到指定的镜像。

404

INVALID_ZONE_NOT_FOUND

指定的可用区不存在。

404

INVALID_INSTANCE_TYPE_NOT_FOUND

未找到指定的实例规格。

403

INVALID_PARTITION_IMAGE_NOT_SET

自定义分区必须指定操作系统才可以进行。

403

OPERATION_DENIED_INSTANCE_QUOTA_EXCEED

机器创建数量超过了当前Team的总配额。

400

INVALID_BANDWIDTH_VALUE_EXCEED_MAXIMUM

指定的带宽大小超过了机型允许的最大范围限制。

400

INVALID_PARAMETER_VALUE_PASSWORD_MALFORMED

无效密码。指定的密码不符合密码复杂度限制。例如密码长度不符合限制等。

400

RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT

所选资源未售卖。

403

OPERATION_DENIED_CHARGE_TYPE_NOT_SUPPORT

该区域所选择的付费类型不支持。

400

RESOURCES_SOLDOUT_INSTANCE_TYPE

指定的实例机型已售罄。

400

INVALID_DISK_SIZE_LESS_MINIMUM

数据盘大小小于了最小值。

400

INVALID_DISK_SIZE_EXCEED_MAXIMUM

数据盘大小超过了最大限制。

403

OPERATION_DENIED_SUBNET_ZONE_MISMATCH

创建虚拟机实例加入的子网和所选可用区不一致

400

INVALID_SYSTEM_DISK_SIZE

无效系统盘大小，必须是10的倍数。

400

INVALID_SYSTEM_DISK_EXCEED_LIMIT

指定的系统盘大小超过了指定限制。

400

INVALID_INSTANCE_TYPE_ZONE_NO_SELL

所选规格在所选区域已售罄或未开售。

400

INVALID_DISK_ZONE_NO_SELL

当前区域数据盘不可用或已售罄，无法创建数据盘。

403

OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT

指定的区域不支持对应的公网网络计费方式。

400

INVALID_PASSWORD_MALFORMED

输入的密码格式错误，请检查字符都包含在规定的字符里。

400

INVALID_PARAMETER_BANDWIDTH_EXCEED

设置的公网带宽出口超过最大限制。

403

OPERATION_DENIED_SUBNET_IP_INSUFFICIENT

指定的子网内无足够可用的私有IP

400

INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED

设定的流量包大小超过最大限制。

400

INVALID_PARAMETER_TRAFFIC_PACKAGE

设定的流量包大小值不合法，必须是0.1或1的倍数。

403

INVALID_REGION_SECURITY_GROUP_NOT_SUPPORT

区域不支持安全组。

最后更新于3个月前