Querying a List of Clusters with Specified Tags

Function

This API is used to filter clusters by tag.

By default, clusters and tags are sorted in descending order of creation time.

Constraints

None

Debugging

You can debug this API in API Explorer. Automatic authentication is supported. API Explorer can automatically generate sample SDK code and provide the sample SDK code debugging.

URI

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

Parameter description

**Table 1** URI parameter
Parameter	Mandatory	Type	Description
project_id	Yes	String	The project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
tags	No	Array of TagWithMultiValue objects	The return result contains resources corresponding to all tags in this parameter. This parameter contains a maximum of 10 keys, and each key contains a maximum of 10 values. The structure body cannot be missing, and the key cannot be left blank or set to an empty string. For details about the parameters, see Table 3.
tags_any	No	Array of TagWithMultiValue objects	The return result contains resources corresponding to any tag in this parameter. This parameter contains a maximum of 10 keys, and each key contains a maximum of 10 values. The structure body cannot be missing, and the key cannot be left blank or set to an empty string. Keys must be unique and values of a key must be unique. For details about the parameters, see Table 3.
not_tags	No	Array of TagWithMultiValue objects	The return result does not contain resources corresponding to all tags in this parameter. This parameter contains a maximum of 10 keys, and each key contains a maximum of 10 values. The structure body cannot be missing, and the key cannot be left blank or set to an empty string. Keys must be unique and values of a key must be unique. For details about the parameters, see Table 3.
not_tags_any	No	Array of TagWithMultiValue objects	The return result does not contain resources corresponding to any tag in this parameter. This parameter contains a maximum of 10 keys, and each key contains a maximum of 10 values. The structure body cannot be missing, and the key cannot be left blank or set to an empty string. Keys must be unique and values of a key must be unique. For details about the parameters, see Table 3.
limit	No	Integer	Number of records. This parameter is not available when action is set to count. The default value is 1000 when action is set to filter. The maximum value is 1000, and the minimum value is 1. The value cannot be a negative number.
offset	No	Integer	Index position. The query starts from the next piece of data specified by the offset parameter. This parameter is not required when you query data on the first page. The value in the response body returned for querying data on the previous page will be included in this parameter for querying data on subsequent pages. This parameter is not available when action is set to count. If action is set to filter, the value must be a number, and the default value is 0. The value cannot be a negative number.
action	Yes	String	Operation to be performed. The value can be filter or count. The value filter indicates pagination query. The value count indicates that the total number of query results meeting the search criteria will be returned.
matches	No	Array of Match objects	Search field. key indicates the field to be matched, for example, resource_name. value indicates the matched value. This field is a fixed dictionary value. Determine whether fuzzy match is required based on different fields. For example, if key is resource_name, fuzzy search is used by default. If value is an empty string, exact match is used. For details about the parameters, see Table 4.

**Table 3** TagWithMultiValue
Parameter	Mandatory	Type	Description
key	Yes	String	Key. A tag key cannot contain special characters (*=<>\,\|/**) or start or end with spaces.
values	No	Array of strings	List of values. A tag value cannot contain special characters (*=<>\,\|/**) or start or end with spaces.

**Table 4** Match
Parameter	Mandatory	Type	Description
key	No	String	Key. Currently, only resource_name is available, indicating the cluster name. Other keys will be supported later.
value	No	String	Value. A value contains a maximum of 64 Unicode characters.

Response Parameters

**Table 5** Response parameters
Parameter	Type	Description
resources	Array of MRSResource objects	Resource details. For details, see Table 6.
total_count	Integer	Total number of resources.

**Table 6** MRSResource
Parameter	Type	Description
resource_detail	String	Resource details.
resource_id	String	Resource ID.
resource_name	String	Resource name.
tags	Array of TagPlain objects	Tag list. For details, see Table 7.

**Table 7** TagPlain
Parameter	Type	Description
key	String	Key. A tag key cannot contain special characters (=*<>\,\|/) or start or end with a space.
value	String	Tag value. A tag value cannot contain special characters (=*<>\,\|/) or start or end with a space.

Example Request

Query the cluster list when action is set to 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" ]
  } ]
}

Query the cluster list when action is set to 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"
  } ]
}

Example Response

Status code: 200

The operation is successful.

{
  "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"
}