# 按标签查询专属主机列表 - ListDedicatedHostsByTags #### 功能介绍 - 使用标签过滤专属主机列表，并返回专属主机使用的所有标签。 - 标签管理服务（TMS）使用该接口过滤专属主机列表。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=DeH&api=ListDedicatedHostsByTags)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-deh/deh_08_0001.html)。 #### 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]。 | 表3tag字段数据结构说明 | 参数 | 参数类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | key | String | 是 | 键。 - 最大长度127个unicode字符。 - key不能为空。 | | values | Array of strings | 否 | 值列表。 - 最多10个value。 - value不允许重复。 - 每个值最大长度255个unicode字符。 - 如果value缺失则表示any_value。 - value之间为"或"的关系。 | 表4match字段数据结构说明 | 参数 | 参数类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | key | String | 是 | 键，表示要匹配的字段。 - key不能重复，value为匹配的值。 - 此字段为固定字典值。 - 不允许为空字符串。 说明： 当前key的参数值仅支持resource_name，此时value的参数值为专属主机名称。 | | value | String | 是 | 值。 - 每个值最大长度为255个unicode字符。 - 不可以为空 。 | #### 响应消息 表5响应参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | resources | Array of objects | 返回的专属主机列表，详情参见[表6]。 | | total_count | Integer | 总记录数。 | 表6resource字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | resource_id | String | 专属主机ID。 | | resource_detail | String | 专属主机详情。 该字段用于后续扩展，默认为空。 | | tags | Array of objects | 标签列表。 详见表[表7]。 | | resource_name | String | 资源名称。 | 表7tag字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 } ``` #### 返回值 请参见[状态码](https://support.huaweicloud.com/api-deh/deh_02_0016.html)。