更新时间:2025-08-20 GMT+08:00

查询云服务器列表

功能介绍

根据用户请求条件筛选、查询所有的弹性云服务器,并关联获取弹性云服务器的详细信息。

URI

GET /v1.1/{project_id}/cloudservers/detail

参数说明请参见表1
表1 路径参数

参数

是否必选

描述

project_id

项目ID。

获取方法请参见获取项目ID

表2 查询参数

参数

是否必选

参数类型

描述

marker

String

参数解释:

以单页最后一条server的ID作为分页标记。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

flavor_name

String

参数解释:

云服务器规格名称。

已上线的规格,请参见规格清单

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

name

String

参数解释:

云服务器名称,支持模糊匹配。

约束限制:

支持特殊字符,例如,“.”匹配除换行符(\n、\r)之外的任何单个字符,相等于 [^\n\r]。

取值范围:

不涉及

默认取值:

不涉及

status

String

参数解释:

云服务器状态。

约束限制:

不涉及

取值范围:

ACTIVE、BUILD、ERROR、HARD_REBOOT、MIGRATING、REBOOT、REBUILD、RESIZE、REVERT_RESIZE、SHUTOFF、VERIFY_RESIZE

云服务器状态说明请参考云服务器状态

说明:

当云服务器处于中间状态时,查询范围如下:

  • ACTIVE,查询范围:ACTIVE,REBOOT,HARD_REBOOT,REBUILD,MIGRATING
  • SHUTOFF,查询范围:SHUTOFF,RESIZE,REBUILD
  • ERROR,查询范围:ERROR,REBUILD
  • VERIFY_RESIZE,查询范围:VERIFY_RESIZE,REVERT_RESIZE

默认取值:

不涉及

limit

Integer

参数解释:

查询返回云服务器列表当前页面的数量。

约束限制:

每页默认值是10,最多返回100台云服务器的信息。

取值范围:

不涉及

默认取值:

不涉及

tags

String

参数解释:

查询tag字段中包含该值的云服务器。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

not-tags

String

参数解释:

查询tag字段中不包含该值的云服务器。

示例:查询的云服务器列表中不包含裸金属服务器,该字段设置如下:not-tags=__type_baremetal

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

project_id

String

参数解释:

项目id。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

availability_zone_eq

String

参数解释:

云服务器所在的AZ,匹配规则为精确匹配。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

id

String

参数解释:

云服务器ID,格式为UUID,匹配规则为精确匹配。

示例:id={id1}&id={id2}。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

in_recycle_bin

Boolean

参数解释:

云服务器是否处于回收站中。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

spod_id

String

参数解释:

共池裸机按整机柜发放的同一批次的批创ID。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

metadata

Object

参数解释:

弹性云服务器元数据。

说明:

元数据包含系统默认添加字段和用户设置的字段。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

metadata-key

String

参数解释:

过滤metadata字段的key中包含该值的云服务器。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

charging_mode

String

参数解释:

云服务器的计费类型。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

key_name

String

参数解释:

云服务器使用的密钥对名称。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

launched_since

String

参数解释:

过滤在launched_since时间之后启动的云服务器。格式为ISO8601时间格式,例如:2013-06-09T06:42:18Z。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

expect-fields

String

参数解释:

控制查询输出的字段。在默认字段的基础上选择是否查询。

约束限制:

不涉及

取值范围:

  • launched_at:云服务器启动时间。
  • key_name:云服务器使用的密钥对名称。
  • locked:云服务器是否为锁定状态。
  • root_device_name:云服务器系统盘的设备名称。
  • tenancy:在专属主机或共享池中创建云服务器。
  • dedicated_host_id:专属主机ID。
  • enterprise_project_id:查询绑定某个企业项目的云服务器。
  • tags:云服务器的标签列表。
  • metadata:云服务器元数据。
  • addresses:云服务器对应的网络地址信息。
  • security_groups:云服务器的安全组信息。
  • volumes_attached:云服务器挂载磁盘信息。
  • image:云服务器镜像信息。
  • power_state:云服务器电源状态。
  • cpu_options:自定义CPU选项。
  • market_info:云服务器计费信息,包含计费类型、到期时间等字段。

默认取值:

不涉及

请求消息

响应消息

响应参数如表3所示。
表3 响应参数

参数

参数类型

描述

servers

Array of objects

参数解释:

查询云服务器详情列表。

详情请参见表5

取值范围:

不涉及

servers_links

Array of objects

参数解释:

分页查询时,查询下一页数据链接。

详情请参见表4

取值范围:

不涉及

request_id

String

参数解释:

请求ID。

取值范围:

不涉及

表4 servers_links字段数据结构说明

参数

参数类型

描述

href

String

参数解释:

对应资源链接。

取值范围:

不涉及

rel

String

参数解释:

对应快捷链接。

取值范围:

不涉及

表5 servers字段数据结构说明

参数

参数类型

描述

tenant_id

String

参数解释:

云服务器所属租户ID,即项目id,和project_id表示相同的概念,格式为UUID。

取值范围:

不涉及

vm_state

String

参数解释:

云服务器实例当前处于完成某个操作的稳定状态。

取值范围:

不涉及

flavor

Object

参数解释:

云服务器规格信息。

详情请参见表2

取值范围:

不涉及

availability_zone

String

参数解释:

云服务器所在可用区名称。

取值范围:

不涉及

user_id

String

参数解释:

创建云服务器的用户ID,格式为UUID。

取值范围:

不涉及

created

String

参数解释:

云服务器创建时间。

时间格式例如:2019-05-22T03:19:19Z

取值范围:

不涉及

name

String

参数解释:

云服务器名称。

取值范围:

不涉及

task_state

String

参数解释:

云服务器的任务状态。

取值范围:

不涉及

id

String

参数解释:

云服务器ID,格式为UUID。

取值范围:

不涉及

status

String

参数解释:

云服务器状态。

取值范围:

不涉及

market_info

Object

参数解释:

云服务器计费信息。

请参见表6

取值范围:

不涉及

availability_zone

String

参数解释:

云服务器所在的AZ。

取值范围:

不涉及

power_state

Integer

参数解释:

云服务器的电源状态。

取值范围:

  • 0:NOSTATE
  • 1:RUNNING
  • 2:SHUTDOWN

in_recycle_bin

Boolean

参数解释:

云服务器是否处于回收站中。

取值范围:

不涉及

spod_id

String

参数解释:

共池裸机按整机柜发放的同一批次的批创ID。

取值范围:

不涉及

created

String

参数解释:

云服务器创建时间。

时间格式例如:2020-05-22T07:48:53Z。

取值范围:

不涉及

updated

String

参数解释:

云服务器上一次更新时间。

时间格式例如:2020-05-22T07:48:53Z。

取值范围:

不涉及

launched_at

String

参数解释:

云服务器启动时间。

时间格式例如:2020-05-22T07:48:53.000000。

取值范围:

不涉及

description

String

参数解释:

云服务器的描述信息。

取值范围:

不涉及

key_name

String

参数解释:

云服务器使用的密钥对名称。

取值范围:

不涉及

locked

Boolean

参数解释:

云服务器是否为锁定状态。

取值范围:

  • true:锁定
  • false:未锁定

root_device_name

String

参数解释:

云服务器系统盘的设备名称,例如当系统盘的磁盘模式是VBD时,为/dev/vda。

取值范围:

不涉及

tenancy

String

参数解释:

在专属主机或共享池中创建云服务器。默认为在共享池创建。

取值范围:

  • shared:共享池
  • dedicated:专属主机

dedicated_host_id

String

参数解释:

专属主机ID。

此属性仅在tenancy值为dedicated时有效,不指定此属性,系统将自动分配租户可自动放置云服务器的专属主机。

取值范围:

不涉及

enterprise_project_id

String

参数解释:

查询绑定某个企业项目的云服务器。

若需要查询当前用户所有企业项目绑定的云服务器,请传参all_granted_eps。

取值范围:

不涉及

metadata

Object

参数解释:

云服务器元数据。

取值范围:

不涉及

tags

Array of Strings

参数解释:

云服务器标签列表。

取值范围:

不涉及

addresses

Object

参数解释:

云服务器对应的网络地址信息。

属性为Map<String, Object>结构。

取值范围:

  • key为网络名称,如“demo_net”。
  • value为网络属性,详情请参见表7

security_groups

Array of objects

参数解释:

云服务器的安全组信息。

详情请参见表3

取值范围:

不涉及

volumes_attached

Array of objects

参数解释:

云服务器挂载磁盘信息。

详情请参见表10

取值范围:

不涉及

image

Object

参数解释:

云服务器镜像信息。

详情请参见表7

取值范围:

不涉及

fault

Object

参数解释:

云服务器故障原因。

取值范围:

  • 当弹性云服务器状态正常时,返回NULL。
  • 当弹性云服务器状态异常时,返回故障描述信息或故障详情请参见表9

cpu_options

Object

参数解释:

自定义CPU选项。

详情请参见表11

取值范围:

不涉及

表6 market_info字段数据结构说明

参数

参数类型

描述

charge_mode

String

参数解释:

云服务器的计费类型。

取值范围:

  • spot:竞价类型
  • prepaid:包年/包月类型
  • postpaid:按需类型

prepaid_info

Object

参数解释:

包年/包月云服务器信息。

详情请参见表8

取值范围:

不涉及

表7 addresses字段数据结构说明

参数

参数类型

描述

version

Integer

参数解释:

IP地址版本。

取值范围:

  • “4”:代表IPv4。
  • “6”:代表IPv6。

addr

String

参数解释:

IP地址。

取值范围:

不涉及

primary

Boolean

参数解释:

是否是主网卡。

取值范围:

  • true:主网卡。
  • false:辅助网卡。

OS-EXT-IPS:type

String

参数解释:

IP地址类型。

取值范围:

  • fixed:代表私有IP地址。
  • floating:代表浮动IP地址。

OS-EXT-IPS-MAC:mac_addr

String

参数解释:

MAC地址。

取值范围:

不涉及

OS-EXT-IPS:port_id

String

参数解释:

IP地址对应的端口ID。

取值范围:

不涉及

表8 prepaid_info字段数据结构说明

参数

参数类型

描述

expired_time

String

参数解释:

包年/包月云服务器计费到期时间。

时间格式例如:2020-05-22T07:48:53Z。

取值范围:

不涉及

表9 fault字段数据结构说明

参数

参数类型

描述

code

Integer

参数解释:

错误码,格式为int32。

取值范围:

不涉及

created

String

参数解释:

异常出现的时间,ISO8601格式。

取值范围:

不涉及

message

String

参数解释:

异常描述信息。

取值范围:

不涉及

details

String

参数解释:

异常详细信息。

取值范围:

不涉及

表10 volumes_attached字段数据结构说明

参数

参数类型

描述

id

String

参数解释:

磁盘ID,格式为UUID。

取值范围:

不涉及

delete_on_termination

Boolean

参数解释:

删除云服务器时是否一并删除该磁盘。

微版本2.3及以上版本支持。

取值范围:

  • true:是
  • false:否

bootIndex

String

参数解释:

云硬盘启动顺序。

取值范围:

  • 0为系统盘。
  • 非0为数据盘。

device

String

参数解释:

云硬盘挂载盘符,即磁盘挂载点。

取值范围:

不涉及

size

Integer

参数解释:

云盘大小,单位为GiB。

取值范围:

不涉及

表11 cpu_options数据结构说明

参数

参数类型

描述

hw:cpu_threads

Integer

参数解释:

用于控制CPU是否开启超线程。

需要同时满足如下条件,才能设置为“关闭超线程”:

  • 只能在实例创建或者resize时指定。
  • 只有目标flavor的extra_specs参数:
    • 存在“hw:cpu_policy”并取值为“dedicated”。
    • 存在“hw:cpu_threads”并取值为“2”。

取值范围:

  • 1: 关闭超线程。
  • 2: 打开超线程。

请求示例

GET https://{endpoint}/v1.1/{project_id}/cloudservers/detail

响应示例

{
    "servers": [
        {
            "tenant_id": "edcb94a885a84ed3a3fdf8ea4d2741da",
            "vm_state": "active",
            "flavor": {
                "disk": 0,
                "name": "s2.medium.2",
                "id": "s2.medium.2",
                "vcpus": 1,
                "ram": 2048,
                "gpus":[],
                "asic_accelerators":[]
            },
            "availability_zone": "az1-dc1",
            "user_id": "bb7f23e27e7e46f3aaceb5f53a158bdc",
            "created": "2023-03-18T09:02:36Z",
            "name": "ecs-5e70",
            "task_state": null,
            "in_recycle_bin": false,
            "id": "b37fd80e-ac67-4d02-b9f1-9891c9c0fabf",
            "updated": "2023-03-18T09:08:54Z",
            "spod_id": null,
            "status": "ACTIVE"
        },
        {
            "tenant_id": "edcb94a885a84ed3a3fdf8ea4d2741da",
            "vm_state": "active",
            "flavor": {
                "disk": 0,
                "name": "s3.small.1",
                "id": "s3.small.1",
                "vcpus": 1,
                "ram": 1024,
                "gpus":[],
                "asic_accelerators":[]
            },
            "availability_zone": "az1-dc1",
            "user_id": "bb7f23e27e7e46f3aaceb5f53a158bdc",
            "created": "2023-03-18T04:29:44Z",
            "name": "ecs-f680",
            "task_state": null,
            "in_recycle_bin": false,
            "id": "8380dcc9-0eac-4407-9f9e-df8c9eddeacd",
            "updated": "2023-03-18T04:40:25Z",
            "spod_id": null,
            "status": "ACTIVE"
        }
    ],
    "servers_links": [
        {
            "rel": "next",
            "href": ""
        }
    ],
    "request_id": "2da856f5-95e6-437f-9f8b-ae7dc00a9ace"
}

返回值

请参考通用请求返回值

错误码

请参考错误码