Help Center/ Direct Connect/ API Reference/ APIs/ Tag management/ Querying Resources by Tag

Updated on 2023-12-07 GMT+08:00

View PDF

Querying Resources by Tag

Function

This API is used to query resources such as virtual gateways and virtual interfaces by tag.

Calling Method

For details, see Calling APIs.

URI

POST /v3/{project_id}/{resource_type}/resource-instances/action

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Specifies the project ID.
resource_type	Yes	String	Specifies the Direct Connect resource type. dc-directconnect: connection dc-vgw: virtual gateway dc-vif: virtual interface Enumeration values: dc-directconnect dc-vgw dc-vif

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
offset	No	String	Specifies the 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 value returned in the response body for the previous query. 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.
limit	No	String	Specifies the number of records to be queried. This parameter is not available when action is set to count. If action is set to filter, the default value is 1000. The maximum value is 1000, and the minimum value is 1. The value cannot be a negative number.
action	Yes	String	Specifies the operation to perform, which can only be filter (filtering) or count (querying the total number). filter indicates pagination query. count indicates that the total number of query results meeting the search criteria will be returned. Returning other fields is not allowed. Enumeration values: filter count
matches	No	Array of Match objects	Specifies the search criteria. key is the field to match, for example, resource_name. value indicates the value to be matched. 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 (case insensitive) is used by default. If value is an empty string, exact match is used. If key is resource_id, exact match is used. Currently, only resource_name is supported.
not_tags	No	Array of Tags objects	Specifies tags that are not included. Each tag 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. Resources not identified by different keys are in AND relationship, and values in one tag are in OR relationship. If no filtering condition is specified, full data is returned.
tags	No	Array of Tags objects	Specifies tags that are included. Each tag 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. Resources identified by different keys are in AND relationship, and values in one tag are in OR relationship. If no tag filtering criteria is specified, full data is returned.
tags_any	No	Array of Tags objects	Specifies any tag that is included. Each tag 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. Resources identified by different keys are in OR relationship, and values in one tag are in OR relationship. If no filtering condition is specified, full data is returned.
not_tags_any	No	Array of Tags objects	Specifies any tag that is not included. Each tag 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. Resources not identified by different keys are in OR relationship, and values in one tag are in OR relationship. If no filtering condition is specified, full data is returned.
sys_tags	No	Array of Tags objects	Only users with the op_service permission can use this field to filter resources. Only one tag structure is contained when this API is called by Tag Management Service (TMS). key is _sys_enterprise_project_id, and value is the enterprise project ID list. When TMS invokes this API, a key can have only one value. 0 indicates the default enterprise project. sys_tags and tenant tag filtering conditions (without_any_tag, tags, tags_any, not_tags, and not_tags_any) cannot be used at the same time.

**Table 3** Match
Parameter	Mandatory	Type	Description
key	Yes	String	Specifies the tag key. The value can be dc-directconnect, dc-vgw, or dc-vif.
value	Yes	String	Specifies the tag value. Each value can contain a maximum of 255 Unicode characters.

**Table 4** Tags
Parameter	Mandatory	Type	Description
key	Yes	String	Specifies the tag key. Each tag key can contain a maximum of 127 Unicode characters. key must be specified.
values	Yes	Array of strings	Specifies the list of tag values. Each value can contain a maximum of 255 Unicode characters.

Response Parameters

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
resources	Array of Resource objects	Specifies the resource list.
total_count	Integer	Specifies the total number of records.
request_id	String	Specifies the request ID.

**Table 6** Resource
Parameter	Type	Description
resource_detail	Object	Specifies the resource details.
resource_id	String	Specifies the resource ID.
resource_name	String	Specifies the resource name. This parameter is an empty string by default if there is no resource name.
tags	Array of Tag objects	Specifies the list of queried tags. If no tag is matched, an empty array is returned.
sys_tags	Array of Tag objects	Specifies the list of queried tags. If no tag is matched, an empty array is returned.

**Table 7** Tag
Parameter	Type	Description
key	String	Specifies the tag key. The key can contain a maximum of 36 Unicode characters, including letters, digits, hyphens (-), and underscores (_). Minimum: 0 Maximum: 36
value	String	Specifies the tag value. The value can contain a maximum of 43 Unicode characters, including letters, digits, hyphens (-), underscores (_), and periods (.). Minimum: 0 Maximum: 43

Example Requests

Querying resources (action set to filter)

https://{endpoint}/v3/cfa563efb77d4b6d9960781d82530fd8/dc-vgw/resource-instances/action

{
  "offset" : "10",
  "limit" : "10",
  "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" ]
  } ]
}

Querying the total number of resources (action set to count)

https://{endpoint}/v3/cfa563efb77d4b6d9960781d82530fd8/dc-vgw/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" ]
  } ],
  "sys_tags" : [ {
    "key" : "_sys_enterprise_project_id",
    "values" : [ "5aa119a8-d25b-45a7-8d1b-88e127885635" ]
  } ],
  "matches" : [ {
    "key" : "resource_name",
    "value" : "resource1"
  } ]
}

Example Responses

Status code: 200

{
  "resources" : [ ],
  "total_count" : 0,
  "request_id" : "9a4f4dfc4fb2fc101e65bba07d908535"
}

Status Codes

Status Code	Description
200	OK

Error Codes

See Error Codes.

Parent topic: Tag management

Previous topic: Deleting a Resource Tag

Next topic: Quota Management

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel