更新时间:2025-07-25 GMT+08:00
分享

批量查询实例

功能介绍

批量查询实例

调用方法

请参见如何调用API

URI

GET /v1/{project_id}/instances

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释

项目ID

约束限制

不涉及

取值范围

账号的项目ID

默认取值

不涉及

表2 Query参数

参数

是否必选

参数类型

描述

limit

String

参数解释

分页查询时每页行数。

约束限制

不涉及

取值范围

10-1000,当不设置值或设置的值小于 10 时,默认值为 10。当设置的值大于 1000 时,默认值为 1000。

默认取值

1000

marker

String

参数解释

下一页查询地址

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

instance_state

String

参数解释

实例状态

约束限制

不涉及

取值范围

  • pending:实例正在启动(分配资源/启动操作系统)

  • running:实例正常运行(可接受SSH/RDP连接)

  • stopping:实例正在关闭(停止/休眠过渡状态)

  • stopped: 实例已完全关闭(存储卷保留)

  • reinstalling:实例正在重装中

  • shutting-down:实例正在终止(删除流程中)

  • terminated:实例已终止(资源完全删除,不可恢复)

  • failed:实例处于失败状态,对于reinstall操作可重试,其它操作不可重试并清除相关资源

默认取值

不涉及

instance_id

String

参数解释

实例 ID。取值可以由多个实例 ID 组成数组。

约束限制

不涉及

取值范围

最多支持 100 个 ID,ID 之间用半角逗号(,)隔开,示例:uuid1,uuid2,uuid3。

默认取值

不涉及

server_id

String

参数解释

服务器 ID。取值可以由多个服务器 ID 组成数组。

约束限制

与instance_id_set查询条件互斥

取值范围

最多支持 100 个 ID,ID 之间用半角逗号(,)隔开,示例:uuid1,uuid2,uuid3。

默认取值

不涉及

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

参数解释

调用接口的认证方式分为Token,如果您使用的Token方式,此参数为必填,请填写Token的值

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

响应参数

状态码:200

表4 响应Body参数

参数

参数类型

描述

instances

Array of QueryInstanceResponseBody objects

实例列表

page_info

PageInfo object

参数解释

分页信息

约束限制

不涉及

count

Integer

实例总数

表5 QueryInstanceResponseBody

参数

参数类型

描述

id

String

参数解释

实例ID

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

name

String

参数解释

实例名称

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

vpc_id

String

参数解释

创建网卡所属的 VPC ID,可通过 VPC API 查询:https://support.huaweicloud.com/api-vpc/vpc_api01_0003.html。

约束限制

不涉及

取值范围

VPC ID

默认取值

不涉及

network_interfaces

Array of NetworkInterface objects

参数解释

指定裸金属服务器的网卡信息。

约束限制

一个裸金属服务器最多挂载2个网卡,参数中第一个网卡会作为裸金属服务器的主网卡。若用户指定了多组网卡参数,需保证各组参数都属于同一VPC。

tags

Array of Tag objects

参数解释

标签

约束限制

不涉及

image

Image object

参数解释

服务器镜像信息

约束限制

不涉及

description

String

参数解释

云服务器描述信息。

约束限制

不涉及

取值范围

不涉及

默认取值

空字符串

state

String

参数解释

实例状态

约束限制

不涉及

取值范围

  • pending:实例正在启动(分配资源/启动操作系统)

  • running:实例正常运行(可接受SSH/RDP连接)

  • stopping:实例正在关闭(停止/休眠过渡状态)

  • stopped: 实例已完全关闭(存储卷保留)

  • reinstalling:实例正在重装中

  • shutting-down:实例正在终止(删除流程中)

  • terminated:实例已终止(资源完全删除,不可恢复)

  • failed:实例处于失败状态,对于reinstall操作可重试,其它操作不可重试并清除相关资源

默认取值

不涉及

metadata

表9 object

-

user_data

String

参数解释

创建实例过程中待注入实例自定义数据。

约束限制

不涉及

取值范围

user_data的值为base64编码之后的内容。

注入内容(编码之前的内容)最大长度为32K。

默认取值

不涉及

server_id

String

参数解释

服务器ID

约束限制

不涉及

取值范围

uuid格式

默认取值

不涉及

created_at

String

参数解释

创建时间

约束限制

不涉及

取值范围

使用RFC 3339格式,例如:2025-04-22T12:03:18.50083+08:00

默认取值

不涉及

updated_at

String

参数解释

更新时间

约束限制

不涉及

取值范围

使用RFC 3339格式,例如:2025-04-22T12:03:18.50083+08:00

默认取值

不涉及

launched_at

String

参数解释

启动时间

约束限制

不涉及

取值范围

使用RFC 3339格式,例如:2025-04-22T12:03:18.50083+08:00

默认取值

不涉及

error

ErrorStatus object

参数解释

失败时返回的错误对象

约束限制

不涉及

表6 NetworkInterface

参数

参数类型

描述

subnet_id

String

参数解释

subnet id

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

ipv4_address

String

参数解释

弹性网卡私有IPv4地址

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

表7 Tag

参数

参数类型

描述

key

String

参数解释

标签key值

约束限制

不涉及

取值范围

  • 不能为空且首尾不能包含空格,最多支持128个字符

  • 可用UTF-8格式表示的任意语种字母、数字和空格

  • 支持部分特殊字符:_.:=+-@

  • 不能以"sys"开头

默认取值

不涉及

value

String

参数解释

标签value值

约束限制

不涉及

取值范围

  • 可以为空但不能缺省,最多支持255个字符

  • 可用UTF-8格式表示的汉字、字母、数字和空格

  • 支持部分特殊字符:_.:/=+-@

默认取值

不涉及

表8 Image

参数

参数类型

描述

id

String

参数解释

镜像ID

约束限制

不涉及

取值范围

格式为UUID

默认取值

不涉及

name

String

参数解释

镜像名称

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

os_type

String

参数解释

镜像os类型

约束限制

不涉及

取值范围

  • Linux

  • Windows

  • Other

默认取值

不涉及

表9 metadata

参数

参数类型

描述

{自定义key}

Map<String,String>

参数解释

创建裸机实例的元数据。可以通过元数据自定义键值对。

如果元数据中包含了敏感数据,您应当采取适当的措施来保护敏感数据,比如限制访问范围、加密等。

约束限制

不涉及

取值范围

最多可注入10对键值(Key/Value)。

主键(Key)只能由大写字母(A-Z)、小写字母(a-z)、数字(0-9)、中划线(-)、下划线(_)、冒号(:)、空格( )和小数点(.)组成,长度为[1-255]个字符。

值(value)最大长度为255个字符。

默认取值

不涉及

表10 ErrorStatus

参数

参数类型

描述

error_code

String

参数解释

错误码

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

error_msg

String

参数解释

错误描述

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

error_type

String

参数解释

错误类型

约束限制

不涉及

取值范围

  • create_instance_error:创建实例异常

  • delete_instance_error:删除实例异常

  • reinstall_error:重装OS异常

  • modify_ip_error:修改IP异常

  • verify_server_error:验证服务器异常

  • delete_server_error:删除服务器异常

默认取值

不涉及

表11 PageInfo

参数

参数类型

描述

next_marker

String

参数解释

下一页查询地址

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

previous_marker

String

参数解释

上一页查询地址

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

current_count

Integer

参数解释

本页返回条目数量

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

状态码:400

表12 响应Body参数

参数

参数类型

描述

error_code

String

参数解释

错误码

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

error_msg

String

参数解释

错误描述

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

状态码:401

表13 响应Body参数

参数

参数类型

描述

error_code

String

参数解释

错误码

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

error_msg

String

参数解释

错误描述

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

状态码:429

表14 响应Body参数

参数

参数类型

描述

-

String

-

状态码:500

表15 响应Body参数

参数

参数类型

描述

error_code

String

参数解释

错误码

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

error_msg

String

参数解释

错误描述

约束限制

不涉及

取值范围

不涉及

默认取值

不涉及

请求示例

批量查询实例

GET https://{endpoint}/v1/{project_id}/instances

响应示例

状态码:200

实例列表分页

{
  "instances" : [ {
    "id" : "0195f996-79c5-7d34-a98e-3a96f7926d96",
    "name" : "host-0403-199",
    "vpc_id" : "31434907-0817-4acc-9a59-c44cf157303b",
    "network_interfaces" : [ {
      "subnet_id" : "",
      "ipv4_address" : "192.168.27.57"
    } ],
    "image" : {
      "id" : "e66a19b0-8c94-4b03-9f4d-4fbd676bcbf0",
      "name" : "test-lsy\nUbuntu 22.04 server 64bit",
      "os_type" : "Linux"
    },
    "description" : "",
    "state" : "terminated",
    "user_data" : "",
    "server_id" : "0195f996-79c5-7d34-a98e-3a96f7926d96",
    "created_at" : "",
    "updated_at" : "2025-07-11T17:07:05+08:00",
    "launched_at" : "2025-04-03T10:59:03+08:00",
    "error" : {
      "error_code" : "iMetal.0099",
      "error_msg" : "failed to reinstall os, create reinstall job on Jarvis failed",
      "error_type" : "reinstall_error"
    }
  } ],
  "page_info" : {
    "next_marker" : "01981672-2e82-7d8a-a315-3f686155a815",
    "previous_marker" : "",
    "current_count" : 92
  },
  "count" : 92
}

状态码

状态码

描述

200

实例列表分页

400

请求参数错误,请求失败

401

请求未鉴权

429

请求过载

500

服务端内部错误

错误码

请参见错误码

相关文档