# 查询云服务器列表 - ListCloudServers #### 功能介绍 根据用户请求条件筛选、查询所有的弹性云服务器，并关联获取弹性云服务器的详细信息。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/ECS/doc?api=ListCloudServers)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-ecs/ecs_06_0000.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | ecs:cloudServers:listServersDetails | list | - | g:EnterpriseProjectId | ecs:cloudServers:list | - | #### URI GET /v1.1/{project_id}/cloudservers/detail 参数说明请参见[表1]。 表1路径参数 | 参数 | 是否必选 | 描述 | |:---|:---|:---| | project_id | 是 | **参数解释：** 项目ID。 获取方法请参见[获取项目ID](https://support.huaweicloud.com/api-ecs/ecs_01_0016.html)。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | 表2查询参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | marker | 否 | String | **参数解释：** 以单页最后一条server的ID作为分页标记。 **约束限制：** marker需要和limit配合使用，不能独立使用。 当最后一页返回数量小于limit时，表示查询结束。 **取值范围：** 不涉及 **默认取值：** 不涉及 | | image_id | 否 | String | **参数解释：** 镜像ID。 **约束限制：** 在使用image_id作为条件过滤时，不能同时支持其他过滤条件和分页条件。 如果同时指定image_id及其他条件，则以image_id条件为准；当条件不含image_id时，接口功能不受限制。 **取值范围：** 不涉及 **默认取值：** 不涉及 | | flavor_name | 否 | String | **参数解释：** 云服务器规格名称。 已上线的规格，请参见[规格清单](https://support.huaweicloud.com/productdesc-ecs/zh-cn_topic_0159822360.html)。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | name | 否 | String | **参数解释：** 云服务器名称，支持模糊匹配。 **约束限制：** 支持特殊字符，例如，"."匹配除换行符（\\n、\\r）之外的任何单个字符，相等于 \[\^\\n\\r\]。 **取值范围：** 不涉及 **默认取值：** 不涉及 | | status | 否 | String | **参数解释：** 云服务器状态。 **约束限制：** 不涉及 **取值范围：** ACTIVE、BUILD、ERROR、HARD_REBOOT、MIGRATING、REBOOT、REBUILD、RESIZE、REVERT_RESIZE、SHUTOFF、VERIFY_RESIZE、DELETED、SHELVED、SHELVED_OFFLOADED 、UNKNOWN 云服务器状态说明请参考[云服务器状态](https://support.huaweicloud.com/api-ecs/ecs_08_0002.html)。 **默认取值：** 不涉及 | | 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 | 否 | String | **参数解释：** 云服务器所在的AZ，匹配规则为模糊匹配。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | availability_zone_eq | 否 | Array of Strings | **参数解释：** 云服务器所在的AZ，匹配规则为精确匹配。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | id | 否 | String | **参数解释：** 云服务器ID，格式为UUID，匹配规则为精确匹配。 示例：id={id1}\&id={id2}。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | in_recycle_bin | 否 | Boolean | **参数解释：** 云服务器是否处于回收站中。 **约束限制：** 不涉及 **取值范围：** - true：云服务器处于回收站中。 - false：云服务器未处于回收站中。 **默认取值：** 不涉及 | | spod_id | 否 | String | **参数解释：** 共池裸机按整机柜发放的同一批次的批创ID。 指定按整机柜发放方式创建的实例详情中携带spod_id。详见[创建云服务器 - CreateServers](https://support.huaweicloud.com/api-ecs/ecs_02_0101.html)或[创建云服务器（按需） - CreatePostPaidServers](https://support.huaweicloud.com/api-ecs/zh-cn_topic_0020212668.html)中的spod_enable字段。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | metadata | 否 | Object | **参数解释：** 弹性云服务器元数据。详情请参见[表5](https://support.huaweicloud.com/api-ecs/ecs_05_0002.html#ecs_05_0002__table537485761711)。 说明： 元数据包含系统默认添加字段和用户设置的字段。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | metadata-key | 否 | String | **参数解释：** 过滤metadata字段的key中包含该值的云服务器。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | charging_mode | 否 | String | **参数解释：** 云服务器的计费类型。 **约束限制：** 不涉及 **取值范围：** - "0"：按需计费（即postPaid-后付费方式）。 - "1"：按包年包月计费（即prePaid-预付费方式）。 - "2"：竞价实例计费 **默认取值：** 不涉及 | | 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。 **取值范围：** 不涉及 | 表4servers_links字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | href | String | **参数解释：** 对应资源链接。 **取值范围：** 不涉及 | | rel | String | **参数解释：** 对应快捷链接。 **取值范围：** 不涉及 | 表5servers字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | tenant_id | String | **参数解释：** 云服务器所属租户ID，即项目id，和project_id表示相同的概念。 **取值范围：** 不涉及 | | vm_state | String | **参数解释：** 云服务器实例当前处于完成某个操作的稳定状态。 **取值范围：** - building：创建实例后，在实例状态进入运行中之前的状态。 - active：实例正常运行状态。 - stopped：实例被正常停止。 - resized：实例完成变更规格的配置。 - error：实例处于异常状态。 - deleted：实例已被正常删除。 - shelved：镜像启动的实例处于搁置状态。 - shelved_offloaded：卷启动的实例处于搁置状态。 | | flavor | Object | **参数解释：** 云服务器规格信息。 详情请参见[表2](https://support.huaweicloud.com/api-ecs/ecs_05_0002.html#ecs_05_0002__table16598374281)。 **取值范围：** 不涉及 | | availability_zone | String | **参数解释：** 云服务器所在可用区名称。 **取值范围：** 不涉及 | | user_id | String | **参数解释：** 创建云服务器的用户ID。 **取值范围：** 不涉及 | | created | String | **参数解释：** 云服务器创建时间。 时间格式例如：2019-05-22T03:19:19Z **取值范围：** 不涉及 | | name | String | **参数解释：** 云服务器名称。 **取值范围：** 不涉及 | | task_state | String | **参数解释：** 云服务器的任务状态。 **取值范围：** - scheduling：实例处于创建中，正在进行调度。 - block_device_mapping：实例处于创建中，正在准备磁盘。 - networking：实例处于创建中，正在准备网络。 - spawning：实例处于创建中，正在内部创建。 - rebooting：实例处于重启中。 - reboot_pending：实例处于重启中，正在下发重启。 - reboot_started：实例处于重启中，开始内部重启。 - rebooting_hard：实例处于强制重启中。 - reboot_pending_hard：实例处于强制重启中，正在下发重启。 - reboot_started_hard：实例处于强制重启中，开始内部重启。 - rebuilding：实例处于重建中。 - rebuild_block_device_mapping：实例处于重建中，正在准备磁盘。 - rebuild_spawning：实例处于重建中，正在内部重建。 - migrating：实例处于热迁移中。 - resize_prep：实例处于调整规格中，正在准备阶段。 - resize_migrating：实例处于调整规格中，正在迁移阶段。 - resize_migrated：实例处于调整规格中，已经完成迁移。 - resize_finish：实例处于调整规格中，正在完成调整。 - resize_reverting：实例处于调整规格中，正在回退调整。 - powering-off：实例处于停止中。 - powering-on：实例处于启动中。 - deleting：实例处于删除中。 - shelving：镜像启动的实例处于搁置中。 - shelving_offloading：卷启动的实例处于搁置中。 - shelving_image_pending_upload：实例处于搁置中，正在下发上传镜像。 - shelving_image_uploading：实例处于搁置中，上传镜像中。 - unshelving：实例处于解除搁置中。 | | id | String | **参数解释：** 云服务器ID，格式为UUID。 **取值范围：** 不涉及 | | status | String | **参数解释：** 云服务器状态。 **取值范围：** ACTIVE、BUILD、ERROR、HARD_REBOOT、MIGRATING、REBOOT、REBUILD、RESIZE、REVERT_RESIZE、SHUTOFF、VERIFY_RESIZE 云服务器状态说明请参考[云服务器状态](https://support.huaweicloud.com/api-ecs/ecs_08_0002.html)。 | | market_info | Object | **参数解释：** 云服务器计费信息。 请参见[表6]。 **取值范围：** 不涉及 | | availability_zone | String | **参数解释：** 云服务器所在的AZ。 **取值范围：** 不涉及 | | power_state | Integer | **参数解释：** 云服务器的电源状态。 **取值范围：** - 0：NOSTATE - 1：RUNNING - 4：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\结构。 **取值范围：** - key为vpc_id。 - value为网络属性，详情请参见[表7]。 | | security_groups | Array of objects | **参数解释：** 云服务器的安全组信息。 详情请参见[表3](https://support.huaweicloud.com/api-ecs/ecs_05_0002.html#ecs_05_0002__zh-cn_topic_0057972887_table38168783)。 **取值范围：** 不涉及 | | volumes_attached | Array of objects | **参数解释：** 云服务器挂载磁盘信息。 详情请参见[表10]。 **取值范围：** 不涉及 | | image | Object | **参数解释：** 云服务器镜像信息。 详情请参见[表11]。 **取值范围：** 不涉及 | | fault | Object | **参数解释：** 云服务器故障原因。 **取值范围：** - 当弹性云服务器状态正常时，返回NULL。 - 当弹性云服务器状态异常时，返回故障描述信息或故障详情请参见[表9]。 | | cpu_options | Object | **参数解释：** 自定义CPU选项。 详情请参见[表12]。 **取值范围：** 不涉及 | 表6market_info字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | charge_mode | String | **参数解释：** 云服务器的计费类型。 **取值范围：** - spot：竞价类型 - prepaid：包年/包月类型 - postpaid：按需类型 | | prepaid_info | Object | **参数解释：** 包年/包月云服务器信息。 详情请参见[表8]。 **取值范围：** 不涉及 | 表7addresses字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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。 **取值范围：** 不涉及 | 表8prepaid_info字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | expired_time | String | **参数解释：** 包年/包月云服务器计费到期时间。 时间格式例如：2020-05-22T07:48:53Z。 **取值范围：** 不涉及 | 表9fault字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释：** 错误码，格式为int32。 **取值范围：** 不涉及 | | created | String | **参数解释：** 异常出现的时间，ISO8601格式。 **取值范围：** 不涉及 | | message | String | **参数解释：** 异常描述信息。 **取值范围：** 不涉及 | | details | String | **参数解释：** 异常详细信息。 **取值范围：** 不涉及 | 表10volumes_attached字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 磁盘ID，格式为UUID。 **取值范围：** 不涉及 | | delete_on_termination | Boolean | **参数解释：** 删除云服务器时是否一并删除该磁盘。 微版本2.3及以上版本支持。 **取值范围：** - true：是 - false：否 | | bootIndex | String | **参数解释：** 云硬盘启动顺序。 **取值范围：** - 0为系统盘。 - 非0为数据盘。 | | device | String | **参数解释：** 云硬盘挂载盘符，即磁盘挂载点。 **取值范围：** 不涉及 | | size | Integer | **参数解释：** 云盘大小，单位为GiB。 **取值范围：** 不涉及 | 表11image参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 镜像ID。 您可以根据镜像ID查询更多镜像信息，详细内容，请参见[查询镜像列表](https://support.huaweicloud.com/api-ims/ims_03_0602.html)。 **取值范围：** 不涉及 | 表12cpu_options数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | hw:cpu_threads | Integer | **参数解释：** 用于控制CPU是否开启超线程。 需要同时满足如下条件，才能设置为"关闭超线程"： - 只能在实例创建或者resize时指定。 - 只有目标flavor的os_extra_specs参数： - 存在"hw:cpu_policy"并取值为"dedicated"。 - 存在"hw:cpu_threads"并取值为"2"。 os_extra_specs参数详情可通过调用[查询规格详情和规格扩展信息列表 - ListFlavors](https://support.huaweicloud.com/api-ecs/zh-cn_topic_0020212656.html)接口进行查询。 **取值范围：** - 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" } ], "request_id": "2da856f5-95e6-437f-9f8b-ae7dc00a9ace" } ``` #### 返回值 请参考[通用请求返回值](https://support.huaweicloud.com/api-ecs/ecs_07_0001.html)。 #### 错误码 请参考[错误码](https://support.huaweicloud.com/api-ecs/ecs_07_0002.html)。