文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>云服务器>API 文档>云服务器 API 2017>实例相关接口>查看实例列表

查看实例列表

最近更新时间：2019-10-12 16:25:36

我的收藏

本页目录：

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

1. 接口描述

本接口 (DescribeInstances) 用于查询一个或多个实例的详细信息。 接口请求域名：cvm.api.qcloud.com
可以根据实例 ID、实例名称或者实例计费模式等信息来查询实例的详细信息。过滤信息详细请参见 过滤器 Filter。
如果参数为空，返回当前用户一定数量（Limit 所指定的数量，默认为20）的实例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数，其它参数见 公共请求参数 页面。
参数名称
类型
是否必选
描述
Version
String
是
表示 API 版本号，主要用于标识请求的不同 API 版本。 本接口第一版本可传：2017-03-12。
InstanceIds.N
array of Strings
否
按照一个或者多个实例 ID 查询。实例 ID 形如：ins-11112222。此参数的具体格式可参见 API 简介 的 id.N 一节。每次请求的实例的上限为100。参数不支持同时指定 InstanceIds 和 Filters。
Filters.N
array of Filter objects
否
过滤条件，详见下表：实例过滤条件表。每次请求的 Filters 的上限为10，Filter.Values 的上限为5。参数不支持同时指定 InstanceIds 和Filters。
Offset
Integer
否
偏移量，默认为0。
Limit
Integer
否
返回数量，默认为20，最大值为100。
实例过滤条件表
参数名称
类型
是否必选
描述
zone
String
否
（过滤条件）按照可用区过滤。
project-id
Integer
否
（过滤条件）按照项目 ID 过滤。可通过调用 DescribeProject 查询已创建的项目列表或登录 控制台 进行查看；也可以调用 AddProject 创建新的项目。
host-id
String
否
（过滤条件）按照 CDH ID 过滤。CDH ID 形如：host-11112222。
instance-id
String
否
（过滤条件）按照实例 ID 过滤。实例 ID 形如：ins-11112222。
instance-name
String
否
（过滤条件）按照实例名称过滤。
instance-charge-type
String
否
（过滤条件）按照实例计费模式过滤。取值范围：
PREPAID：表示预付费，即包年包月。
POSTPAID_BY_HOUR：表示后付费，即按量计费。
CDHPAID：表示 CDH 付费，即只对 CDH 计费，不对 CDH 上的实例计费。
private-ip-address
String
否
（过滤条件）按照实例主网卡的内网 IP 过滤。
public-ip-address
String
否
（过滤条件）按照实例主网卡的公网 IP 过滤，包含实例创建时自动分配的 IP 和实例创建后手动绑定的弹性 IP。

3. 输出参数

参数名称
类型
描述
RequestId
String
唯一请求 ID。每次请求都会返回 RequestId。当用户调用接口失败需找后台研发人员处理时需提供该 RequestId。
TotalCount
Integer
符合条件的实例数量。
InstanceSet
array of Instance objects
实例详细信息列表。

4. 错误码

以下错误码表仅列出了该接口的业务逻辑错误码，更多错误码详见 公共错误码。
错误码
描述
InvalidParameter
无效参数。参数不合要求或者参数不被支持等。
InvalidParameterValue
无效参数值。参数值格式错误或者参数值不被支持等。
InvalidInstanceId.Malformed
无效实例 ID。指定的实例 ID 格式错误。例如 ID 长度错误 ins-1122。
InvalidHostId.Malformed
无效 CDH ID。指定的 CDH ID 格式错误。例如 ID 长度错误 host-1122。
InvalidParameterValue.LimitExceeded
参数值数量超过限制。
InvalidFilterValue.LimitExceeded
Filter 参数值数量超过限制。
InvalidFilter
指定的 Filter 不被支持。
InvalidZone.MismatchRegion
指定的 zone 不存在。
InternalServerError
内部服务错误。

5. 示例

输入
https://cvm.api.qcloud.com/v2/index.php?Action=DescribeInstances
&Version=2017-03-12
&Filters.1.Name=zone
&Filters.1.Values.1=ap-guangzhou-1
&Filters.1.Values.2=ap-guangzhou-2
&Offset=0&Limit=1
输出
{
    "Response": {
        "TotalCount": 2,
        "InstanceSet": [
            {
                "Placement": {
                    "Zone": "ap-guangzhou-1",
                    "HostId": "",
                    "ProjectId": 0
                },
                "InstanceId": "ins-r8hr2upy",
                "InstanceType": "S1.SMALL2",
                "CPU": 1,
                "Memory": 2,
                "InstanceName": "\u6d4b\u8bd5\u5b9e\u4f8b",
                "InstanceChargeType": "PREPAID",
                "SystemDisk": {
                    "DiskType": "CLOUD_BASIC",
                    "DiskId": "disk-4rnslbwq",
                    "DiskSize": 20
                },
                "DataDisks": [
                    {
                        "DiskType": "CLOUD_BASIC",
                        "DiskId": "disk-4rnslb35",
                        "DiskSize": 50
                    }
                ],
                "PrivateIpAddresses": [
                    "10.104.37.58"
                ],
                "PublicIpAddresses": [
                    "123.207.32.83"
                ],
                "InternetAccessible": {
                    "InternetMaxBandwidthOut": 2,
                    "InternetChargeType": "BANDWIDTH_PREPAID",
                    "PublicIpAssigned": "TRUE"
                },
                "VirtualPrivateCloud": {
                    "VpcId": "vpc-4e78ea76",
                    "SubnetId": "subnet-6d7kj98i",
                    "AsVpcGateway": "TRUE"
                },
                "ImageId": "img-0vbqvzfn",
                "RenewFlag": "NOTIFY_AND_AUTO_RENEW",
                "CreatedTime": "2016-12-02T00:22:40Z",
                "ExpiredTime": "2017-01-02T00:22:48Z"
            }
        ],
        "RequestId": "6EF60BEC-0242-43AF-BB20-270359FB54A7"
    }
}
中国站