Help Center/ Global Accelerator/ API Reference/ API/ Tag/ Querying Resources by Tag

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

Online Debugging

CLI Examples

View PDF

Querying Resources by Tag

Function

This API is used to query resources by tag.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{resource_type}/resource-instances/filter

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
resource_type	Yes	Object	Specifies the resource type.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
limit	No	Integer	Specifies the number of results on each page. Minimum: 1 Maximum: 1000 Default: 1000
offset	No	Integer	Specifies the number of bytes to skip before starting to read data. Minimum: 0 Default: 0

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Specifies the user token. The token can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token.

**Table 4** Request body parameters
Parameter	Mandatory	Type	Description
tags	No	Array of Tag objects	Specifies the tag list. Array Length: 1 - 20
matches	No	Array of Match objects	Specifies the matched results. Array Length: 1 - 1

**Table 5** Tag
Parameter	Mandatory	Type	Description
key	Yes	String	Specifies tag key. Minimum: 1 Maximum: 128
values	Yes	Array of strings	Specifies the values of the tag. Minimum: 0 Maximum: 255 Array Length: 0 - 10

**Table 6** Match
Parameter	Mandatory	Type	Description
key	Yes	String	Specifies the key of the matched result. Enumeration values: resource_name
value	Yes	String	Specifies the value of the matched result. Minimum: 0 Maximum: 255

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
resources	Array of ResourceTags objects	Specifies the resource list.
total_count	Integer	Specifies the total number of resources.

**Table 8** ResourceTags
Parameter	Type	Description
resource_id	String	Specifies the resource ID.
resource_name	String	Specifies resource name.
tags	Array of ResourceTag objects	Specifies the tag.

**Table 9** ResourceTag
Parameter	Type	Description
key	String	Specifies the tag key. The key must meet the following requirements: The key can contain 1 to 128 characters. The key can contain UTF-8 letters, digits, spaces, and the following characters:_.:=+-@ Tags starting with _sys_ are system tags and cannot be entered by tenants. Minimum: 1 Maximum: 128
value	String	Specifies the tag value. The value must meet the following requirements: The value can contain 0 to 255 characters. The key can contain UTF-8 letters, digits, spaces, and the following characters:_.:/=+-@ The value can be empty or null. Minimum: 0 Maximum: 255

Example Requests

Querying Resources by Tag

POST https://{ga_endpoint}/v1/{resource_type}/resource-instances/filter

{
  "tags" : [ {
    "key" : "tagKey",
    "values" : [ "tagValue" ]
  } ],
  "matches" : [ {
    "key" : "resourceName",
    "value" : "name"
  } ]
}

Example Responses

Status code: 200

Operation successful.

{
  "resources" : [ {
    "resource_id" : "c2b210b2-60c4-449d-91e2-9e9ea1dd7443",
    "resource_name" : "resourceName",
    "tags" : [ {
      "key" : "tagKey",
      "value" : "tagValue"
    } ]
  } ],
  "total_count" : 1
}