文档首页/ 弹性云服务器 ECS/ API参考（安卡拉区域）/ API（推荐）/ 标签管理/ 按标签查询云服务器列表
更新时间：2024-04-16 GMT+08:00
查看PDF

按标签查询云服务器列表

功能介绍

使用标签过滤弹性云服务器，并返回云服务器使用的所有标签。

URI

POST /v1/{project_id}/servers/resource_instances/action

参数说明请参见表1。
表1 参数说明

参数

是否必选

描述

project_id

是

项目ID。

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

请求消息

请求参数如表2所示。
表2 请求参数

参数

是否必选

参数类型

描述

tags

否

Array of objects

查询包含所有指定标签的弹性云服务器，详情请参见表3。

  • 结构体不能缺失。
  • key不能为空或者空字符串。
  • key不能重复。
  • 同一个key中values不能重复。

not_tags

否

Array of strings

查询不包含所有指定标签的弹性云服务器。

  • 结构体不能缺失。
  • key不能为空或者空字符串。
  • Key不能重复。
  • 同一个key中values不能重复。

limit

否

String

查询返回的云服务器数量限制，最多为1000，不能为负数。

  • 如果action的值为count，此参数无效。
  • 如果action的值为filter，limit默认为1000。

offset

否

String

索引位置，从offset指定的下一条数据开始查询。必须为数字，不能为负数。

查询第一页数据时，不需要传入此参数。查询后续页码数据时，将查询前一页数据时响应体中的值带入此参数。

  • 如果action的值为count，此参数无效。
  • 如果action的值为filter，offset默认为0。

action

是

String

操作标识，包括filter和count两种。

  • filter：表示按标签过滤弹性云服务器，返回符合条件的云服务器列表。此时，为分页查询。
  • count：表示按标签搜索弹性云服务器，返回符合条件的云服务器个数。

matches

否

Array of objects

搜索字段，用于按条件搜索弹性云服务器。

当前仅支持按resource_name进行搜索。更多信息，请参见表4。
表3 tag字段数据结构说明

参数

是否必选

参数类型

描述

key

是

String

键。

  • 最大长度127个unicode字符。
  • key不能为空。

values

否

Array of strings

值列表。

  • Value不允许重复。
  • 每个值最大长度255 个unicode字符。
  • 如果values缺失则表示any_value。
  • value之间为或的关系。
表4 match字段数据结构说明

参数

是否必选

参数类型

描述

key

是

String

键，表示要匹配的字段。

当前key的参数值只能取“resource_name”，此时value的参数值为云服务器名称。

  • Key不能重复，value为匹配的值。
  • 此字段为固定字典值。
  • 不允许为空字符串。

value

是

String

值。

当前key的参数值只能取“resource_name”，此时value的参数值为云服务器名称。

  • 每个值最大长度255个unicode字符。
  • 不可以为空 。

响应消息

响应参数如表5所示。

表5 响应参数

参数

参数类型

描述

resources

Array of objects

返回的云服务器列表，详情参见表6。

total_count

Integer

总记录数
表6 resource字段数据结构说明

参数

参数类型

描述

resource_id

String

云服务器ID

resouce_detail

String

云服务器详情，对象。

tags

Array of objects

标签列表

resource_name

String

资源名称，即弹性云服务器名称。
表7 resource_tag字段数据结构说明

参数

参数类型

描述

key

String

键。

  • 最大长度36个unicode字符。
  • key不能为空。
  • 只能包含字母、数字、下划线“_”、中划线“-”。

value

String

值。

  • 每个值最大长度43个unicode字符。
  • 可以为空字符串。
  • 只能包含字母、数字、下划线“_”、中划线“-”。

请求示例

POST https://{endpoint}/v1/{project_id}/servers/resource_instances/action

{
    "offset": "100", 
    "limit": "100", 
    "action": "filter", 
    "matches":[
    {
        "key": "resource_name", 
        "value": "ecs_test"
     }], 
    "tags": [
    {
        "key": "key1", 
        "values": [
            "value1", 
            "value2"
        ]
    }]
}

响应示例

  • action为filter时响应体
    {
      "resources": [
         {
            "resource_detail": null, 
            "resource_id": "cdfs_cefs_wesas_12_dsad", 
            "resource_name": "ecs_test", 
            "tags": [
                {
                   "key": "key1",
                   "value": "value1"
                }
             ]
         }
       ], 
      "total_count": 1000
}
  • action为count时响应体
    {
       "total_count": 1000
}

返回值

请参考通用请求返回值。

错误码

请参考错误码。

父主题： 标签管理