# 按标签条件分页查询超节点列表-ListHypernodesByTag
#### 功能介绍
按标签条件分页查询超节点列表接口，用于根据标签、资源名称或资源 ID 等组合条件，分页查询指定项目下符合条件的超节点实例列表。
该接口适用于以下场景：控制台按标签筛选超节点、导出满足条件的资源清单等。请求体过滤条件与统计接口相同，分页通过 query 参数 limit、offset 控制。
#### 调试
您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/AICS/doc?api=ListHypernodesByTag)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
#### 授权信息
账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-aics/aics_05_0700.html)。
| 授权项                               | 访问级别 | 资源类型（\*为必须） | 条件键       | 别名 | 依赖的授权项 |
|:---|:---|:---|:---|:---|:---|
| aics:hypernode:listResourcesByTag | List | -           | g:TagKeys | -  | -      |
   
#### URI
POST /v2/{project_id}/hypernodes/resource-instances/filter
表1路径参数 
| 参数         | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                         |
|:---|:---|:---|:---|
| project_id | 是    | String | **参数解释**: 项目ID，获取方法请参见[获取项目ID](https://support.huaweicloud.com/api-aics/aics_api_0702.html)。 **约束限制**: 不涉及。 **取值范围**: 不涉及。 **默认取值**: 不涉及。 |
   
表2Query参数 
| 参数     | 是否必选 | 参数类型    | 描述                                                                                                                                                                                                                                                                                                                                                                                          |
|:---|:---|:---|:---|
| limit  | 否    | Integer | **参数解释**: 分页大小，表示单次返回的最大资源实例条数。 **约束限制**: 不涉及。 **取值范围**: 1\~100。 **默认取值**: 100。                            |
| offset | 否    | Integer | **参数解释**: 分页偏移量，表示从满足条件的第几条结果开始返回。 **约束限制**: 从 0 开始计数；与 limit 组合使用实现分页。 **取值范围**: 大于等于 0 的整数。 **默认取值**: 0。 |
   
#### 请求参数
表3请求Header参数 
| 参数           | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                               |
|:---|:---|:---|:---|
| X-Auth-Token | 否    | String | **参数解释**: 用户Token，通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 **约束限制**: 不涉及。 **取值范围**: 不涉及。 **默认取值**: 不涉及。 |
   
表4请求Body参数 
| 参数              | 是否必选 | 参数类型                                                                  | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|:---|:---|:---|:---|
| without_any_tag | 否    | Boolean                                                               | **参数解释**: 是否仅查询未绑定任何标签的资源。 **约束限制**: 为 true 时返回所有不带标签的资源，此时忽略 tags 字段；为 false 或未指定时该条件不生效。 **取值范围**: - true：仅查询未绑定任何标签的资源。   - false：查询所有资源。    **默认取值**: false。 |
| tags            | 否    | Array of [FilterTag] objects | **参数解释**: 按标签过滤资源。 **约束限制**: 最多指定 20 个标签键，每个键下最多 64 个取值；多个标签键之间为"与"关系，同一键下多个取值为"或"关系；若某键的 values 为空数组，表示仅按该键是否存在进行过滤。 **取值范围**: 不涉及。 **默认取值**: 不涉及。                                                                                                                                                                                                                                                                                                                                                                          |
| matches         | 否    | Array of [Match] objects         | **参数解释**: 按资源名称或资源 ID 等属性进行附加匹配，可与标签条件组合使用。 **约束限制**: 最多指定 16 条匹配条件。 **取值范围**: 不涉及。 **默认取值**: 不涉及。                                                                                                                                                                                                                                                                                                                                                                                                                           |
   
 表5FilterTag 
| 参数     | 是否必选 | 参数类型             | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|:---|:---|:---|:---|
| key    | 是    | String           | **参数解释**: 标签键。 **约束限制**: 不能以 _sys_ 开头；首尾不能为空白字符。 **取值范围**: 最大128个Unicode字符，满足'\^((?!\\s)(?!_sys_)\[\\p{L}\\p{Z}\\p{N}_.:/=+-@\]\*)(?\<!\\s)$'。 **默认取值**: 不涉及。 |
| values | 是    | Array of strings | **参数解释**: 标签取值列表。 **约束限制**: 为空数组时表示仅匹配存在该标签键的资源，不限定取值。 **取值范围**: 每个取值最大255个Unicode字符；最多64个取值，满足'\^(\[\\p{L}\\p{Z}\\p{N}_.:/=+-@\]\*)$'。 **默认取值**: 不涉及。        |
   
 表6Match 
| 参数    | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|:---|:---|:---|:---|
| key   | 否    | String | **参数解释**: 匹配字段名。 **约束限制**: 仅支持 resource_name 或 resource_id；传入其他字段将返回 400。 **取值范围**: - resource_name：按资源名称匹配。   - resource_id：按资源ID匹配。    **默认取值**: 不涉及。 |
| value | 否    | String | **参数解释**: 与 key 对应的匹配值。 **约束限制**: 支持精确匹配或正则表达式，具体规则遵循 TMS 约定。 **取值范围**: 最大 512 个字符。 **默认取值**: 不涉及。                                                                                                                                                                                                                                                                                                                                                                                                                  |
   
#### 响应参数
**状态码：200**
表7响应Body参数 
| 参数          | 参数类型                                                                 | 描述                                                                                                                                                                  |
|:---|:---|:---|
| total_count | Integer                                                              | **参数解释**: 满足过滤条件的资源实例总数。 **取值范围**: 大于等于 0 的整数。 |
| resources   | Array of [Resource] objects | **参数解释**: 当前页的资源实例列表。 **取值范围**: 不涉及。           |
   
 表8Resource 
| 参数              | 参数类型                                                                   | 描述                                                                                                                                                             |
|:---|:---|:---|
| resource_id     | String                                                                 | **参数解释**: 资源实例 ID。 **取值范围**: 最大 128 个字符。  |
| resource_name   | String                                                                 | **参数解释**: 资源实例名称。 **取值范围**: 最大 256 个字符。   |
| tags            | Array of [TagKv] objects         | **参数解释**: 该资源实例上绑定的用户标签列表。 **取值范围**: 不涉及。 |
| resource_detail | [ResourceDetail] object | **参数解释**: 资源扩展属性。 **取值范围**: 不涉及。          |
   
 表9TagKv 
| 参数    | 参数类型   | 描述                                                                                                                                                                                                                                |
|:---|:---|:---|
| key   | String | **参数解释**: 标签键。 **取值范围**: 最大128个Unicode字符。满足'\^((?!\\s)(?!_sys_)\[\\p{L}\\p{Z}\\p{N}_.:/=+-@\]\*)(?\<!\\s)$'。 |
| value | String | **参数解释**: 标签值。 **取值范围**: 最大255个Unicode字符。满足'\^(\[\\p{L}\\p{Z}\\p{N}_.:/=+-@\]\*)$'。                          |
   
 表10ResourceDetail 
| 参数         | 参数类型   | 描述                                                                                                                                                             |
|:---|:---|:---|
| cluster_id | String | **参数解释**: 资源所属集群 ID。 **取值范围**: 最大 64 个字符。 |
   
#### 请求示例
按标签条件分页查询超节点列表请求示例。使用场景：用户需要按标签筛选超节点资源时使用，返回满足条件的超节点分页列表。
```
POST https://{endpoint}/v2/{project_id}/hypernodes/resource-instances/filter?limit=10&offset=0
```
#### 响应示例
**状态码：200**
成功返回满足过滤条件的超节点实例分页列表。
```
{
  "total_count" : 2,
  "resources" : [ {
    "resource_id" : "0a100010-0001-4000-8000-000000000010",
    "resource_name" : "alpha-query-hypernode-1",
    "tags" : [ {
      "key" : "env",
      "value" : "prod"
    } ],
    "resource_detail" : {
      "cluster_id" : "550e8400-e29b-41d4-a716-446655440000"
    }
  } ]
}
```
#### 状态码
| 状态码 | 描述                    |
|:---|:---|
| 200 | 成功返回满足过滤条件的超节点实例分页列表。 |
   
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-aics/ErrorCode.html)。