Updated on 2024-07-25 GMT+08:00

Querying Resources by Tag

Function

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

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

OK

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

Status Codes

Status Code

Description

200

OK

Error Codes

See Error Codes.