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

当前页面接口为旧版 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。参数不支持同时指定InstanceIdsFilters
Filters.N array of Filter objects 过滤条件,详见下表:实例过滤条件表。每次请求的Filters的上限为10,Filter.Values的上限为5。参数不支持同时指定InstanceIdsFilters
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"
        }
    }