文档首页/MapReduce服务 MRS/API参考/API V1.1/标签管理接口/查询特定标签的集群列表-ListClustersByTags
更新时间：2026-01-12 GMT+08:00
查看PDF
分享

查询特定标签的集群列表-ListClustersByTags

功能介绍

使用标签过滤集群。

集群默认按照创建时间倒序，集群tag也按照创建时间倒序。

接口约束

无

调试

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

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和受限项。
  • 如果使用身份策略授权，当前API调用无需身份策略权限。

URI

  • URI格式

    POST /v1.1/{project_id}/clusters/resource_instances/action

  • 参数说明
    表1 参数说明

    参数

    是否必选

    参数类型

    描述

    project_id

    是

    String

    参数解释：

    项目编号。获取方法，请参见获取项目ID。

    约束限制：

    不涉及

    取值范围：

    只能由英文字母和数字组成，且长度为[1-64]个字符。

    默认取值：

    不涉及

请求参数

表2 请求Body参数

参数

是否必选

参数类型

描述

tags

否

Array of TagWithMultiValue objects

参数解释：

返回结果包含该参数中所有标签对应的资源。

约束限制：

该参数最多包含10个key，每个key下面的value最多10个，结构体不能缺失，key不能为空或者空字符串。参数说明请参见表3。

取值范围：

不涉及

默认取值：

不涉及

tags_any

否

Array of TagWithMultiValue objects

参数解释：

返回结果包含该参数中任意一个标签对应的资源。

约束限制：

该参数最多包含10个key，每个key下面的value最多10个，结构体不能缺失，key不能为空或者空字符串。Key不能重复，同一个key中values不能重复。参数说明请参见表3。

取值范围：

不涉及

默认取值：

不涉及

not_tags

否

Array of TagWithMultiValue objects

参数解释：

返回结果不包含该参数中所有标签对应的资源。

约束限制：

该参数最多包含10个key，每个key下面的value最多10个，结构体不能缺失，key不能为空或者空字符串。Key不能重复，同一个key中values不能重复。参数说明请参见表3。

取值范围：

不涉及

默认取值：

不涉及

not_tags_any

否

Array of TagWithMultiValue objects

参数解释：

返回结果不包含该参数中任意一个标签对应的资源。

约束限制：

该参数最多包含10个key，每个key下面的value最多10个，结构体不能缺失，key不能为空或者空字符串。Key不能重复，同一个key中values不能重复。参数说明请参见表3。

取值范围：

不涉及

默认取值：

不涉及

limit

否

Integer

参数解释：

查询记录数。

约束限制：

action为count时无此参数。如果action为filter默认为1000。

取值范围：

1-1000

默认取值：

不涉及

offset

否

Integer

参数解释：

索引位置，从offset指定的下一条数据开始查询。查询第一页数据时，不需要传入此参数，查询后续页码数据时，将查询前一页数据时响应体中的值带入此参数。

约束限制：

action为count时无此参数。如果action为filter默认为0。

取值范围：

≥0

默认取值：

不涉及

action

是

String

参数解释：

操作标识（仅限于filter，count），如果是filter则为分页查询，如果是count会按照条件将总条数返回。

约束限制：

不涉及

取值范围：

  • filter：过滤
  • count：查询总条数

默认取值：

不涉及

matches

否

Array of Match objects

参数解释：

搜索字段，key为要匹配的字段，如resource_name等。value为匹配的值。此字段为固定字典值。根据不同的字段确认是否需要模糊匹配，如resource_name默认为模糊搜索，如果value为空字符串精确匹配。参数说明请参见表4。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

表3 TagWithMultiValue

名称

是否必选

参数类型

说明

key

是

String

参数解释：

标签的键。

约束限制：

不涉及

取值范围：

标签的key值可以包含任意语种字母、数字、空格和_.:=+-@，但首尾不能含有空格，不能以_sys_开头。

默认取值：

不涉及

values

否

Array of strings

参数解释：

标签的值。

约束限制：

标签的value值可以包含任意语种字母、数字、空格和_.:=+-@，但首尾不能含有空格，不能以_sys_开头。

取值范围：

不涉及

默认取值：

不涉及

表4 Match

名称

是否必选

参数类型

说明

key

否

String

参数解释：

键。当前只有resource_name可用，表示集群的名称，后续扩展。

约束限制：

不涉及

取值范围：

长度为[1-64]个字符。

默认取值：

不涉及

value

否

String

参数解释：

值。每个值最大长度64个unicode字符。

约束限制：

不涉及

取值范围：

长度为[0-64]个字符。

默认取值：

不涉及

响应参数

表5 响应参数说明

参数名

参数类型

说明

resources

Array of MRSResource objects

参数解释：

资源详情，请参见表6。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

total_count

Integer

参数解释：

资源总数。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

表6 MRSResource

参数名

参数类型

说明

resource_detail

String

参数解释：

资源详情。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

resource_id

String

参数解释：

资源ID。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

resource_name

String

参数解释：

资源名称。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

tags

Array of TagPlain objects

参数解释：

标签列表，请参见表7。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

表7 TagPlain

参数

参数类型

描述

key

String

参数解释：

标签的键。

约束限制：

不涉及

取值范围：

标签的key值可以包含任意语种字母、数字、空格和_.:=+-@，但首尾不能含有空格，不能以_sys_开头。

默认取值：

不涉及

value

String

参数解释：

标签的值。

约束限制：

不涉及

取值范围：

标签的value值可以包含任意语种字母、数字、空格和_.:=+-@，但首尾不能含有空格，不能以_sys_开头。

默认取值：

不涉及

请求示例

  • 查询action为filter时的集群列表 
    POST https://{endpoint}/v1.1/{project_id}/{resource_type}/resource_instances/action

{
  "offset" : "100",
  "limit" : "100",
  "action" : "filter",
  "matches" : [ {
    "key" : "resource_name",
    "value" : "clusterA"
  } ],
  "not_tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "not_tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ]
}
  • 查询action为count时的集群列表 
    POST https://{endpoint}/v1.1/{project_id}/{resource_type}/resource_instances/action

{
  "action" : "count",
  "not_tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  }, {
    "key" : "key2",
    "values" : [ "value1", "value2" ]
  } ],
  "tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "not_tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "matches" : [ {
    "key" : "resource_name",
    "value" : "clusterA"
  } ]
}

响应示例

状态码：200

操作成功。

{
  "resources" : [ {
    "resource_detail" : null,
    "resource_id" : "cdfs_cefs_wesas_12_dsad",
    "resource_name" : "clusterA",
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value1"
    } ]
  } ],
  "total_count" : "1000"
}

状态码

状态码请参见状态码。

错误码

请参见错误码。

父主题：标签管理接口