说明：当前页面接口为旧版 API，未来可能停止维护，目前不展示在左侧导航。云服务器 API 3.0 版本接口定义更加规范，访问时延下降显著，建议使用 云服务器 API 3.0。
1. 接口描述
本接口 (RunInstances) 用于创建一个或多个指定配置的实例。
接口请求域名：cvm.api.qcloud.com
- 实例创建成功后将自动开机启动，实例状态变为“运行中”。
- 预付费实例的购买会预先扣除本次实例购买所需金额，按小时后付费实例购买会预先冻结本次实例购买一小时内所需金额，在调用本接口前请确保账户余额充足。
- 本接口允许购买的实例数量遵循 CVM 实例购买限制，所创建的实例和官网入口创建的实例共用配额。
- 本接口为异步接口，当创建请求下发成功后会返回一个实例
ID列表，此时实例的创建并立即未完成。在此期间实例的状态将会处于“准备中”，可以通过调用 DescribeInstancesStatus 接口查询对应实例的状态，来判断生产有没有最终成功。如果实例的状态由“准备中”变为“运行中”，则为创建成功。
2. 输入参数
以下请求参数列表仅列出了接口请求参数，其它参数见 公共请求参数 页面。
| 名称 | 类型 | 是否必选 | 描述 |
|---|---|---|---|
| Version | String | 是 | 表示API版本号，主要用于标识请求的不同API版本。 本接口第一版本可传：2017-03-12。 |
| InstanceChargeType | String | 否 | 实例 计费类型。 默认值：POSTPAID_BY_HOUR。 |
| InstanceChargePrepaid | InstanceChargePrepaid object | 否 | 预付费模式，即包年包月相关参数设置。通过该参数可以指定包年包月实例的购买时长、是否设置自动续费等属性。若指定实例的付费模式为预付费则该参数必传。 |
| Placement | Placement object | 是 | 实例所在的位置。通过该参数可以指定实例所属可用区，所属项目等属性。 |
| InstanceType | String | 否 | 实例机型。不同实例机型指定了不同的资源规格，具体取值可通过调用接口 DescribeInstanceTypeConfigs 来获得最新的规格表或参见 实例类型 描述。若不指定该参数，则默认机型为 S1.SMALL1。 |
| ImageId | String | 是 | 指定有效的镜像 ID，格式形如img-xxx。镜像类型分为四种：可通过以下方式获取可用的镜像 ID： 公共镜像、自定义镜像、共享镜像的镜像ID可通过登录 控制台 查询；服务镜像市场的镜像 ID可通过 云市场 查询。ImageId字段。 |
| SystemDisk | SystemDisk object | 否 | 实例系统盘配置信息。若不指定该参数，则按照系统默认值进行分配。 |
| DataDisks.N | array of DataDisk objects | 否 | 实例数据盘配置信息。若不指定该参数，则默认不购买数据盘，当前仅支持购买的时候指定一个数据盘。 |
| VirtualPrivateCloud | VirtualPrivateCloud object | 否 | 私有网络相关信息配置。通过该参数可以指定私有网络的 ID，子网 ID 等信息。若不指定该参数，则默认使用基础网络。若在此参数中指定了私有网络 IP，那么InstanceCount参数只能为1。 |
| InternetAccessible | InternetAccessible object | 否 | 公网带宽相关信息设置。若不指定该参数，则默认公网带宽为0Mbps。 |
| InstanceCount | Integer | 否 | 购买实例数量。取值范围：[1，100]。默认取值：1。指定购买实例的数量不能超过用户所能购买的剩余配额数量，具体配额相关限制详见 CVM 实例购买限制。 |
| InstanceName | String | 否 | 实例显示名称。如果不指定则默认显示"未命名"。最大长度不能超60个字节。 |
| LoginSettings | LoginSettings object | 否 | 实例登录设置。通过该参数可以设置实例的登录方式密码、密钥或保持镜像的原始登录设置。默认情况下会随机生成密码，并以站内信方式知会到用户。 |
| SecurityGroupIds.N | array of Strings | 否 | 实例所属安全组。该参数可以通过调用 DescribeSecurityGroups 的返回值中的 sgId 字段来获取。若不指定该参数，则默认不绑定安全组。不绑定安全组将暴露所有端口到公网和内网，实例的所有业务（如80、443等端口）将均可被访问，但会有一定的安全风险，建议选择按需新建的安全组。当前仅支持购买的时候指定一个安全组。 |
| EnhancedService | EnhancedService object | 否 | 增强服务。通过该参数可以指定是否开启云安全、腾讯云可观测平台等服务。若不指定该参数，则默认开启腾讯云可观测平台、云安全服务。 |
| ClientToken | String | 否 | 用于保证请求幂等性的字符串。该字符串由客户生成，需保证不同请求之间唯一，最大值不超过64个ASCII字符。若不指定该参数，则无法保证请求的幂等性。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| InstanceIdSet | array of Strings | 当通过本接口来创建实例时会返回该参数，表示一个或多个实例ID。返回实例ID列表并不代表实例创建成功，可根据 DescribeInstancesStatus 接口查询返回的 InstancesSet 中对应实例的ID的状态来判断创建是否完成；如果实例状态由“准备中”变为“正在运行”，则为创建成功。 |
| RequestId | String | 唯一请求ID。每次请求都会返回一个唯一的RequestId，当客户调用接口失败找后台研发人员处理时需提供该RequestId具体值。 |
接口执行正常返回参数示例
{
"Response": {
"InstanceIdSet": [
"xxx1",
"xxx2"
],
"RequestId": "eac6b301-a322-493a-8e36-83b295459397"
}
}
接口执行异常返回参数示例
{
"Response": {
"Error": {
"Code": "AuthFailure",
"Message": "qcloud was not able to validate the provided access credentials"
},
"RequestId": "eac6b301-a322-493a-8e36-83b295459397"
}
}
4. 错误码
以下错误码表仅列出了该接口的业务逻辑错误码，更多错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| InvalidParameterValue | 无效参数值。参数值格式错误或者参数值不被支持等。 |
| InvalidParameterValue.Range | 表示参数取值范围不合法。 |
| InvalidParameterCombination | 表示参数组合不正确。 |
| MissingParameter | 参数缺失。该请求涉及的必选参数缺失。 |
| InvalidPermission | 账户权限限制，无法进行该操作。 |
| AccountQualificationRestrictions | 该请求账户未通过资格审计。 |
| InvalidZone.MismatchRegion | 指定的可用区ID不合法或不属于指定 Region 底下的可用区。 |
| InvalidHostId.NotFound | 指定的 HostId 不存在，或不属于该请求账号所有。 |
| InvalidPeriod | 指定的购买时长不在合理取值范围内。 |
| InvalidInstanceType.Malformed | 指定 InstanceType 参数格式不合法。 |
| InstancesQuotaLimitExceeded | 表示当前创建的实例个数超过了该账户允许购买的剩余配额数。 |
| InvalidInstanceName.TooLong | 指定的 InstanceName 字符串长度超出限制，必须小于等于60字节。 |
| InvalidPassword | 表示指定的密码复杂度符合限制要求。 |
| InvalidClientToken.TooLong | 指定的 ClientToken 字符串长度超出限制，必须小于等于64字节。 |
| VpcAddrNotInSubNet | 私有网络 IP 不在子网内 |
| VpcIpIsUsed | 私有网络 IP 已经被使用 |
5. 示例
示例1
说明：最简单参数的购买：
只传必传的 Zone 和镜像 ID，其他均采用系统默认值，具体配置如下：实例所在位置为广州二区，镜像 ID 为：img-pmqg1cw7。
请求参数
https://cvm.api.qcloud.com/v2/index.php?Action=RunInstances &Version=2017-03-12 &Placement.Zone=ap-guangzhou-2 &ImageId=img-pmqg1cw7 &<公共请求参数>
返回参数
{
"Response": {
"InstanceIdSet": [
"ins-1vogaxgk"
],
"RequestID": "3c140219-cfe9-470e-b241-907877d6fb03"
}
}
示例2
说明：包年包月实例购买：
实例所在位置为广州二区，付费模式为包年包月，购买一个月，到期自动续费，镜像 ID 为：img-pmqg1cw7，选择机型为：1C1G 标准型(S1.SMALL1)，50G大小本地普通系统盘，带100G大小本地普通数据盘，基础网络，公网付费模式为流量按小时后付费，外网带宽上限10Mbps，分配公网 IP，实例命名为QCLOUD-TEST，设置登录密码为Qcloud@TestApi123++，安装腾讯云可观测平台云安全，购买数量为1台。
请求参数
https://cvm.api.qcloud.com/v2/index.php?Action=RunInstances &Version=2017-03-12 &Placement.Zone=ap-guangzhou-2 &InstanceChargeType=PREPAID &InstanceChargePrepaid.Period=1 &InstanceChargePrepaid.RenewFlag=NOTIFY_AND_AUTO_RENEW &ImageId=img-pmqg1cw7 &InstanceType=S1.SMALL1 &SystemDisk.DiskType=LOCAL_BASIC &SystemDisk.DiskSize=50 &DataDisks.0.DiskType=LOCAL_BASIC &DataDisks.0.DiskSize=100 &InternetAccessible.InternetChargeType=TRAFFIC_POSTPAID_BY_HOUR &InternetAccessible.InternetMaxBandwidthOut=10 &InternetAccessible.PublicIpAssigned=TRUE &InstanceName=QCLOUD-TEST &LoginSettings.Password=Qcloud@TestApi123++ &EnhancedService.SecurityService.Enabled=TRUE &EnhancedService.MonitorService.Enabled=TRUE &InstanceCount=1 &<公共请求参数>
返回参数
{
"Response": {
"InstanceIdSet": [
"ins-bfw5zq3y"
],
"RequestID": "3c140219-cfe9-470e-b241-907877d6fb03"
}
}
示例3
说明：按小时后付费实例购买：
实例所在位置为广州二区，付费模式为按小时后付费，镜像ID为：img-pmqg1cw7，选择机型为：1C1G 标准型(S1.SMALL1)，50G大小本地普通系统盘，带100G大小本地普通数据盘，基础网络，公网付费模式为流量按小时后付费，外网带宽上限10Mbps，分配公网 IP，实例命名为 QCLOUD-TEST，设置登录密码为Qcloud@TestApi123++，安装腾讯云可观测平台云安全，购买数量为1台。
请求参数
https://cvm.api.qcloud.com/v2/index.php?Action=RunInstances &Version=2017-03-12 &Placement.Zone=ap-guangzhou-2 &InstanceChargeType=POSTPAID_BY_HOUR &ImageId=img-pmqg1cw7 &InstanceType=S1.SMALL1 &SystemDisk.DiskType=LOCAL_BASIC &SystemDisk.DiskSize=50 &DataDisks.0.DiskType=LOCAL_BASIC &DataDisks.0.DiskSize=100 &InternetAccessible.InternetChargeType=TRAFFIC_POSTPAID_BY_HOUR &InternetAccessible.InternetMaxBandwidthOut=10 &InternetAccessible.PublicIpAssigned=TRUE &InstanceName=QCLOUD-TEST &LoginSettings.Password=Qcloud@TestApi123++ &EnhancedService.SecurityService.Enabled=TRUE &EnhancedService.MonitorService.Enabled=TRUE &InstanceCount=1 &<公共请求参数>
返回参数
{
"Response": {
"InstanceIdSet": [
"ins-32kcaqoa"
],
"RequestID": "3c140219-cfe9-470e-b241-907877d6fb03"
}
}
