> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/cn/bmc/bare-metal-instance/createinstances.md). # CreateInstances ## 1. 接口描述 本接口(CreateInstances)用于创建一个或多个指定配置的实例。 #### 准备工作 * 查询库存：调用[`DescribeAvailableResources`](/api-reference/cn/bmc/bare-metal-instance/describeavailableresources.md)查看指定地区的资源供给情况。 * 查询密钥对：调用[`DescribeKeyPairs`](https://github.com/zenlayer/zenlayercloud-api-doc-cn/tree/main/security/key-service/key-pair/describekeypairs.md) 可以查询到密钥对ID信息。 * 查询机型规格：调用[`DescribeInstanceTypes`](/api-reference/cn/bmc/bare-metal-instance/describeinstancetypes.md) 可以查询到区域支持的规格信息。 * 查询镜像：调用[`DescribeImages`](/api-reference/cn/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/bmc/datastructure.md#chargetype) |

付费类型。

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

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

| | instanceTypeId | 是 | String |

实例机型ID。

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

| | internetChargeType | 是 | [InternetChargeType](/api-reference/cn/bmc/datastructure.md#internetchargetype) | 网络计费类型。 | | instanceChargePrepaid | 否 | [ChargePrepaid](/api-reference/cn/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/bmc/datastructure.md#raidconfig) | 磁盘阵列配置。 | | partitions | 否 | Array of [Partition](/api-reference/cn/bmc/datastructure.md#partition) |

分区配置。

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

| | nic | 否 | [Nic](/api-reference/cn/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/bmc/datastructure.md#marketinginfo) | 市场营销活动相关信息。 | | tags | 否 | [TagAssociation](/api-reference/cn/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格式不正确，请注意输入值在规定的字符内。 |