文档首页/ 弹性云服务器 ECS/ API参考/ API/ 生命周期管理/ 查询云服务器列表
更新时间：2024-12-03 GMT+08:00
查看PDF
分享

查询云服务器列表

功能介绍

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

调试

您可以在API Explorer中调试该接口。

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

enterprise_project_id

否

String

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

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

说明：
  • 查询的企业项目需具备ecs:cloudServers:list的权限。

    如果用户只有某个企业项目的权限，则需要传递该参数，查询指定企业项目绑定的弹性云服务器，否则会因权限不足而报错。

  • 当前all_granted_eps支持查询的企业项目个数不超过100。

project_id

否

String

项目id。

availability_zone_eq

否

String

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

id

否

String

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

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

in_recycle_bin

否

Boolean

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

sopt_id

否

String

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

metadata

否

String

过滤metadata字段包含该值的云服务器，支持key=value过滤。

metdata-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。

updated

String

云服务器修改时间。

status

String

云服务器状态。

market_info

Object

云服务器计费信息。

请参见表6。

availability_zone

String

云服务器所在的AZ。

task_state

String

云服务器的任务状态。

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

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

tenancy

String

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

取值范围：

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

dedicated_host_id

String

专属主机ID。

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

enterprise_project_id

String

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

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

metadata

Map<String, String>

云服务器元数据。

详情请参见表5。

tags

Array of Strings

云服务器标签列表。

addresses

Object

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

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

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

security_groups

Array of objects

云服务器的安全组信息。

详情请参见表3。

volumes_attached

Array of objects

云服务器挂载磁盘信息。

详情请参见表8。

image

Object

云服务器镜像信息。

详情请参见表7。

fault

Object

云服务器故障原因。

  • 当弹性云服务器状态正常时，返回NULL。
  • 当弹性云服务器状态异常时，返回故障描述信息或故障详情：
    • message：故障信息
    • code：故障代码
    • details：故障详情
    • created：故障时间，ISO8601格式

cpu_options

Object

自定义CPU选项。

详情请参见表9。
表6 market_info字段数据结构说明

参数

参数类型

描述

charge_mode

String

云服务器的计费类型。

取值范围：

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

prepaid_info

Object

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

详情请参见表7。
表7 prepaid_info字段数据结构说明

参数

参数类型

描述

expired_time

String

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

时间格式例如：2020-05-22T07:48:53Z。
表8 volumes_attached字段数据结构说明

参数

参数类型

描述

id

String

磁盘ID，格式为UUID。

delete_on_termination

Boolean

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

  • true：是
  • false：否

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

bootIndex

String

云硬盘启动顺序。

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

device

String

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

size

Integer

云盘大小，单位为GiB。
表9 cpu_options数据结构说明

参数

参数类型

描述

hw:cpu_threads

Integer

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

取值范围：1，2。

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

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

  • 只能在实例创建或者resize时指定。
  • 只有目标flavor的extra_specs参数：
    • 存在“hw:cpu_policy”并取值为“dedicated”。
    • 存在“hw:cpu_threads”并取值为“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"
}

返回值

请参考通用请求返回值。

错误码

请参考错误码。

父主题： 生命周期管理

相关文档