查看实例列表

最近更新时间: 2026-11-07 00:16:28

1. 接口描述

接口请求域名： bms.api3.fincloud.tencent.cn。

本接口 (DescribeInstances) 用于查询一个或多个实例的详细信息。

可以根据实例ID、实例名称或者实例计费模式等信息来查询实例的详细信息。过滤信息详细请见过滤器Filter。
如果参数为空，返回当前用户一定数量（Limit所指定的数量，默认为20）的实例。

默认接口请求频率限制：40次/秒。

接口更新时间：2025-12-30 16:33:10。

接口既验签名又鉴权。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

参数名称	必选	允许NULL	类型	描述
Action	是	否	String	公共参数，本接口取值：DescribeInstances
Version	是	否	String	公共参数，本接口取值：2018-08-13
Region	是	否	String	公共参数，地域信息可通过DescribeRegions接口查看产品支持的地域列表
InstanceIds	否	否	Array of String	按照一个或者多个实例ID查询。实例ID形如：`bms-11112222`。（此参数的具体格式可参考API[简介]的`id.N`一节）。每次请求的实例的上限为100。参数不支持同时指定`InstanceIds`和`Filters`。示例值： bms-asdfghjk
Filters	否	否	Array of Filter	过滤条件。 zone - String - 是否必填：否 -（过滤条件）按照可用区过滤。 instance-id - String - 是否必填：否 - （过滤条件）按照实例ID过滤。实例ID形如：ins-11112222。 instance-name - String - 是否必填：否 - （过滤条件）按照实例名称过滤。 instance-state - String - 是否必填：否 -（过滤条件）按照实例的状态过滤 private-ip-address - String - 是否必填：否 - （过滤条件）按照实例主网卡的内网IP过滤。 vpc-id - String - 是否必填：否 - （过滤条件）按照实例所属的vpcid进行过滤 subnet-id - String - 是否必填：否 - （过滤条件）按照实例所属的子网id进行过滤 -（过滤条件）按照实例所属的groupid进行过滤 groupId - String - 是否必填：否。 cpuArch - String - 是否必填：否 -（过滤条件）按照CPU架构过滤。 operating-system-type - String - 是否必填：否 -（过滤条件）按照操作系统过滤。每次请求的`Filters`的上限为10，`Filter.Values`的上限为5。参数不支持同时指定`InstanceIds`和`Filters`。示例值：查看
Offset	否	否	Int64	偏移量，默认为0。关于`Offset`的更进一步介绍请参考 API [简介]中的相关小节。示例值： 0
Limit	否	否	Int64	返回数量，默认为20，最大值为100。关于`Limit`的更进一步介绍请参考 API [简介]中的相关小节。示例值： 20

3. 输出参数

参数名称	类型	描述
TotalCount	Int64	实例总数量示例值： 100
InstanceSet	Array of Instance	实例的详细信息列表示例值：查看
RequestId	String	唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 错误码

该接口暂无业务逻辑相关的错误码，其他错误码详见公共错误码。

5. 示例

示例1 查看实例列表

输入示例

{"Offset":0,"Limit":100,"Filters":[{"Name":"ExcludeOutband","Values":["1"]},{"Name":"instance-state","Values":["RUNNING"]}],"Version":"2018-08-13","Language":"zh-CN"}

输出示例

{
    "Response": {
        "InstanceSet": [
            {
                "InstanceId": "bms-fe9bb5f4",
                "AppId": "1255000069",
                "Placement": {
                    "Zone": "ap-test-region-jcctest-ops-1"
                },
                "Uuid": "fe9bb5f4-63a1-403d-b181-de52f36ebe8c",
                "InstanceName": "TEST",
                "RaidType": "RAID0",
                "OperatingSystemType": "Linux",
                "OperatingSystem": "centos72",
                "Tag": [
                    {
                        "TagKey": "bmsKey",
                        "TagValue": "bmsValue1"
                    },
                    {
                        "TagKey": "bmsKey2",
                        "TagValue": "bmsValue2.1"
                    }
                ],
                "PrivateIpAddresses": [
                    "10.1.5.9"
                ],
                "PrivateIpv6Addresses": [],
                "Status": "RUNNING",
                "FlavorId": "flavor-94722d72",
                "UserDefined": 1,
                "GroupId": null,
                "HeartbeatId": null,
                "BackupIPs": null,
                "CpuArch": "X86",
                "CreatedTime": "2026-03-16 16:22:04",
                "CreateTimeIso": "2026-03-16T16:22:04+08:00",
                "VirtualPrivateCloud": {
                    "VpcId": "vpc-7z9vr80d",
                    "SubnetId": "subnet-6rr8pck0"
                }
            }
        ],
        "TotalCount": 1,
        "RequestId": "b1cad462-5d05-e466-9f64-22b6c91527e7"
    }
}