Updated on 2024-04-19 GMT+08:00

Querying Listeners by Tag

Function

This API is used to query listeners by tag.

Constraints

None

URI

POST /v2.0/{project_id}/listeners/resource_instances/action

Table 1 Parameter description

Parameter

Mandatory

Type

Description

project_id

Yes

String

Specifies the ID of the project where the tag is used.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

Table 3 Parameter description

Parameter

Mandatory

Type

Description

tags

No

Array

Specifies the included tags. A maximum of 10 tag keys are allowed for each query operation. Each tag key can have up to 10 tag values. The structure body must be included. The tag key cannot be left blank or set to an empty string. Each tag key and each tag value of the same tag key must be unique. For details, see Table 4.

limit

No

Integer

Sets the page size. This parameter is available when action is set to filter. Both the default value and maximum value are 1000, and the minimum value is 1. The value cannot be a negative integer.

offset

No

Integer

Specifies the index position. The query starts from the next listener indexed by this parameter. This parameter is not required when you query listeners on the first page. The value in the response returned for querying the listeners on the previous page will be included in this parameter for querying the listeners 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 positive integer, and the default value is 0.

action

Yes

String

Identifies the operation. The value can be filter or count.

  • filter: indicates pagination query.
  • count: indicates that all listeners meeting the search criteria will be returned.

matches

No

Array

Specifies the search criteria. The tag key is the parameter to match, for example, resource_name. value indicates the value of the match content. The key is a fixed dictionary value.

Determine whether fuzzy match is required based on different parameters. For example, if the key is resource_name, fuzzy search is used by default. If value is an empty string, exact match is used. If the key is resource_id, exact match is used. For details, see Table 5.

Table 4 tags parameter description

Parameter

Mandatory

Type

Description

key

Yes

String

Specifies the tag key. It contains a maximum of 127 Unicode characters and cannot be left blank. (This parameter is not verified in the search process.)

values

Yes

Array

Lists the tag values. Each tag value can contain a maximum of 255 Unicode characters. The values are in the OR relationship.

Table 5 matches parameter description

Parameter

Mandatory

Type

Description

key

Yes

String

Specifies the tag key.

The value can be one of the following:

  • resource_name: indicates the resource name.
  • resource_id: indicates the resource ID.

value

Yes

String

Specifies the tag value. Each tag value can contain a maximum of 255 Unicode characters.

Response Parameters

Table 6 Response parameters

Parameter

Type

Description

resources

Array

Lists the listeners. For details, see Table 7.

total_count

Integer

Specifies the total number of queried records.

Table 7 resource parameter description

Parameter

Type

Description

resource_id

String

Specifies the resource ID.

resource_detail

String

Specifies the resource details. The value is a resource object, used for extension. The value is left blank by default.

tags

Array

Lists the tags. If there is no tag, an empty array is used by default. For details, see Table 8.

resource_name

String

Specifies the resource name. This parameter is an empty string by default if there is no resource name.

super_resource_id

String

Specifies the parent resource ID.

Table 8 tags parameter description

Parameter

Type

Description

key

String

Specifies the tag key. It contains a maximum of 127 Unicode characters and cannot be left blank. (This parameter is not verified in the search process.)

value

String

Specifies the tag value. Each tag value can contain a maximum of 255 Unicode characters.

Example Request

  • Example request 1 (when action is set to filter)
    POST https://{Endpoint}/v2.0/6a0de1c3-7d74-4f4a-b75e-e57135bd2b97/listeners/resource_instances/action
    
    {
        "offset": "100", 
        "limit": "100", 
        "action": "filter", 
        "matches": [
            {
                "key": "resource_name", 
                "value": "resource1"
            }
        ], 
        "tags": [
            {
                "key": "key1", 
                "values": [
                    "value1", 
                    "value2"
                ]
            }
        ]
    }
  • Example request 2 (when action is set to count)
    POST https://{Endpoint}/v2.0/6a0de1c3-7d74-4f4a-b75e-e57135bd2b97/listeners/resource_instances/action
    
    {
        "action": "count", 
        "tags": [
            {
                "key": "key1", 
                "values": [
                    "value1", 
                    "value2"
                ]
            }, 
            {
                "key": "key2", 
                "values": [
                    "value1", 
                    "value2"
                ]
            }
        ], 
        "matches": [
            {
                "key": "resource_name", 
                "value": "resource1"
            }
        ]
    }

Example Response

  • Example response 1
    {
        "resources": [
            {
                "resource_detail":"", 
                "resource_id": "154d135b-3a89-4e89-8023-06efb9acdc05", 
                "resource_name": "resouece1", 
                "tags": [
                    {
                        "key": "key1", 
                        "value": "value1"
                    }, 
                    {
                        "key": "key2", 
                        "value": "value1"
                    }
                ]
            }
        ], 
        "total_count": 1000
    }
  • Example response 2
    {
        "total_count": 1000
    }

Status Code

For details, see Status Codes.