按标签条件分页查询节点列表-ListNodesByTag

功能介绍

按标签条件分页查询节点列表接口，用于根据标签、资源名称或资源 ID 等组合条件，分页查询指定项目下符合条件的节点实例列表。

该接口适用于以下场景：控制台按标签筛选节点、导出满足条件的资源清单等。请求体过滤条件与统计接口相同，分页通过 query 参数 limit、offset 控制。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项	访问级别	资源类型（*为必须）	条件键	别名	依赖的授权项
aics:node:listResourcesByTag	List	-	g:TagKeys	-	-

URI

POST /v2/{project_id}/nodes/resource-instances/filter

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释: 项目ID，获取方法请参见获取项目ID。约束限制: 不涉及。取值范围: 不涉及。默认取值: 不涉及。

表2 Query参数
参数	是否必选	参数类型	描述
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 条匹配条件。取值范围: 不涉及。默认取值: 不涉及。

表5 FilterTag
参数	是否必选	参数类型	描述
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}_.:/=+-@])$'。默认取值*: 不涉及。

表6 Match
参数	是否必选	参数类型	描述
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	参数解释: 当前页的资源实例列表。取值范围: 不涉及。

表8 Resource
参数	参数类型	描述
resource_id	String	参数解释: 资源实例 ID。取值范围: 最大 128 个字符。
resource_name	String	参数解释: 资源实例名称。取值范围: 最大 256 个字符。
tags	Array of TagKv objects	参数解释: 该资源实例上绑定的用户标签列表。取值范围: 不涉及。
resource_detail	ResourceDetail object	参数解释: 资源扩展属性。取值范围: 不涉及。

表9 TagKv
参数	参数类型	描述
key	String	参数解释: 标签键。取值范围: 最大128个Unicode字符。满足'^((?!\s)(?!_sys_)[\p{L}\p{Z}\p{N}_.:/=+-@]*)(?<!\s)$'。
value	String	参数解释: 标签值。取值范围: 最大255个Unicode字符。满足'^([\p{L}\p{Z}\p{N}_.:/=+-@]*)$'。

**表10** ResourceDetail
参数	参数类型	描述
cluster_id	String	参数解释: 资源所属集群 ID。取值范围: 最大 64 个字符。

请求示例

按标签条件分页查询节点列表请求示例。使用场景：用户需要按标签筛选节点资源时使用，返回满足条件的节点分页列表。

POST https://{endpoint}/v2/{project_id}/nodes/resource-instances/filter?limit=10&offset=0

响应示例

状态码：200

成功返回满足过滤条件的节点实例分页列表。

{
  "total_count" : 1,
  "resources" : [ {
    "resource_id" : "0b100010-0001-4000-8000-000000000010",
    "resource_name" : "alpha-query-node-1",
    "tags" : [ {
      "key" : "env",
      "value" : "prod"
    } ],
    "resource_detail" : {
      "cluster_id" : "550e8400-e29b-41d4-a716-446655440000"
    }
  } ]
}

状态码

状态码	描述
200	成功返回满足过滤条件的节点实例分页列表。

错误码

请参见错误码。

父主题： 节点资源标签

上一篇：按标签条件统计节点数量-CountNodesByTag

下一篇：查询节点标签-ListNodeTags