说明：当前页面接口为旧版 API，未来可能停止维护，目前不展示在左侧导航。云服务器 API 3.0 版本接口定义更加规范，访问时延下降显著，建议使用 云服务器 API 3.0。
1. 接口描述
本接口 (DescribeInstances) 用于获取一个或多个实例的详细信息。
接口请求域名：cvm.api.qcloud.com
- 可根据实例ID、实例名称或者实例状态来获取实例列表。
- 如果参数为空，返回当前用户一定数量（limit所指定，默认为20）的实例。
- “实例状态”字段指明了实例当前所属的状态，包含在下列所述情形范围内：
| 状态ID | 状态名 |
|---|---|
| -1 | 创建已失败 |
| 1 | 故障 |
| 2 | 运行中 |
| 3 | 创建中 |
| 4 | 已关机 |
| 5 | 已退还 |
| 6 | 退还中 |
| 7 | 重启中 |
| 8 | 开机中 |
| 9 | 关机中 |
| 10 | 密码重置中 |
| 11 | 格式化中 |
| 12 | 镜像制作中 |
| 13 | 带宽设置中 |
| 14 | 重装系统中 |
| 15 | 域名绑定中 |
| 16 | 域名解绑中 |
| 17 | 负载均衡绑定中 |
| 18 | 负载均衡解绑中 |
| 19 | 升级中 |
| 20 | 密钥下发中 |
| 其它 | 维护中(不能对实例进行操作 但不影响正常运行) |
2. 输入参数
以下请求参数列表仅列出了接口请求参数，其它参数见公共请求参数页面。
| 参数名称 | 是否必选 | 类型 | 描述 |
|---|---|---|---|
| instanceIds.n | 否 | String | （过滤条件）按照一个或者多个实例ID过滤；可通过 DescribeInstances API返回值中的 unInstanceId 获取（此接口支持同时传入多个ID。此参数的具体格式可参考API简介的id.n一节）。 |
| lanIps.n | 否 | String | （过滤条件）按照一个或者多个实例的内网IP或公网IP（包括实例创建时自动分配的IP和弹性IP）过滤（此接口支持同时传入多个IP。此参数的具体格式可参考API简介的id.n一节）。 |
| searchWord | 否 | String | （过滤条件）按照实例名称过滤，支持模糊查询。 |
| status | 否 | Int | （过滤条件）实例的状态，状态的列举见上。 |
| projectId | 否 | Int | （过滤条件）项目ID。 |
| zoneId | 否 | Int | （过滤条件）可用区ID。 |
| offset | 否 | Int | 偏移量，默认为0。关于offset的更进一步介绍参考 API 简介中的相关小节。 |
| limit | 否 | Int | 返回数量，默认 20，最大值 100。关于limit的更进一步介绍参考 API 简介中的相关小节。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| code | Int | 公共错误码。0表示成功，其他值表示失败。 |
| message | String | 模块错误信息描述，与接口相关。 |
| totalCount | Int | 符合条件的实例数量。 |
| instanceSet | Array | 实例信息列表。 |
其中 instanceSet 包含了多个实例信息，每个实例信息的数据结构如下：
| 参数名称 | 类型 | 描述 |
|---|---|---|
| instanceName | String | 实例名称。 |
| unInstanceId | String | 实例ID，命名格式为“ins-xxxxxxxx”。 |
| lanIp | String | 实例主网卡的内网IP。 |
| wanIpSet | Array | 公网IP列表（包括实例创建时自动分配的IP和弹性IP）。 |
| cpu | Int | CPU核数。 |
| mem | Int | 内存大小(GB)。 |
| bandwidth | Int | 带宽大小(Mbps)。 |
| unImgId | String | 镜像ID，命名格式为“img-xxxxxxxx”。 |
| status | Int | 当前状态，具体意义见上文。 |
| Region | String | 所属地域。具体意义可通过 DescribeProductRegionList API查询。 |
| createTime | String | 创建时间。 |
| deadlineTime | String | 到期时间。如果是按量计费实例，则为“0000-00-00 00:00”。 |
| autoRenew | Int | 自动续费标识。 0：不自动续费 1：自动续费 2：不再续费 |
| projectId | Int | 项目ID。 |
| os | String | 操作系统名称。 |
| cvmPayMode | Int | 计费模式。 0：按月结算的后付费 1：包年包月 2：按量计费 |
| networkPayMode | Int | 网络计费模式。 0：按月结算的后付费 1：包年包月 2：按流量 3：按带宽。 关于各个网络计费模式之间的区别可以参考购买网络带宽。 |
| zoneId | Int | 可用区ID。 |
| zoneName | String | 可用区名称。 |
| vpcId | Int | 私有网络ID。 |
| subnetId | Int | 子网ID。 |
| isVpcGateway | Int | 是否是VPC的网关。 0:否 1:是 |
| diskInfo | Array | 包含了硬盘信息的对象。 |
diskInfo 包含了多个硬盘信息，单个硬盘信息的数据结构如下：
| 参数名称 | 类型 | 描述 |
|---|---|---|
| storageId | String | 硬盘ID。 |
| storageType | Int | 硬盘类型。 1.本地硬盘 2.普通云硬盘 3.本地SSD硬盘 4.SSD云硬盘 5.高性能云硬盘 |
| storageSize | Int | 数据盘大小(GB)。 |
| rootId | String | 系统盘ID。 |
| rootSize | Int | 系统盘大小(GB)。 |
| rootType | Int | 系统盘类型。 1.本地硬盘 2.普通云硬盘 3.本地SSD硬盘 4.SSD云硬盘 |
4. 示例
输入：
https://cvm.api.qcloud.com/v2/index.php?Action=DescribeInstances &instanceIds.0=ins-r8hr2upy &instanceIds.1=ins-5d8a23rs &<公共请求参数>
输出：
{
"codeDesc": "Success",
"totalCount": 14,
"message": "",
"code": 0,
"instanceSet": [
{
"lanIp": "10.104.37.58",
"instanceId": "qcvmfd57f3113bc6fd6f0c8ce381f5433539",
"unImgId": "img-0vbqvzfn",
"imageId": 6,
"autoRenew": 0,
"bandwidth": 1,
"vpcId": 0,
"deviceClass": "VSELF",
"diskInfo": {
"rootType": 2,
"rootId": "disk-4rnslbwq",
"rootSize": 50
},
"subnetId": 0,
"isVpcGateway": 0,
"uuid": "9bd7331d-fb7d-4013-bcb1-65a0d4b46873",
"wanIpSet": [
"123.207.32.83"
],
"projectId": 0,
"deadlineTime": "2017-01-02 00:22:48",
"cvmPayMode": 1,
"zoneId": 100002,
"instanceName": "3日测试镜像",
"imageType": "公有镜像",
"status": 4,
"mem": 1,
"Region": "gz",
"networkPayMode": 2,
"unInstanceId": "ins-gsbuwc26",
"createTime": "2016-12-02 00:22:40",
"zoneName": "广州二区",
"statusTime": "2016-12-02 12:28:09",
"os": "Xserver V8.1_64",
"cpu": 1
},
{
"lanIp": "10.104.249.153",
"instanceId": "qcvm0c7dca6b0244fde9b36d7cbc986274a5",
"unImgId": "img-31tjrtph",
"imageId": 53,
"autoRenew": 0,
"bandwidth": 1,
"vpcId": 0,
"deviceClass": "VSELF_2",
"diskInfo": {
"rootId": "disk-hq2agvi8",
"storageSize": 100,
"rootType": 2,
"storageType": 2,
"storageId": "disk-fegdogdg",
"rootSize": 50
},
"subnetId": 0,
"isVpcGateway": 0,
"uuid": "a952c786-a1ee-4d0a-8c45-2640ea70e704",
"wanIpSet": [
"123.207.115.47"
],
"projectId": 0,
"deadlineTime": "2017-01-24 09:22:25",
"cvmPayMode": 1,
"zoneId": 100003,
"instanceName": "jupyter",
"imageType": "公有镜像",
"status": 2,
"mem": 16,
"Region": "gz",
"networkPayMode": 1,
"unInstanceId": "ins-r8hr2upy",
"createTime": "2016-11-24 09:22:18",
"zoneName": "广州三区",
"statusTime": "2016-11-30 10:48:24",
"os": "centos7.2x86_64",
"cpu": 8
}
]
}
