CreateInstances

1. 接口描述

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

准备工作

• 查询库存：调用DescribeAvailableResources查看指定地区的资源供给情况。

• 查询机型规格：调用DescribeInstanceTypes 可以查询到区域支持的规格信息。

• 查询镜像：调用DescribeImages可以查询到镜像信息。

• 成本估算：了解裸机云的的计费方式。更多详情，请参见计费方式概述。

注意事项

• 实例创建成功后将自动开机启动，实例状态变为RUNNING(运行中)。

• 预付费实例的购买会预先扣除本次实例购买所需金额，如果余额不足，请求将会失败。后付费实例购买时需要确保账户账号状态正常。

• 调用本接口创建实例，支持代金券自动抵扣，详情请参考代金券选用规则。

• 本接口为异步接口，当创建实例请求下发成功后会返回一个实例ID列表，此时创建实例操作并未立即完成。在此期间实例的状态将会处于PENDING或CREATING，实例创建结果可以通过调用DescribeInstances 接口查询，如果实例状态(instanceStatus)由CREATING(创建中)或PENDING(等待创建）变为RUNNING(运行中)，则代表实例创建成功，CREATE_FAILED代表实例创建失败，创建过程中不可对实例进行任何操作。

• 单次最多能创建100台实例。

2. 请求参数

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

参数名称	必选	类型	描述
zoneId	是	String	实例所属的可用区ID。
instanceChargeType	是	String	付费类型。 PREPAID：预付费，即包年包月 POSTPAID：后付费
instanceChargePrepaid	否	ChargePrepaid	预付费模式。 即包年包月相关参数设置。通过该参数可以指定包年包月实例的购买时长等属性。若指定实例的付费模式为预付费则该参数必传。
instanceTypeId	是	String	实例机型ID。 具体取值可通过调用接口DescribeInstanceTypes来获得最新的规格表。
imageId	否	String	指定有效的镜像ID。 可通过以下方式获取可用的镜像ID：通过调用接口 DescribeImages ，传入InstanceType获取当前机型支持的镜像列表，取返回信息中的ImageId字段。 也可以不指定镜像，如果不指定镜像，后续可以通过IPMI进行安装。使用iPXE安装镜像，请指定ipxeUrl字段，且该字段不必传。
ipxeUrl	否	String	iPXE URL 地址。 传入参数后，将根据指定URL进行iPXE安装， 如果指定为netboot，将使用netboot iPXE方式进行安装。相关帮助文档：Deploy a Custom Image Using iPXE
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。
hostname	否	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]。 默认值为hostname。
amount	否	Integer	指定创建实例的数量。 取值范围：1~100。 默认值：1。
password	否	String	实例的密码。 必须是 8-16 个字符，包含大写字母、小写字母、数字和特殊字符。特殊符号可以是：1~!@$^*-_=+。该密码也是作为IPMI登录的密码。请妥善保管。 密钥与密码必须并且只能指定其中一个。
sshKeys	否	Array of String	密钥列表。 使用了密钥登录，密码登录将会被禁止。 密钥最多支持5个。 Windowsh和exsi操作系统的实例 ，忽略该参数。默认为空。即使填写了该参数，仍旧只执行password的内容。 如果imageId未指定，则会忽略该参数。 密钥与密码必须并且只能指定其中一个。
internetChargeType	是	String	网络计费类型。 取值范围请看InternetChargeType。
internetMaxBandwidthOut	否	Integer	公网出带宽上限。 单位：Mbps。默认值：1Mbps。不同机型带宽上限范围不一致，具体限制详见购买网络带宽。
trafficPackageSize	否	Float	流量包订购大小。 单位为TB。该值仅限当 internetChargeType = ByTrafficPackage 生效。 如果没有传则会默认以赠送的流量包大小
subnetId	否	String	虚拟子网ID 。 您可以调用DescribeVpcSubnets查询已创建的交换机的相关信息。
raidConfig	否	RaidConfig	磁盘阵列配置。
partitions	否	Array of Partition	分区配置。 如果未安装操作系统，将不能设置分区
nic	否	Nic	网卡配置。
enablePrimaryIPv6	否	Boolean	是否启用实例主IPv6。 false为不启用主IPv6，此时将不能为实例配置弹性IPv6。默认为true。

3. 响应结果

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

4. 代码示例

示例

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

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

Request:
{
    "instanceChargeType": "POSTPAID",
    "instanceTypeId": "M6C",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
        "instanceIdSet": ["instanceId1"],
        "orderNumber" : "orderNumber1"
    }
}

2. 创建2台预付费的实例 ****在Seoul A 创建2台预付费付费实例，规格为M6C，两台实例的名称分别为：SEL-M6C-01, SEL-M6C-02, 密码Password-12345~，镜像ID: 5ace1756-2230-4d1d-8fc6-84f1897ef397，指定了公网和内网网卡名称wan0和lan0, 带宽计费为固定带宽，带宽大小为10Mbps。

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

Request:
{
    "instanceChargeType": "PREPAID",
    "amount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-M6C-[1,2]",
    "hostname": "SEL-M6C-[1,2]",
    "internetMaxBandwidthOut": 10,
    "password": "Password-12345~",
    "nic": {
        "wanName": "wan0",
        "lanName": "lan0"
    },
    "instanceTypeId": "M6C",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A", 
    "imageId": "5ace1756-2230-4d1d-8fc6-84f1897ef397"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId3", "instanceId4"],
        "orderNumber" : "orderNumber2"
    }
}

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

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

Request:
{
    "instanceChargeType": "PREPAID",
    "amount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-M6C-[1,2]",
    "hostname": "SEL-M6C-[1,2]",
    "internetMaxBandwidthOut": 10,
    "password": "Password-12345~",
    "nic": {
        "wanName": "wan0",
        "lanName": "lan0"
    },
    "instanceTypeId": "M6C",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A", 
    "imageId": "5ace1756-2230-4d1d-8fc6-84f1897ef397",
    "trafficPackageSize": 10 
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId5", "instanceId6"],
        "orderNumber" : "orderNumber3"
    }
}

5. 开发者工具

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

6. 错误码

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

HTTP状态码	错误码	说明
400	INVALID_PARAMETER_HOSTNAME_EXCEED	参数hostname超过了长度限制，请注意模式串中的bits总和不要超过指定长度。
400	INVALID_PARAMETER_HOSTNAME_MALFORMED	参数hostname格式不正确，请注意输入值在规定的字符内。
400	INVALID_PARAMETER_INSTANCE_NAME_EXCEED	参数instanceName超过了长度限制，请注意模式串中的bits总和不要超过指定长度。
400	INVALID_PARAMETER_INSTANCE_NAME_EXCEED	参数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	INVALID_PARAMETER_INSTANCE_LOGIN_CONFLICT	不能同时指定密码登录和SSH Key登录。
400	INVALID_PARAMETER_SSH_KEY_MALFORMED	输入的ssh key格式不正确，一般以rsa开头。
400	INVALID_RAID_CONFIG_FAST_CUSTOM_CONFLICT	自定义raid和快速raid只能选择其中一种。
400	INVALID_INSTANCE_TYPE_RAID_NOT_SUPPORT	当前机型不支持指定的raid级别。
400	INVALID_PARAMETER_NIC_NAME_CONFLICT	公网网卡名称和内网网卡不能相同。
400	INVALID_PARAMETER_NIC_NAME_MALFORMED	公网网卡或内网网卡名称不符合规范，请注意字符是否在规定的范围内。
400	INVALID_PARTITION_SIZE_NOT_FULL	分区大小没有到达应分区的规定容量。
400	INVALID_PARTITION_DUPLICATE_FILE_PATH	分区的文件路径或盘符有重复。
400	INVALID_PARTITION_MISSING_REQUIRED_FILE_PATH	分区时缺少必须的文件路径（盘符），windos必须包含c，linux必须包含/。
400	INVALID_PARTITION_MALFORMED	分区文件类型或路径有格式问题。
400	INVALID_PARTITION_NO_TYPE	分区文件类型错误。
400	INVALID_PARTITION_INVALID_ORDER	windows 分区时盘符必须按字母顺序以此填写，比如CDEFG。
400	INVALID_PARAMETER_VALUE_RAID_DISK_MISMATCH	自定义raid配置时传的硬盘数量和Raid等级所要求的硬盘数量不匹配。
400	INVALID_PARAMETER_VALUE_RAID_DISK_DISORDER	自定义raid配置时硬盘的序号必须按顺序填写，比如[1,2,3]。
400	INVALID_PARAMETER_VALUE_RAID_DISK_SEQUENCE_RANGE	自定义raid配置时硬盘的序号超过了机型的硬盘数量。
400	INVALID_PARAMETER_VALUE_RAID_DISK_SEQUENCE_DUPLICATE	自定义raid配置时硬盘的序号存在重复的值。
400	RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT	所选资源未售卖。
403	OPERATION_DENIED_CHARGE_TYPE_NOT_SUPPORT	该区域所选择的付费类型不支持。
400	RESOURCES_SOLDOUT_INSTANCE_TYPE	指定的实例机型已售罄。
403	INVALID_CHARGE_TYPE_NOT_SUPPORT	付费类型不支持，请联系Support进行开通。
404	INVALID_SUBNET_NOT_FOUND	内网Subnet不存在。
400	INVALID_SUBNET_PRIVATE_IP_INSUFFICIENT	Subnet子网下内网的IP不足以分配给创建的机器。
400	INVALID_SUBNET_ZONE_MISMATCH	Subnet不在指定的Zone。
400	INVALID_PARAMETER_SSH_KEY_DUPLICATE	ssh密钥值不合法，值存在重复。
400	INVALID_INSTANCE_TYPE_QUICK_RAID_NOT_SUPPORT	当前机型不支持快速raid级别。请使用自定义raid。