九游平台/ 弹性云服务器 ecs/ api参考/ api/ 生命周期管理/ 查询云服务器列表
更新时间：2025-03-07 gmt 08:00
查看pdf

查询云服务器列表-九游平台

功能介绍

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

调试

您可以在中调试该接口。

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

否

map

弹性云服务器元数据。详情请参见表5。

说明：

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

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

云服务器元数据。

详情请参见表5。

tags

array of strings

云服务器标签列表。

addresses

object

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

属性为map结构。

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

security_groups

array of objects

云服务器的安全组信息。

详情请参见表3。

volumes_attached

array of objects

云服务器挂载磁盘信息。

详情请参见表9。

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

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

  • true：是
  • false：否

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

bootindex

string

云硬盘启动顺序。

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

device

string

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

size

integer

云盘大小，单位为gib。
表11 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"
}

返回值

请参考通用请求返回值。

错误码

请参考错误码。

父主题： 生命周期管理

相关文档

网站地图