CreateZecInstances

1. 接口描述

本接口(CreateZecInstances)用于创建一台或多台虚拟机实例。

准备工作

• 查询机型规格：调用DescribeZoneInstanceConfigInfos 可以查询到规格信息。

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

• 查询密钥对：调用 DescribeKeyPairs可以查询到密钥对ID信息。

注意事项

• 实例创建成功后将自动开机启动，实例状态变为RUNNING, 如果创建失败，状态会变为CREATE_FAILED。

• 购买时需要确保账户账号状态正常。

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

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

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

2. 请求参数

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

参数名称	必选	类型	描述
zoneId	是	String	可用区ID。
imageId	是	String	指定有效的镜像ID。 可以通过DescribeImages取返回信息中的imageId字段。
instanceType	是	String	实例机型。 具体取值可通过调用接口DescribeZoneInstanceConfigInfos来获得最新的规格表。
instanceCount	是	Integer	要创建的实例数量。 可选值范围：[1, 100]。 默认值：1。
subnetId	是	String	子网ID。
timeZone	否	String	设置操作系统的时区。 默认值：America/Los_Angeles。
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。
password	否	String	实例的密码。 与keyId必须指定其中的一种（Windows和Generic类型的镜像无法指定密码和key）。 必须包含以下3种格式的字符：大小写字母: [a-zA-Z]数字: 0-9特殊字符: ~!@$^*-_=+。
keyId	否	String	密钥ID。 与password必须指定其中的一种（Windows和Generic类型的镜像无法指定密码和key）。 可调用接口DescribeKeyPairs来获得最新的密钥对信息。 关联密钥后，就可以通过对应的私钥来访问实例；密钥与密码不能同时指定，同时Windows操作系统不支持指定密钥。 示例值：key-YWD2QFOl。
nicNetworkType	否	NicNetworkType	网卡模式。 默认值：Auto。
systemDisk	否	SystemDisk	实例系统盘配置信息。 若不指定该参数，则按照系统默认值进行分配。 即操作系统要求的最小大小。
dataDisks	否	Array of DataDisk	实例数据盘配置信息。 若不指定该参数，则默认不额外购买数据盘。 目前只能附带1个数据盘。
securityGroupId	否	String	要配置在实例主网卡的安全组ID。 目前只能关联1个安全组。 如果未指定，会默认用VPC关联的安全组。
lanIp	否	String	分配的内网起始IP。 如果内网IP被使用,则会往后分配。
enableAgent	否	Boolean	是否安装启动Agent。 默认值：true。
enableIpForward	否	Boolean	是否开启IP转发。 默认值：false。
internetChargeType	否	InternetChargeType	公网IP的网络计费类型。 如果不指定，则不会分配公网IP地址。
trafficPackageSize	否	Float	流量包订购大小。 单位为TB。 该值必须在internetChargeType = ByTrafficPackage时才会生效。 可选值范围：[0.0, +)。
bandwidth	否	Integer	公网出带宽上限。 单位：Mbps。 当分配公网IP时需要指定。 可选值范围：[1, +)。
eipBindType	否	BindType	公网IP的绑定模式。 当分配公网IP时需要指定。 默认值：FullNat。
eipV4Type	否	EipNetworkType	公网IPv4的线路类型。 当分配公网IP时需要指定。 请确保所选子网的堆栈类型支持IPv4。 目前不支持三线IP随实例一起创建。
clusterId	否	String	共享带宽包ID。 当网络计费方式是共享带宽包计费(BandwidthCluster)时需要指定。
resourceGroupId	否	String	创建后实例所在的资源组ID，如不指定则放入默认资源组。
marketingOptions	否	MarketingInfo	市场营销的相关选项。
tags	否	TagAssociation	创建实例时关联的标签。 注意：·关联标签键不能重复。
userData	否	String	初始化命令。

3. 响应结果

参数名称	类型	描述
requestId	String	唯一请求 ID。 每次请求都会返回。定位问题时需要提供该次请求的 requestId。
orderNumber	String	订单编号。
instanceIdSet	Array of String	虚拟机实例ID列表。
instances	Array of DiskWithInstance	随机器创建的数据盘id集合。如果请求中没有指定数据盘，返回空数组。

4. 代码示例

示例

1. 使用最简单的参数创建实例。不分配公网IP地址。

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

Request：
{
  "zoneId": "asia-east-1a",
  "instanceType": "z2a.cpu.1",
  "imageId": "ubuntu2404_20240712",
  "instanceName": "Test-InstanceName",
  "keyId": "key-rcfljdP5",
  "subnetId": "1272168087751233112",
  "nicNetworkType": "Auto",
  "tags":
    {
      "tags": [
        {
          "key": "key1",
          "value": "value1"
        },
        {
          "key": "key2",
          "value": "value2"
        }
      ]
    }
}

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

2. 创建2台实例，分配公网IP。线路类型为BGP, 网络计费使用共享带宽包。带宽限速为10Mbps。

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

Request：
{
  "zoneId": "asia-east-1a",
  "instanceType": "z2a.cpu.1",
  "imageId": "ubuntu2404_20240712",
  "instanceName": "Test-InstanceName",
  "keyId": "key-rcfljdP5",
  "subnetId": "1272168087751233112",
  "internetChargeType": "BandwidthCluster",
  "bandwidth": 10,
  "clusterId": "<clusterId>",
  "eipV4Type": "BGPLine"
}

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

5. 开发者工具

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

6. 错误码

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

HTTP状态码	错误码	说明
400	INVALID_DISK_CATEGORY_TYPE	云盘的类型不合法。
400	INVALID_DISK_ILLEGAL_AMOUNT	数据盘的数量超过限制。
400	INVALID_DISK_SIZE_EXCEED_MAXIMUM	云盘最大值超限。
400	INVALID_DISK_SIZE_LESS_MINIMUM	云盘最小值超限。
400	INVALID_IMAGE_AGENT_NOT_SUPPORT	镜像不支持Agent。
400	INVALID_IMAGE_IPV6_NOT_SUPPORT	镜像不支持IPv6 Only。
404	INVALID_IMAGE_NOT_FOUND	镜像不存在。
400	INVALID_IMAGE_SIZE_EXCEED	镜像大小超过指定系统盘的大小。
400	INVALID_INSTANCE_COUNT_LIMITATION	实例的数量超过配额限制。
404	INVALID_INSTANCE_TYPE_NOT_FOUND	实例规格不存在。
400	INVALID_INSTANCE_TYPE_ZONE_NO_SELL	规格未开售或不存在。
404	INVALID_KEY_PAIR_NOT_FOUND	SSH密钥对不存在。
400	INVALID_LOGIN_SETTING_CONFLICT	密码和密钥对不能同时设置。
400	INVALID_PARAMETER_USER_DATA_EXCEED	实例命令超过长度限制。
400	INVALID_PARAMETER_INSTANCE_NAME_EXCEED	实例名称超过长度限制。
400	INVALID_PARAMETER_INSTANCE_NAME_EXCEED_MINIMUM_LENGTH	实例名称长度小于最小限制。
400	INVALID_PARAMETER_INSTANCE_NAME_MALFORMED	实例名称的格式不合法。
400	INVALID_PARAMETER_TRAFFIC_PACKAGE	流量包大小必须是0.1的倍数。
400	INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED	流量包大小超过最大限制。
400	INVALID_PASSWORD_MALFORMED	密码格式错误。
404	INVALID_SUBNET_NOT_FOUND	子网不存在。
400	INVALID_SYSTEM_DISK_EXCEED_LIMIT	系统盘大小超过限制。
404	INVALID_TIME_ZONE_NOT_FOUND	系统时区不存在。
404	INVALID_ZONE_NOT_FOUND	可用区不存在。
400	OPERATION_DENIED_EIP_INSUFFICIENT	公网IP的库存不足，无法操作。
400	OPERATION_DENIED_EIP_UNSUPPORT_NETWORK_TYPE	EIP网络计费方式不支持。
403	OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT	IP网络计费方式不支持。
403	OPERATION_DENIED_STACK_TYPE_NOT_SUPPORT	堆栈类型不支持。
403	OPERATION_DENIED_SUBNET_ZONE_MISMATCH	子网的区域和可用区的区域不一致。
400	STOCK_INSUFFICIENT	库存不足。
400	UNSUPPORT_SUBNET_TYPE_FOR_INTERNET_CHARGE_TYPE	子网堆栈类型不支持公网。
404	INVALID_PASSWORD_KEY_PAIR_MISSING	未指定密码或密钥对。
404	INVALID_SECURITY_GROUP_NOT_FOUND	安全组不存在。
400	OPERATION_DENIED_SUBNET_TYPE_NOT_SUPPORT_IPV4	子网堆栈类型不包括IPv4。
403	OPERATION_DENIED_NIC_NETWORK_TYPE_NOT_SUPPORT	网卡模式不支持。