Querying a List of Clusters with Specified Tags

Updated on 2024-12-10 GMT+08:00

View PDF

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	Explanation Project ID. For details about how to obtain the project ID, see Obtaining a Project ID. Constraints N/A Value range The value must consist of 1 to 64 characters. Only letters and digits are allowed. Default value N/A

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
tags	No	Array of TagWithMultiValue objects	Explanation The returned result contains the resources corresponding to all tags in this parameter. Constraints The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. One tag key can have up to 10 tag values. For details about the parameters, see Table 3. Value range N/A Default value N/A
tags_any	No	Array of TagWithMultiValue objects	Explanation The returned result contains the resources corresponding to any tag in this parameter. Constraints The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. One tag key can have up to 10 tag values. Keys must be unique and values of a key must be unique. For details about the parameters, see Table 3. Value range N/A Default value N/A
not_tags	No	Array of TagWithMultiValue objects	Explanation The returned result does not contain the resources corresponding to all tags in this parameter. Constraints The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. One tag key can have up to 10 tag values. Keys must be unique and values of a key must be unique. For details about the parameters, see Table 3. Value range N/A Default value N/A
not_tags_any	No	Array of TagWithMultiValue objects	Explanation The returned result does not contain the resources corresponding to any tag in this parameter. Constraints The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. One tag key can have up to 10 tag values. Keys must be unique and values of a key must be unique. For details about the parameters, see Table 3. Value range N/A Default value N/A
limit	No	Integer	Explanation Number of query records. Constraints If you set action to count, this parameter is not required. If action is set to filter, the default value of this parameter is 1000. Value range 1-1000 Default value N/A
offset	No	Integer	Explanation Index position. The query starts from the next data record indexed by this parameter. You do not need to specify this parameter when you query resources on the first page. When you query resources on subsequent pages, set this parameter to the location returned in the response body for the previous query. Constraints If you set action to count, this parameter is not required. If action is set to filter, the default value is 0. Value range ≥0 Default value N/A
action	Yes	String	Explanation Operation ID (only filter and count is available). filter: The query is paginated. count: The total number of records is returned by search condition. Constraints N/A Value range filter: Perform pagination query. count: Query the total number of resources. Default value N/A
matches	No	Array of Match objects	Explanation 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. Constraints N/A Value range N/A Default value N/A

**Table 3** TagWithMultiValue
Parameter	Mandatory	Type	Description
key	Yes	String	Explanation Tag key. Constraints N/A Value range A tag key can contain letters, digits, spaces, and special characters (_.:=+-@), but cannot start or end with a space or start with _sys_. Default value N/A
values	No	Array of strings	Explanation Tag value. Constraints A tag value can contain letters, digits, spaces, and special characters (_.:=+-@), but cannot start or end with a space or start with _sys_. Value range N/A Default value N/A

**Table 4** Match
Parameter	Mandatory	Type	Description
key	No	String	Explanation Key. Currently, only resource_name is available, indicating the cluster name. Other keys will be supported later. Constraints N/A Value range The value can contain 1 to 64 characters. Default value N/A
value	No	String	Explanation Value. A value can contain a maximum of 64 Unicode characters. Constraints N/A Value range The value can contain 0 to 64 characters. Default value N/A

Response Parameters

**Table 5** Response parameters
Parameter	Type	Description
resources	Array of MRSResource objects	Explanation Resource details. For details, see Table 6. Constraints N/A Value range N/A Default value N/A
total_count	Integer	Explanation Total number of resources. Constraints N/A Value range N/A Default value N/A

**Table 6** MRSResource
Parameter	Type	Description
resource_detail	String	Explanation Resource details. Constraints N/A Value range N/A Default value N/A
resource_id	String	Explanation Resource ID. Constraints N/A Value range N/A Default value N/A
resource_name	String	Explanation Resource name. Constraints N/A Value range N/A Default value N/A
tags	Array of TagPlain objects	Explanation Tag list. For details, see Table 7. Constraints N/A Value range N/A Default value N/A

**Table 7** TagPlain
Parameter	Type	Description
key	String	Explanation Tag key. Constraints N/A Value range A tag key can contain letters, digits, spaces, and special characters (_.:=+-@), but cannot start or end with a space or start with _sys_. Default value N/A
value	String	Explanation Tag value. Constraints N/A Value range A tag value can contain letters, digits, spaces, and special characters (_.:=+-@), but cannot start or end with a space or start with _sys_. Default value N/A

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