# CreateInstances ## 1. 接口描述 本接口(CreateInstances)用于创建一个或多个指定配置的实例。 #### 准备工作 * 查询库存：调用[`DescribeAvailableResources`](/api-reference/cn/compute/bmc/bare-metal-instance/describeavailableresources.md)查看指定地区的资源供给情况。 * 查询密钥对：调用[`DescribeKeyPairs`](https://github.com/zenlayer/zenlayercloud-api-doc-cn/blob/main/security/key-service/key-pair/describekeypairs.md) 可以查询到密钥对ID信息。 * 查询机型规格：调用[`DescribeInstanceTypes`](/api-reference/cn/compute/bmc/bare-metal-instance/describeinstancetypes.md) 可以查询到区域支持的规格信息。 * 查询镜像：调用[`DescribeImages`](/api-reference/cn/compute/bmc/bare-metal-instance/describeimages.md)可以查询到镜像信息。 * 成本估算：了解裸机云的的计费方式。更多详情，请参见[计费方式概述](https://docs.console.zenlayer.com/welcome/pricing/bare-metal-cloud-pricing/billing-method)。 {% hint style="info" %} **注意事项** * 实例创建成功后将自动开机启动，实例状态变为`RUNNING`(运行中)。 * 预付费实例的购买会预先扣除本次实例购买所需金额，如果余额不足，请求将会失败。后付费实例购买时需要确保账户账号状态正常。 * 调用本接口创建实例，支持代金券自动抵扣，详情请参考代金券选用规则。 * 本接口为异步接口，当创建实例请求下发成功后会返回一个实例`ID`列表，此时创建实例操作并未立即完成。在此期间实例的状态将会处于`PENDING`或`CREATING`，实例创建结果可以通过调用`DescribeInstances` 接口查询，如果实例状态(instanceStatus)由`CREATING`(创建中)或`PENDING`(等待创建）变为`RUNNING`(运行中)，则代表实例创建成功，`CREATE_FAILED`代表实例创建失败，创建过程中不可对实例进行任何操作。 * 单次最多能创建**100**台实例。 {% endhint %} ## 2. 请求参数 以下请求参数列表仅列出了接口中需要的请求参数 | 参数名称 | 必选 | 类型 | 描述 | | ----------------------- | -- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | zoneId | 是 | String | 实例所属的可用区ID。 | | instanceChargeType | 是 | [ChargeType](/api-reference/cn/compute/bmc/datastructure.md#chargetype) |

付费类型。

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

默认只支持预付费计费方式， 如果需要后付费， 请联系Support开通后付费权限。

| | instanceTypeId | 是 | String |

实例机型ID。

具体取值可通过调用接口DescribeInstanceTypes来获得最新的规格表。

| | internetChargeType | 是 | [InternetChargeType](/api-reference/cn/compute/bmc/datastructure.md#internetchargetype) | 网络计费类型。 | | instanceChargePrepaid | 否 | [ChargePrepaid](/api-reference/cn/compute/bmc/datastructure.md#chargeprepaid) |

预付费模式。

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

| | imageId | 否 | String |

指定有效的镜像ID。

可通过以下方式获取可用的镜像ID：通过调用接口 DescribeImages

，传入InstanceType获取当前机型支持的镜像列表，取返回信息中的ImageId字段。

也可以不指定镜像，如果不指定镜像，后续可以通过IPMI进行安装。使用iPXE安装镜像，请指定ipxeUrl字段，且该字段不必传。

| | 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登录的密码。请妥善保管。

密钥ID与密码必须并且只能指定其中一个。

| | keyId | 否 | String |

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

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

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

示例值：key-YWD2QFOl

| | internetMaxBandwidthOut | 否 | Integer |

公网出带宽上限。

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

可选值范围：\[1, +)

默认值：1

| | trafficPackageSize | 否 | Float |

流量包订购大小。

单位为TB。该值仅限当 internetChargeType = ByTrafficPackage 生效。

如果没有传则会默认以赠送的流量包大小

可选值范围：\[0.0, +)

| | subnetId | 否 | String |

虚拟子网ID 。

您可以调用DescribeVpcSubnets查询已创建的交换机的相关信息。

| | raidConfig | 否 | [RaidConfig](/api-reference/cn/compute/bmc/datastructure.md#raidconfig) | 磁盘阵列配置。 | | partitions | 否 | Array of [Partition](/api-reference/cn/compute/bmc/datastructure.md#partition) |

分区配置。

如果未安装操作系统，将不能设置分区

| | nic | 否 | [Nic](/api-reference/cn/compute/bmc/datastructure.md#nic) | 网卡配置。 | | ipxeUrl | 否 | String |

iPXE URL 地址。

传入参数后，将根据指定URL进行iPXE安装， 如果指定为netboot，将使用netboot iPXE方式进行安装。相关帮助文档：Deploy

a Custom Image Using iPXE

| | userData | 否 | String |

用户数据。

在安装实例时可以通过指定用户数据进行配置实例。当实例首次启动时，用户数据将以文本的方式传递到云服务器中，并执行该文本。支持的最大数据大小为 32KB。

| | enablePrimaryIPv6 | 否 | Boolean |

是否启用实例主IPv6。

false为不启用主IPv6，此时将不能为实例配置弹性IPv6。默认为true。

默认值：true

| | clusterId | 否 | String | 带宽组ID。当 internetChargeType = ByBandwidthCluster 时必传。 | | marketingOptions | 否 | [MarketingInfo](/api-reference/cn/compute/bmc/datastructure.md#marketinginfo) | 市场营销活动相关信息。 | | tags | 否 | [TagAssociation](/api-reference/cn/compute/bmc/datastructure.md#tagassociation) |

创建实例时关联的标签。

注意: 关联标签键不能重复。

| | enableGatewayMode | 否 | Boolean |

是否启用网关模式。

启用后，该机器上绑定的IP将作为网关模式使用，用于转发下游网络流量，且仅支持绑定EIP掩码段类IP。开启后需要进入机器完成进一步配置。若未开启则是普通路由模式。

请注意：网关模式默认为不支持，如需使用请联系Console Support。

| ## 3. 响应结果 | 参数名称 | 类型 | 描述 | | ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | requestId | String |

唯一请求 ID。

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

| | instanceIdSet | Array of String |

实例ID列表。

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

| | orderNumber | String | 订单编号。 | ## 4. 代码示例 {% tabs %} {% tab title="示例" %} **1. 用最简单的参数创建一台后付费的实例**\ 在Seoul A创建一台后付费实例，规格为M6C，其带宽计费为固定带宽，密码随机生成，不安装任何镜像，带宽大小为默认的1Mbps。 POST /api/v2/bmc HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateInstances 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。 ```json POST /api/v2/bmc HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateInstances 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。 ```json POST /api/v2/bmc HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateInstances 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" } } ``` {% endtab %} {% endtabs %} ## 5. 开发者工具 Zenlayer Cloud API 2.0 提供了配套的[开发工具集（SDK）](/api-reference/cn/api-introduction/toolkit.md)，未来会陆续支持更多开发语言，方便快速接入和使用Zenlayer的产品和服务。 ## 6. 错误码 下面包含业务逻辑中遇到的错误码，其他错误码见[公共错误码](/api-reference/cn/api-introduction/instruction/commonerrorcode.md) | HTTP状态码 | 错误码 | 说明 | | ------- | ---------------------------------------------------------- | ----------------------------------------- | | 404 | INVALID\_ZONE\_NOT\_FOUND | 指定的可用区不存在。 | | 400 | INVALID\_PARAMETER\_VALUE\_RAID\_DISK\_SEQUENCE\_RANGE | 自定义raid配置时硬盘的序号超过了机型的硬盘数量。 | | 404 | INVALID\_SUBNET\_NOT\_FOUND | 内网Subnet不存在。 | | 404 | INVALID\_INSTANCE\_TYPE\_NOT\_FOUND | 指定的机型不存在。 | | 400 | INVALID\_PARAMETER\_VALUE\_RAID\_DISK\_SEQUENCE\_DUPLICATE | 自定义raid配置时硬盘的序号存在重复的值。 | | 400 | INVALID\_PARAMETER\_INSTANCE\_LOGIN\_CONFLICT | 不能同时指定密码登录和SSH Key登录。 | | 400 | INVALID\_PARTITION\_MALFORMED | 分区文件类型或路径有格式问题。 | | 404 | INVALID\_IMAGE\_NOT\_FOUND | 未找到指定的镜像。 | | 400 | INVALID\_PARAMETER\_NIC\_NAME\_MALFORMED | 公网网卡或内网网卡名称不符合规范，请注意字符是否在规定的范围内。 | | 400 | INVALID\_INSTANCE\_TYPE\_RAID\_NOT\_SUPPORT | 当前机型不支持指定的raid级别。 | | 400 | INVALID\_RAID\_CONFIG\_FAST\_CUSTOM\_CONFLICT | 自定义raid和快速raid只能选择其中一种。 | | 403 | INVALID\_CHARGE\_TYPE\_NOT\_SUPPORT | 当前账号不支持指定的付费类型 | | 403 | OPERATION\_DENIED\_INSTANCE\_QUOTA\_EXCEED | 机器创建数量超过了当前Team的总配额。 | | 400 | INVALID\_PARAMETER\_SSH\_KEY\_DUPLICATE | ssh密钥值不合法，值存在重复。 | | 400 | INVALID\_INSTANCE\_TYPE\_QUICK\_RAID\_NOT\_SUPPORT | 当前机型不支持快速raid级别。请使用自定义raid。 | | 400 | INVALID\_PARAMETER\_NIC\_NAME\_CONFLICT | 公网网卡名称和内网网卡不能相同。 | | 400 | INVALID\_PARAMETER\_VALUE\_PASSWORD\_MALFORMED | 无效密码。指定的密码不符合密码复杂度限制。例如密码长度不符合限制等。 | | 400 | INVALID\_PARTITION\_NO\_TYPE | 分区文件类型错误。 | | 400 | INVALID\_PARTITION\_INVALID\_ORDER | windows 分区时盘符必须按字母顺序以此填写，比如CDEFG。 | | 400 | INVALID\_SUBNET\_PRIVATE\_IP\_INSUFFICIENT | 子网下内网的IP不足以分配给创建的机器。 | | 400 | INVALID\_PARTITION\_MISSING\_REQUIRED\_FILE\_PATH | 分区时缺少必须的文件路径（盘符），windos必须包含c，linux必须包含/。 | | 400 | INVALID\_PARAMETER\_SSH\_KEY\_MALFORMED | 输入的ssh key格式不正确，一般以rsa开头。 | | 400 | INVALID\_PARTITION\_DUPLICATE\_FILE\_PATH | 分区的文件路径或盘符有重复。 | | 400 | INVALID\_PARAMETER\_VALUE\_RAID\_DISK\_MISMATCH | 自定义raid配置时传的硬盘数量和Raid等级所要求的硬盘数量不匹配。 | | 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_EXCEED | 参数instanceName格式不正确，请注意输入值在规定的字符内。 | | 403 | INVALID\_PARTITION\_IMAGE\_NOT\_SET | 自定义分区必须指定操作系统才可以进行。 | | 400 | INVALID\_PARAMETER\_HOSTNAME\_EXCEED | 参数hostname超过了长度限制，请注意模式串中的bits总和不要超过指定长度。 | | 400 | INVALID\_SUBNET\_ZONE\_MISMATCH | 子网不在指定的可用区。 | | 400 | INVALID\_PARAMETER\_VALUE\_RAID\_DISK\_DISORDER | 自定义raid配置时硬盘的序号必须按顺序填写，比如\[1,2,3]。 | | 400 | INVALID\_PARAMETER\_HOSTNAME\_MALFORMED | 参数hostname格式不正确，请注意输入值在规定的字符内。 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.console.zenlayer.com/api-reference/cn/compute/bmc/bare-metal-instance/createinstances.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.