云服务器 ECS：RunInstances - 批量创建实例

实例所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

镜像 ID，启动实例时选择的镜像资源。您可以通过 DescribeImages 查询您可以使用的镜像资源。如果您不指定LaunchTemplateId或LaunchTemplateName以确定启动模板，也不通过指定ImageFamily选用镜像族系最新可用镜像，则ImageId为必选参数。

镜像族系名称，通过设置该参数来获取当前镜像族系内最新可用镜像来创建实例。

镜像族系的名称长度为 2~128 个字符。镜像族系名称不能以特殊字符、数字、http://、https://开头，只可包含特殊字符中的"."、"_"、"-"和":"。

您需要注意：

• 设置了参数ImageId，则不能设置该参数。
• 未设置参数ImageId，但指定的LaunchTemplateId或LaunchTemplateName对应的启动模板设置了ImageId，则不能设置该参数。
• 未设置ImageId，且指定的LaunchTemplateId或LaunchTemplateName对应的启动模板未设置ImageId，则可以设置该参数。
• 未设置ImageId，且未设置LaunchTemplateId、LaunchTemplateName参数，则可以设置该参数。

实例的资源规格。如果您不指定LaunchTemplateId或LaunchTemplateName以确定启动模板，InstanceType为必选参数。

• 产品选型：参见实例规格族或调用 DescribeInstanceTypes 查看目标实例规格的性能数据，或者参见选型配置了解如何选择实例规格。
• 查询库存：调用 DescribeAvailableResource 查看指定地域或者可用区内的资源供给情况。

新创建实例所属于的安全组 ID。同一个安全组内的实例之间可以互相访问，一个安全组能容纳的实例数量视安全组类型而定，具体请参见使用限制的安全组章节。

如果您不设置LaunchTemplateId或LaunchTemplateName以确定实例启动模板，则安全组 ID 为必选参数。您需要注意：

• 您可以通过SecurityGroupId设置一个安全组，也可以通过SecurityGroupIds.N设置一个或多个安全组，但不支持同时设置SecurityGroupId和SecurityGroupIds.N。

• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置SecurityGroupId或SecurityGroupIds.N，只能设置NetworkInterface.N.SecurityGroupId或NetworkInterface.N.SecurityGroupIds.N。

虚拟交换机 ID。如果您创建的是 VPC 类型 ECS 实例，必须指定虚拟交换机 ID，且安全组和虚拟交换机在同一个专有网络 VPC 中。您可以调用 DescribeVSwitches 查询已创建的交换机的相关信息。

您需要注意：

• 如果您设置了VSwitchId参数，则设置的ZoneId参数必须和交换机所在的可用区保持一致。您也可以不设置ZoneId参数，系统将自动选择指定交换机所在的可用区。

• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置VSwitchId，只能设置NetworkInterface.N.VSwitchId。

实例名称。长度为 2~128 个字符，支持 Unicode 中 letter 分类下的字符（其中包括英文、中文等）和数字。可以包含半角冒号（:）、下划线（_）、半角句号（.）或者短划线（-）。默认值为实例的InstanceId。

创建多台 ECS 实例时，您可以批量设置有序的实例名称，并且可以包含方括号（[]）和逗号（,）。具体操作，请参见批量设置有序的实例名称或主机名称。

实例的描述。长度为 2~256 个英文或中文字符，不能以http://和https://开头。

公网入带宽最大值，单位为 Mbit/s。取值范围：

• 当所购公网出带宽小于等于 10 Mbit/s 时：1~10，默认为 10。
• 当所购公网出带宽大于 10 Mbit/s 时：1~InternetMaxBandwidthOut的取值，默认为InternetMaxBandwidthOut的取值。

公网出带宽最大值，单位为 Mbit/s。取值范围：0~100。

默认值：0。

实例主机名称。限制说明如下：

• 半角句号（.）和短划线（-）不能作为首尾字符，更不能连续使用。
• Windows 实例：字符长度为 2~15，不支持半角句号（.），不能全是数字。允许包含大小写英文字母、数字和短划线（-）。
• 其他类型实例（Linux 等）：
  • 字符长度为 2~64，支持多个半角句号（.），点之间为一段，每段允许包含大小写英文字母、数字和短划线（-）。
  • 支持通过占位符${instance_id}将实例 ID 写入HostName参数。例如：HostName=k8s-${instance_id}，并且创建的 ECS 实例 ID 为i-123abc****，则该实例的主机名为k8s-i-123abc****。

创建多台 ECS 实例时，您可以：

• 批量设置有序的主机名。具体操作，请参见批量设置有序的实例名称或主机名称。
• 通过HostNames.N参数，为多台实例分别设置主机名。需要注意HostName参数和HostNames.N参数不能同时设置。

当创建多台实例时，是否为HostName和InstanceName自动添加有序后缀。有序后缀从 001 开始递增，最大不能超过 999。取值范围：

• true：添加。
• false：不添加。

默认值：false。

当HostName或InstanceName按照指定排序格式设置，未设置命名后缀name_suffix，即命名格式为name_prefix[begin_number,bits]时，UniqueSuffix不生效，名称仅按照指定顺序排序。

更多信息，请参见批量设置有序的实例名称或主机名称。

实例的密码。长度为 8 至 30 个字符，必须同时包含大小写英文字母、数字和特殊符号中的三类字符。特殊符号可以是：

()`~!@#$%^&*-_+=|{}[]:;'<>,.?/

其中，Windows 实例不能以正斜线（/）为密码首字符。

是否使用镜像预设的密码。取值范围：

• true：使用。
• false：不使用。

默认值：false。

实例所属的可用区 ID，您可以调用 DescribeZones 获取可用区列表。

默认值：系统自动选择。

网络计费类型。取值范围：

• PayByBandwidth：按固定带宽计费。
• PayByTraffic：按使用流量计费。

默认值：PayByTraffic。

系统盘大小，单位为 GiB。取值范围：

• 普通云盘：20~500。
• ESSD 云盘：
  • PL0：1~2048。
  • PL1：20~2048。
  • PL2：461~2048。
  • PL3：1261~2048。
• ESSD AutoPL 云盘：1~2048。
• 其他云盘类型：20~2048。

该参数的取值必须大于或者等于 max{1, ImageSize}。

默认值：max{40, 参数 ImageId 对应的镜像大小}。

系统盘的云盘种类。取值范围：

• cloud_efficiency：高效云盘。
• cloud_ssd：SSD 云盘。
• cloud_essd：ESSD 云盘。
• cloud：普通云盘。
• cloud_auto：ESSD AutoPL 云盘。
• cloud_essd_entry：ESSD Entry 云盘。

已停售的实例规格且非 I/O 优化实例默认值为 cloud，否则默认值为 cloud_efficiency。

系统盘名称。长度为 2~128 个字符，支持 Unicode 中 letter 分类下的字符（其中包括英文、中文和数字等）。可以包含半角冒号（:）、下划线（_）、半角句号（.）或者短划线（-）。

系统盘的描述。长度为 2~256 个英文或中文字符，不能以http://和https://开头。

创建 ESSD 云盘作为系统盘使用时，设置云盘的性能等级。取值范围：

• PL0：单盘最高随机读写 IOPS 1 万。
• PL1（默认）：单盘最高随机读写 IOPS 5 万。
• PL2：单盘最高随机读写 IOPS 10 万。
• PL3：单盘最高随机读写 IOPS 100 万。

有关如何选择 ESSD 性能等级，请参见 ESSD 云盘。

系统盘采用的自动快照策略 ID。

是否为 I/O 优化实例。已停售的实例规格实例默认值是 none，其他实例规格默认值是 optimized。取值范围：

• none：非 I/O 优化。
• optimized：I/O 优化。

实例自定义数据。必须填写已采用 Base64 编码后的数据，且在进行 Base64 编码前自定义数据内容的大小不能超过 32 KB。

有关实例自定义数据的使用限制、格式以及运行频率的详细信息，请参见实例自定义数据。

密钥对名称。

实例 RAM 角色名称。您可以使用 RAM API ListRoles 查询您已创建的实例 RAM 角色。

指定创建 ECS 实例的数量。取值范围：1~100。

创建成功的 ECS 数量与指定的 Amount 和 minAmount 数量有关：

• 不指定 minAmount 时：按照 Amount 数量创建，库存不满足则 API 返回创建失败，同时一台也不会创建。

• 指定 minAmount 时：

  • 当 ECS 库存数量＜minAmount：不会创建 ECS，同时 API 返回创建失败。
  • 当 minAmount≤ECS 库存数量＜Amount，按照库存数量创建实例，API 返回创建成功。
  • 当 ECS 库存数量≥Amount，按照指定的 Amount 创建，API 返回创建成功。

默认值：1。

指定 ECS 实例最小购买数量。取值范围：1~100。

创建成功的 ECS 数量与指定的 Amount 和 minAmount 数量有关：

• 不指定 minAmount 时：按照 Amount 数量创建，库存不满足则 API 返回创建失败，同时一台也不会创建。

• 指定 minAmount 时：

  • 当 ECS 库存数量＜minAmount：不会创建 ECS，同时 API 返回创建失败。
  • 当 minAmount≤ECS 库存数量＜Amount，按照库存数量创建实例，API 返回创建成功。
  • 当 ECS 库存数量≥Amount，按照指定的 Amount 创建，API 返回创建成功。

按量付费实例的自动释放时间。按照ISO 8601标准表示，使用 UTC+0 时间。格式为：yyyy-MM-ddTHH:mm:ssZ。

• 如果秒（ss）取值不是00，则自动取为当前分钟（mm）开始时。

• 最短释放时间为当前时间半小时之后。

• 最长释放时间不能超过当前时间三年。

按量付费实例的竞价策略。当参数InstanceChargeType取值为PostPaid时生效。取值范围：

• NoSpot：正常按量付费实例。
• SpotWithPriceLimit：设置上限价格的抢占式实例。
• SpotAsPriceGo：系统自动出价，跟随当前市场实际价格。

默认值：NoSpot。

抢占式实例的保留时长，单位为小时。 默认值：1。取值范围：

• 1：创建后阿里云会保证实例运行 1 小时不会被自动释放；超过 1 小时后，系统会自动比较出价与市场价格、检查资源库存，来决定实例的持有和回收。
• 0：创建后，阿里云不保证实例运行 1 小时，系统会自动比较出价与市场价格、检查资源库存，来决定实例的持有和回收。

实例回收前 5 分钟阿里云会通过 ECS 系统事件向您发送通知。抢占式实例按秒计费，建议您结合具体任务执行耗时来选择合适的保留时长。

设置实例的每小时最高价格。支持最大 3 位小数，参数SpotStrategy取值为SpotWithPriceLimit时生效。

抢占实例中断模式。取值范围：

• Terminate：直接释放实例。

• Stop：实例进入节省停机模式。

  关于节省停机模式的更多说明，请参见按量付费实例节省停机模式。

默认值：Terminate。

是否开启安全加固。取值范围：

• Active：启用安全加固，只对公共镜像生效。
• Deactive：不启用安全加固，对所有镜像类型生效。

保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。

实例所属的 HPC 集群 ID。

创建 SCC 实例时，该参数为必选参数。您可以参考 CreateHpcCluster 创建 HPC 集群。

是否只预检此次请求。取值范围：

• true：发送检查请求，不会创建实例。检查项包括是否填写了必需参数、请求格式、业务限制和 ECS 库存。如果检查不通过，则返回对应错误。如果检查通过，则返回错误码DryRunOperation。
• false（默认）：发送正常请求，通过检查后直接创建实例。

是否在专有宿主机上创建 ECS 实例。由于专有宿主机不支持创建抢占式实例，指定DedicatedHostId参数后，会自动忽略请求中的SpotStrategy和SpotPriceLimit设置。

您可以通过 DescribeDedicatedHosts 查询专有宿主机 ID 列表。

启动模板 ID。更多信息，请调用 DescribeLaunchTemplates 。

使用启动模板创建实例时，您必须指定LaunchTemplateId或LaunchTemplateName确定启动模板。

启动模板名称。

使用启动模板创建实例时，您必须指定LaunchTemplateId或LaunchTemplateName确定启动模板。

启动模板版本。如果您指定了LaunchTemplateId或LaunchTemplateName而不指定启动模板版本号，则采用默认版本。

实例所在的企业资源组 ID。

购买资源的时长，单位由PeriodUnit指定。当参数InstanceChargeType取值为PrePaid时才生效且为必选值。一旦指定了DedicatedHostId，则取值范围不能超过专有宿主机的订阅时长。取值范围：

PeriodUnit=Month 时，Period 取值：1、2、3、4、5、6、7、8、9、12、24、36、48、60。

包年包月计费方式的时长单位。取值范围：

Month（默认）。

是否要自动续费。当参数InstanceChargeType取值PrePaid时才生效。取值范围：

• true：自动续费。
• false：不自动续费。

默认值：false。

单次自动续费的续费时长。取值范围：

PeriodUnit=Month 时：1、2、3、6、12、24、36、48、60。

默认值：1。

实例的付费方式。取值范围：

• PrePaid：包年包月。
• PostPaid：按量付费。

默认值：PostPaid。

选择包年包月时，您必须确认自己的账号支持信用支付，否则将返回InvalidPayMethod的错误提示。

部署集 ID。

如果您设置的部署集对应的策略为部署集组高可用策略（AvailabilityGroup），可以通过该参数指定实例在部署集中的分组号。取值范围：1~7。

实例私网 IP 地址。专有网络 VPC 类型 ECS 实例设置私网 IP 地址时，必须从虚拟交换机（VSwitchId）的空闲网段中选择。

您需要注意：

• 设置PrivateIpAddress后：

  • 如果Amount参数取值为 1，则表示为创建的一台 ECS 实例分配私网 IP 地址。
  • 如果Amount参数取值大于 1，则表示在批量创建 ECS 实例时，以指定的私网 IP 地址为起始地址，依次为多台 ECS 实例分配连续的私网 IP 地址，但需要注意，此时不支持再为实例绑定辅助网卡（即不支持再设置NetworkInterface.N.*这类参数）。

• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置PrivateIpAddress，只能设置NetworkInterface.N.PrimaryIpAddress。

设置突发性能实例的运行模式。取值范围：

• Standard：标准模式，实例性能请参见什么是突发性能实例下的性能约束模式章节。
• Unlimited：无性能约束模式，实例性能请参见什么是突发性能实例下的无性能约束模式章节。

为主网卡指定随机生成的 IPv6 地址数量。取值范围：1~10。

您需要注意：

• 您不能同时设置Ipv6Address.N和Ipv6AddressCount。

• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置Ipv6Address.N或Ipv6AddressCount，只能设置NetworkInterface.N.Ipv6Address.N或NetworkInterface.N.Ipv6AddressCount。

主网卡队列数。您需要注意：

• 不能超过实例规格允许的单块网卡最大队列数。

• 实例的所有网卡累加队列数不能超过实例规格允许的队列数总配额。实例规格的单块网卡最大队列数和总配额可以通过 DescribeInstanceTypes 接口查询MaximumQueueNumberPerEni、TotalEniQueueQuantity字段。

• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置NetworkInterfaceQueueNumber，只能设置NetworkInterface.N.QueueNumber。

实例释放保护属性，指定是否支持通过控制台或 API（ DeleteInstance ）释放实例。取值范围：

• true：开启实例释放保护。
• false：关闭实例释放保护。

默认值：false。

专有宿主机实例是否与专有宿主机关联。取值范围：

• default：实例不与专有宿主机关联。已启用节省停机模式的实例，停机后再次启动时，若原专有宿主机可用资源不足，则实例被放置在自动部署资源池的其它专有宿主机上。

• host：实例与专有宿主机关联。已启用节省停机模式的实例，停机后再次启动时，仍放置在原专有宿主机上。若原专有宿主机可用资源不足，则实例重启失败。

默认值：default。

是否在专有宿主机上创建实例。取值范围：

• default：创建非专有宿主机实例。

• host：创建专有宿主机实例。若您不指定DedicatedHostId，则由阿里云自动选择专有宿主机放置实例。

默认值：default。

存储集 ID。

存储集中的最大分区数量。取值范围：大于等于 2。

CPU 核心数。该参数不支持自定义设置，只能采用默认值。

CPU 线程数。ECS 实例的 vCPU 数=CpuOptions.Core取值*CpuOptions.ThreadsPerCore取值。

• CpuOptions.ThreadsPerCore=1表示关闭 CPU 超线程。

• 仅部分实例规格支持设置 CPU 线程数。

该参数已弃用。

实例的 Cpu 拓扑类型。取值范围：

• ContinuousCoreToHTMapping：当选择ContinuousCoreToHTMapping时，实例的 Cpu 拓扑中，实例的同一个 Core 的 HT 是连续的。
• DiscreteCoreToHTMapping：当选择DiscreteCoreToHTMapping时，实例的同一个 Core 的 HT 是离散的。

默认值：无。

可信系统模式。取值：vTPM。

目前，可信系统模式支持的实例规格族：

• g7、c7、r7。
• 安全增强型（g7t、c7t、r7t）。

当您创建以上实例规格族的 ECS 实例时，需要设置该参数。具体说明如下：

• 如果您使用阿里云可信系统，请将该参数值设置为 vTPM，在实例启动时即可通过阿里云可信系统完成可信校验。
• 如果您不使用阿里云可信系统，可以不设置该参数值，但您需要注意，如果您所创建的 ECS 实例使用了 Enclave 机密计算模式（SecurityOptions.ConfidentialComputingMode=Enclave），则该 ECS 实例也会启用可信系统。
• 通过 OpenAPI 创建可信系统的 ECS 实例时，只能调用RunInstances实现，CreateInstance目前不支持设置SecurityOptions.TrustedSystemMode参数。

关于可信系统的更多信息，请参见安全增强型实例可信功能概述。

机密计算模式。取值：Enclave。

该参数取值为 Enclave 时，表示 ECS 实例使用 Enclave 构建机密计算环境。目前仅实例规格族 c7、g7、r7，支持调用RunInstances时指定该参数使用 Enclave 机密计算。您需要注意：

• 机密计算功能正在邀测中。

• 通过 OpenAPI 创建 Enclave 机密计算的 ECS 实例时，只能调用RunInstances实现，CreateInstance目前不支持设置SecurityOptions.ConfidentialComputingMode参数。

• Enclave 机密计算依托可信系统（vTPM）实现，当您指定 ECS 实例使用 Enclave 构建机密计算环境时，该实例同时也会启用可信系统。因此，调用该接口时，如果设置了SecurityOptions.ConfidentialComputingMode=Enclave，则无论您是否设置了SecurityOptions.TrustedSystemMode=vTPM，最终创建的 ECS 实例均会启用 Enclave 机密计算模式以及可信系统。

关于机密计算的更多信息，请参见使用 Enclave 构建机密计算环境。

是否启用实例元数据的访问通道。取值范围：

• enabled：启用。
• disabled：禁用。

默认值：enabled。

访问实例元数据时是否强制使用加固模式（IMDSv2）。取值范围：

• optional：不强制使用。
• required：强制使用。设置该取值后，普通模式无法访问实例元数据。

默认值：optional。

实例启动的私有池容量选项。弹性保障服务或容量预定服务在生效后会生成私有池容量，供实例启动时选择。取值范围：

• Open：开放模式。将自动匹配开放类型的私有池容量。如果没有符合条件的私有池容量，则使用公共池资源启动。该模式下无需设置PrivatePoolOptions.Id参数。
• Target：指定模式。使用指定的私有池容量启动实例，如果该私有池容量不可用，则实例会启动失败。该模式下必须指定私有池 ID，即PrivatePoolOptions.Id参数为必填项。
• None：不使用模式。实例启动将不使用私有池容量。

默认值：None。

以下任一场景，实例启动的私有池容量选项只能取值None或不传值。

• 创建抢占式实例。
• 创建经典网络类型的 ECS 实例。
• 在专有宿主机 DDH 上创建 ECS 实例。

私有池 ID。即弹性保障服务 ID 或容量预定服务 ID。

指定 ECS 实例所属的专有宿主机集群，系统会自动选择该专有宿主机集群中的一台专有宿主机部署 ECS 实例。

在您同时指定了专有宿主机（DedicatedHostId）和专有宿主机集群（SchedulerOptions.DedicatedHostClusterId）时：

• 如果专有宿主机属于专有宿主机集群，则优先将 ECS 实例部署在指定的专有宿主机上。
• 如果专有宿主机不属于专有宿主机集群，则 ECS 实例创建失败。

您可以通过 DescribeDedicatedHostClusters 查询专有宿主机集群 ID 列表。

将实例同时加入多个安全组。N 的取值范围与实例能够加入安全组配额有关。更多信息，请参见安全组限制。

您需要注意：

• 不支持同时设置SecurityGroupId和SecurityGroupIds.N。
• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置SecurityGroupId或SecurityGroupIds.N，只能设置NetworkInterface.N.SecurityGroupId或NetworkInterface.N.SecurityGroupIds.N。

创建多台实例时，为每台实例指定不同的主机名。

数据盘信息集合列表。

弹性网卡信息。

实例、云盘和主网卡的标签信息。

为主网卡指定一个或多个 IPv6 地址。支持设置最多 10 个 IPv6 地址，即 N 的取值范围：1~10。

取值示例：Ipv6Address.1=2001:db8:1234:1a00::***。

您需要注意：

• 设置了Ipv6Address.N时，Amount参数取值只能为 1，且不能同时设置Ipv6AddressCount。

• 如果NetworkInterface.N.InstanceType取值为Primary，则不能设置Ipv6Addresses.N或Ipv6AddressCount，而是需要设置NetworkInterface.N.Ipv6Addresses.N或NetworkInterface.N.Ipv6AddressCount。

系统盘相关参数，目前专属块存储集群 ID（StorageClusterId）需要通过该参数设置参数值。

镜像相关属性信息。

网络相关属性参数。

创建实例时，是否自动支付。取值范围：

• true：自动支付。

  说明 自动支付时，请确保支付方式余额充足，否则会生成异常订单，只能作废订单。如果您的支付方式余额不足，可以将参数AutoPay置为false，此时会生成未支付订单，您可以登录 ECS 管理控制台自行支付。

• false：只生成订单不扣费。

  说明 当InstanceChargeType 取值为PostPaid时，AutoPay不能设置为false。

默认值：true。