有奖捉虫:云通信与企业服务文档专题,速来> HOT
说明:

当前页面接口为旧版 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
        }
    ]
}