文档首页/ 专属主机 DeH/ API参考/ API/ 专属主机标签管理/ 按标签查询专属主机列表
更新时间：2025-08-21 GMT+08:00
查看PDF
分享

按标签查询专属主机列表

功能介绍

  • 使用标签过滤专属主机列表，并返回专属主机使用的所有标签。
  • 标签管理服务（TMS）使用该接口过滤专属主机列表。

URI

POST /v1.0/{project_id}/dedicated-host-tags/resource_instances/action

参数说明请参见表1。

表1 参数说明

参数

参数类型

是否必选

描述

project_id

String

是

项目ID。

请求消息

表2 请求参数

参数

参数类型

是否必选

描述

tags

Array of objects

否

查询包含所有指定标签的专属主机。更多信息，请参见表3。

  • 最多包含10个key，每个key下面的value最多10个。
  • 结构体不能缺失。
  • key不能为空或者空字符串。
  • key不能重复。
  • 同一个key中value不能重复。

not_tags

Array of objects

否

查询不包含所有指定标签的专属主机。更多信息，请参见表3。

  • 最多包含10个key，每个key下面的value最多10个。
  • 结构体不能缺失。
  • key不能为空或者空字符串。
  • Key不能重复。
  • 同一个key中value不能重复。

limit

Integer

否

查询返回的专属主机数量限制，最多为1000，不能为负数。

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

offset

Integer

否

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

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

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

action

String

是

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

  • filter：表示按标签过滤专属主机，返回符合条件的专属主机列表。此时，为分页查询。
  • count：表示按标签搜索专属主机，返回符合条件的专属主机个数。

tags_any

Array of objects

否

包含任意标签。更多信息，请参见表3。

  • 最多包含10个key，每个key下面的value最多10个，每个key对应的value可以为空数组但结构体不能缺失。
  • key不能重复，同一个key中value不能重复。
  • 结果返回包含标签的资源列表，key之间是“或”的关系，key-value结构中value是“或”的关系。
  • 无过滤条件时返回全量数据。

not_tags_any

Array of objects

否

不包含任意标签。更多信息，请参见表3。

  • 最多包含10个key，每个key下面的value最多10个，每个key对应的value可以为空数组但结构体不能缺失。
  • key不能重复，同一个key中value不能重复。
  • 结果返回不包含标签的资源列表，key之间是“或”的关系，key-value结构中value是或的关系。
  • 无过滤条件时返回全量数据。

matches

Array of objects

否

搜索字段，用于按条件搜索专属主机。

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

参数

参数类型

是否必选

描述

key

String

是

键。

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

values

Array of strings

否

值列表。

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

参数

参数类型

是否必选

描述

key

String

是

键，表示要匹配的字段。

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

当前key的参数值仅支持resource_name，此时value的参数值为专属主机名称。

value

String

是

值。

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

响应消息

表5 响应参数

参数

参数类型

描述

resources

Array of objects

返回的专属主机列表，详情参见表6。

total_count

Integer

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

参数

参数类型

描述

resource_id

String

专属主机ID。

resource_detail

String

专属主机详情。

该字段用于后续扩展，默认为空。

tags

Array of objects

标签列表。

详见表表7。

resource_name

String

资源名称。
表7 tag字段数据结构说明

参数

参数类型

描述

key

String

键。

  • 最大长度36个unicode字符。
  • key不能为空。
  • 不能包含以下ASCII非打印字符：“=”,“*”,“<”,“>”,“\”,“|”,“/”,“,”。

value

String

值。

  • 每个值最大长度43个unicode字符。
  • 可以为空字符串。
  • 不能包含以下ASCII非打印字符： “=”,“*”,“<”,“>”,“\”,“|”,“/”,“,”。

请求示例

按标签查询专属主机列表，按标签过滤专属主机，从第一条数据开始查询，搜索名称为resource1的专属主机，标签键为key1值为value1。 
POST https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-host-tags/resource_instances/action 
{ 
    "offset": "0",
    "limit": "100",
    "action": "filter",
    "matches": [
        {
            "key": "resource_name",
            "value": "resource1"
        }
    ],
    "tags": [
        {
            "key": "key1",
            "values": ["value1"]
        }
    ]
}

响应示例

action为filter时的响应体：

{
    "resources": [
        {
            "resource_detail": null,
            "resource_id": "cdfs_cefs_wesas_12_dsad",
            "resource_name": "resource1",
            "tags": [
                {
                    "key": "key1",
                    "value": "value1"
                }
            ]
        }
    ],
    "total_count": 1
}

action为count时的响应体：

{
    "total_count": 100
}

返回值

请参见状态码。