Updated on 2022-12-14 GMT+08:00

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.

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 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.

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 tag parameters

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 parameters

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

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 resources parameters

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 tags parameters

Parameter

Type

Description

key

String

Key.

value

String

Tag value.

Example

  • Example request

    Request body when action is set to filter

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

    Request body when action is set to count

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

    Response body when action is set to filter

        { 
          "resources": [
             {
                "resource_detail": null, 
                "resource_id": "cdfs_cefs_wesas_12_dsad", 
                "resource_name": "clusterA"
             }
           ]
          "total_count": 1000
    }

    Response body when action is set to count

    {
           "total_count": 1000
    }

Status Codes

See Status Codes.

Error Codes

See Error Codes.