Help Center/ Domain Name Service/ API Reference/ APIs/ Tags/ Querying Resources Using Tags

Updated on 2025-08-19 GMT+08:00

View PDF

Querying Resources Using Tags

Function

This API is used to query resources using tags.

Calling Method

For details, see Calling APIs.

URI

POST /v2/{project_id}/{resource_type}/resource_instances/action

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.
resource_type	Yes	String	Resource type. The value can be DNS-public_zone, DNS-private_zone, DNS-public_recordset, DNS-private_recordset, or DNS-ptr_record.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition The user token. The token can be obtained by calling an IAM API. The value of X-Subject-Token in the response header is the user token. For details about how to obtain a user token, seeObtaining a User Token. Constraints N/A Range N/A Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
tags	No	Array of tagValues objects	Tags that are included. A maximum of 10 tag keys are allowed. The structure body is mandatory. Each tag key must be unique and cannot be left blank or set to an empty string. A tag key can have up to 10 tag values, and each tag value in a tag must be unique.
tags_any	No	Array of tagValues objects	A maximum of 10 tag keys are allowed. The structure body is mandatory. Each tag key must be unique and cannot be left blank or set to an empty string. A tag key can have up to 10 tag values, and each tag value in a tag must be unique.
not_tags	No	Array of tagValues objects	A maximum of 10 tag keys are allowed. The structure body is mandatory. Each tag key must be unique and cannot be left blank or set to an empty string. A tag key can have up to 10 tag values, and each tag value in a tag must be unique.
not_tags_any	No	Array of tagValues objects	A maximum of 10 tag keys are allowed. The structure body is mandatory. Each tag key must be unique and cannot be left blank or set to an empty string. A tag key can have up to 10 tag values, and each tag value in a tag must be unique.
limit	No	Integer	The number of records returned on each page during pagination query. Range: 1 to 1000. If action is set to filter, the default value is 1000. If action is set to count, this parameter is not required.
offset	No	Integer	Start offset of the pagination query. The query will start from the next resource of the offset value. The value ranges from 0 to 2147483647, and the default value is 0. This parameter is not required when data on the first page is queried. When you query resources on subsequent pages, set the value of offset to the location returned in the response body for the previous query. If action is set to filter, the default value is 0. The value must be a number and cannot be a negative number. If action is set to count, this parameter does not exist.
action	Yes	String	Operation to be performed. The value options are case sensitive. Value options: filter: Resources are queried in pages by filter condition. count: The total number of resources is queried.
matches	No	Array of match objects	This parameter specifies the key-value pair to be matched in the query. If value is left blank, exact search will work. Otherwise, fuzzy search will work.

**Table 4** tagValues
Parameter	Mandatory	Type	Description
key	No	String	Key. It can contain a maximum of 128 Unicode characters. The tag key cannot be left blank. (This parameter is not verified in the search process.)
values	No	Array of strings	Value list. Each value can contain a maximum of 255 Unicode characters. An asterisk (*) is a reserved character. If the value starts with an asterisk, fuzzy matching will work for the string following the asterisk. If this parameter is not specified, any value is matched. All values are in the OR relationship.

**Table 5** match
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. The current value is resource_name.
value	No	String	Value. It can contain a maximum of 255 Unicode characters.

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
resources	Array of resourceItem objects	Resource tag list.
total_count	Integer	List of tags added to a resource.

**Table 7** resourceItem
Parameter	Type	Description
resource_id	String	Resource ID.
resource_detail	Object	Resource details. This field is reserved, and its value defaults to an empty string.
tags	Array of tag objects	Tag list. If there is no tag in the list, an empty array is returned.
resource_name	String	Resource name. If no resource name is matched, this parameter is left blank.

**Table 8** tag
Parameter	Type	Description
key	String	Definition The tag key. Range Cannot be left blank. Must be unique for each resource. Contains up to 128 characters. Cannot start or end with a space, or start with *sys*. Only letters, digits, spaces, and the following special characters are allowed: _.:=+-@
value	String	Definition The tag value. Range Can be left blank. Can contain a maximum of 255 characters. Only letters, digits, spaces, and the following special characters are allowed: _.:/=+-@

Example Requests

Querying resources by tag, with the start offset of pagination query set to 100, and the number of resources displayed on each page to 100

POST https://{endpoint}/v2/{project_id}/{resource_type}/resource_instances/action

{
  "offset" : "100",
  "limit" : "100",
  "action" : "filter",
  "matches" : [ {
    "key" : "resource_name",
    "value" : "resource1"
  } ],
  "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" ]
  } ]
}

Example Responses

Status code: 200

Response to the request for querying resources by tag

{
  "resources" : [ {
    "resource_detail" : null,
    "resource_id" : "cdfs_cefs_wesas_12_dsad",
    "resource_name" : "resource1",
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value1"
    } ]
  } ],
  "total_count" : 1000
}