创建实例（包年包月）

说明：

当前页面接口为旧版 API，未来可能停止维护，目前不展示在左侧导航。云服务器 API 3.0 版本接口定义更加规范，访问时延下降显著，建议使用 云服务器 API 3.0。

1. 接口描述

本接口 (RunInstances) 用于创建一台或多台指定配置的包年包月实例。

接口请求域名：cvm.api.qcloud.com

• API创建的实例遵循 CVM 实例购买限制 文档所描述的数量限制，和官网所创建的实例共用配额。
• CPU 与内存具体的配比限制参见 CVM 实例配置。
• 实例的创建需要一定时间，本接口不会立刻返回实例结果。而是返回一个 InstanceId，在此期间可以通过 DescribeInstances 接口查询该实例的状态。如果状态由“创建中”变为“正在运行”，则为创建成功。
• 本接口暂时只支持预付费的用户，在调用API前请确认余额充足。
• 实例创建成功后为“正在运行”的状态，无需再次调用 StartInstances 来启动。
• 如需要更改带宽，请在实例创建成功后，使用接口 UpdateInstanceBandwidth 更改，公网带宽不指定默认为0。
• 本接口暂不支持在创建实例的同时绑定安全组，所创建的实例默认所有端口都放通，建议用户在创建实例之后使用ModifySecurityGroupsOfInstance 接口给对应云服务器关联的安全组。
• 支持的实例类型：

  机型	系列1	系列2
  标准型	CVM.S1	CVM.S2
  高IO型	CVM.I1	CVM.I2
  内存型	CVM.M1	CVM.M2
  计算型	－	CVM.C2

2. 输入参数

以下请求参数列表仅列出了接口请求参数，其它参数见 公共请求参数 页面。

参数名称	是否必选	类型	描述
cpu	是	Int	CPU（核数）。
mem	是	Int	内存（GB）。
imageId	是	String	镜像ID。可通过 DescribeImages 接口(链接包含公共镜像名称ID对应表)返回字段中的 unImgId 获取。
period	是	Int	购买时长(月)。至少1个月，最多36个月。
storageSize	是	Int	数据盘大小（GB）。最小调整步长为10G，此参数默认值为0，表示不购买数据盘。其所分配数据盘的类型与 storageType 所指定的一致。关于不同类型数据盘的特性与容量限制请参考硬盘产品简介。
zoneId	否	Int	可用区ID，默认为每个地区的第一个可用区。
instanceType	否	String	实例类型（例如高IO机型等）。默认为CVM.S1。更多实例类型，可在上文查看“实例类型”一节。
imageType	否	Int	镜像类型。1：私有镜像、2：公有镜像、3：镜像市场、4：共享镜像。默认为2。如果您指定非公有镜像的ImageId，则必须指定ImageType，如使用公有镜像，则无需ImageType参数。
bandwidthType	否	String	带宽的类型。PayByTraffic：按流量计费； PayByBandwidth：按带宽计费；默认是按带宽计费。关于各个网络计费模式之间的区别可以参考购买网络带宽。
bandwidth	否	Int	公网带宽(Mbps)，当按流量计费时为公网带宽峰值，默认为0。
wanIp	否	Int	是否开通公网IP。1：开通，0：不开通。bandwidth大于0，可自由选择开通与否，默认为开通；bandwidth为0，则不分配公网IP。
vpcId	否	String	私有网络 ID。私有网络下为必填，不填则为基础网络。
subnetId	否	String	子网 ID，私有网络下为必填（必须保证此subnetId在本可用区内）。
isVpcGateway	否	Int	是否是公网网关。0：非公网网关；1：公网网关；默认为0。公网网关只有在实例拥有公网IP并处于私有网络下时才能正常使用。
storageType	否	Int	硬盘类型。1:本地硬盘、2:普通云硬盘、3:本地 SSD 硬盘；默认为1。关于硬盘类型的选择请参考硬盘产品简介，可选硬盘类型受到实例类型（InstanceType）限制。另外允许购买的最大容量也因硬盘类型的不同而有所差异。
rootSize	否	Int	系统盘大小（GB）。 Linux/BSD 系统调整范围为20~50G，最小调整步长为10G，默认免费分配20G。Windows 不可调整，默认为免费分配50G。系统盘类型须与 storageType 所指定的一致。
password	否	String	实例密码。未设置则为随机产生，并通过站内信下发。Linux 实例密码必须是8至16位，至少包括以下三项中的两项。[a-z，A-Z]、[0-9] 和 [( ) ~ ! @ # $ % ^ & * - + = | { } [ ] : ; ' , . ? / ]中的特殊符号。Windows 实例密码必须是12至16位，至少包括以下四项中的三项。[a-z]，[A-Z]，[0-9] 和 [( ) ~ ! @ # $ % ^ & * - + = { } [ ] : ; ' , . ? /]中的特殊符号。
keyId	否	String	密钥ID。关联密钥后可使用密钥登录实例，keyId 可通过接口DescribeKeyPairs获取，密钥与密码不能同时指定，同时 Windows 操作系统不支持指定密钥。
needSecurityAgent	否	Int	开启 云安全服务。开通：1，不开通：0。默认开通。
needMonitorAgent	否	Int	开启 腾讯云可观测平台服务。开通：1，不开通：0。默认开通。
projectId	否	Int	项目 ID，不填为默认项目。
instanceName	否	String	实例名称，可任意命名，但不得超过60个字符。默认为“未命名”。
goodsNum	否	Int	购买实例的数量。默认为1，最大为100。
clientToken	否	String	保证此API幂等的Token，最多64字符。不同的API请求携带相同的 Token 视为同一请求，可以防止客户端请求API时因为网络异常而重试，导致多次创建实例的情况。
privateIpAddresses.n	否	array of Strings	私有子网ip数组，目前只支持一个ip。在创建实例、修改实例vpc属性操作中可使用此参数。

3. 输出参数

参数名称	类型	描述
code	Int	公共错误码。0表示成功，其他值表示失败。
message	String	模块错误信息描述，与接口相关。
dealIds	Array	生成的订单号，可通过 DescribeDeals API 查询后续执行状况。
unInstanceIds	Array	系统自动生成实例的 ID，命名格式为“ins-xxxxxxxx”，可使用此 ID 通过 DescribeInstances API 查询实例的详细信息。

4. 错误码

以下错误码表仅列出了该接口的业务逻辑错误码，更多公共错误码详见 CVM 错误码 页面。

错误码	描述
InvalidParameter.InvaildZoneId	zoneId不合法
OperationFail.SystemBusy	资源购买繁忙
InvalidParameter.PasswordNotConformSpecs	密码不合规范
InvalidParameter.InvaildZoneId	zoneId不合法
OperationConstraints.AccountBalanceNotEnough	您的余额不足，请先充值
InvalidParameter.InvalidIpFormat	ip格式不正确
InvalidParameter.NotSupportReservedIp	保留ip不可使用
InvalidParameter.IpNotInCidrRange	ip不在子网内
InvalidParameter.IpInUse	ip已经被使用

5. 示例

输入

  https://cvm.api.qcloud.com/v2/index.php?Action=RunInstances
  &imageId=img-lkxqa4kj
  &imageType=2
  &bandwidth=1
  &cpu=1
  &mem=2
  &storageType=1
  &storageSize=50
  &period=12
  &goodsNum=1
  &<公共请求参数>

输出

  {
      "code" : 0,
      "message" : "ok",
      "dealIds":[
          121
      ],
     "unInstanceIds": {
        "121": [
            "ins-npphstest"
        ]
    }
  }