更新时间:2024-01-10 GMT+08:00

按标签查询云服务器列表

功能介绍

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

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
    }

返回值

请参考通用请求返回值

错误码

请参考错误码