Using Tags to Filter Resources (Streams)

Function

This API is used to filter resources (streams) by tag.

Calling Method

For details, see Calling APIs.

URI

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

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token.

It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

action

Yes

String

Operation to be performed. The value can be filter or count.

  • filter: pagination query

  • count: total number of returned records that meet the query criteria.

Enumeration values:

  • filter

  • count

limit

No

String

Number of records to be queried. This parameter is not available when action is set to count. The default value is 1000 when action is set to filter. The maximum value is 1000, and the minimum value is 1. The value cannot be a negative number.

Default: 1000

offset

No

String

Index position. The query starts from the next data record indexed by this parameter. This parameter is not required when you query data on the first page. The value in the response returned for querying data on the previous page will be included in this parameter for querying data 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 number, and the default value is 0. The value cannot be a negative number.

tags

No

Array of Tags objects

The return result contains resources corresponding to any tag in this parameter. This parameter 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 an empty string.

tags_any

No

Array of Tags objects

The return result contains resources corresponding to any tag in this parameter. This parameter 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 an empty string. Each tag key must be unique, and each value of the same key must be unique.

not_tags

No

Array of Tags objects

The return result does not contain resources corresponding to any tag in this parameter. This parameter 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 an empty string. Each tag key must be unique, and each value of the same key must be unique.

not_tags_any

No

Array of Tags objects

The return result does not contain resources corresponding to any tag in this parameter. This parameter 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 an empty string. Each tag key must be unique, and each value of the same key must be unique.

matches

No

String

Search criteria. The tag key is the field to match. Currently, only resource_name is supported. The tag value indicates the value to be matched. This field is a fixed dictionary value.

Table 4 Tags

Parameter

Mandatory

Type

Description

key

No

String

Tag key.

  • It cannot be left blank.

  • It must be unique for each resource.

  • It can contain uppercase and lowercase letters, digits, hyphens (-), underscores (_), and Unicode characters (\u4E00-\u9FFF).

Maximum: 36

values

No

Array of strings

Tag values.

If the value list is empty, this parameter indicates any_value. The values are in the OR relationship.

Response Parameters

Status code: 200

Table 5 Response body parameters

Parameter

Type

Description

action

String

Operation to be performed. The value can be filter or count.

  • filter: pagination query

  • count: total number of returned records that meet the query criteria.

Enumeration values:

  • filter

  • count

limit

String

Number of records to be queried. This parameter is not available when action is set to count. The default value is 1000 when action is set to filter. The maximum value is 1000, and the minimum value is 1. The value cannot be a negative number.

Default: 1000

offset

String

Index position. The query starts from the next data record indexed by this parameter. This parameter is not required when you query data on the first page. The value in the response returned for querying data on the previous page will be included in this parameter for querying data 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 number, and the default value is 0. The value cannot be a negative number.

tags

Array of Tags objects

The return result contains resources corresponding to any tag in this parameter. This parameter 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 an empty string.

tags_any

Array of Tags objects

The return result contains resources corresponding to any tag in this parameter. This parameter 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 an empty string. Each tag key must be unique, and each value of the same key must be unique.

not_tags

Array of Tags objects

The return result does not contain resources corresponding to any tag in this parameter. This parameter 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 an empty string. Each tag key must be unique, and each value of the same key must be unique.

not_tags_any

Array of Tags objects

The return result does not contain resources corresponding to any tag in this parameter. This parameter 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 an empty string. Each tag key must be unique, and each value of the same key must be unique.

matches

String

Search criteria. The tag key is the field to match. Currently, only resource_name is supported. The tag value indicates the value to be matched. This field is a fixed dictionary value.

Table 6 Tags

Parameter

Type

Description

key

String

Tag key.

  • It cannot be left blank.

  • It must be unique for each resource.

  • It can contain uppercase and lowercase letters, digits, hyphens (-), underscores (_), and Unicode characters (\u4E00-\u9FFF).

Maximum: 36

values

Array of strings

Tag values.

If the value list is empty, this parameter indicates any_value. The values are in the OR relationship.

Example Requests

  • Resource (stream) filtering by tag and record querying

    POST https://{Endpoint}/v2/{project_id}/stream/resource_instances/action
    
    {
      "action" : "count",
      "tags" : [ {
        "key" : "key1",
        "values" : [ "value1", "value2" ]
      }, {
        "key" : "key2",
        "values" : [ "value1", "value2" ]
      } ],
      "matches" : [ {
        "key" : "resource_name",
        "value" : "resource1"
      } ]
    }
    
  • Resource (stream) filtering by tag and querying by page

    POST https://{Endpoint}/v2/{project_id}/stream/resource_instances/action
    
    {
      "offset" : "0",
      "limit" : "100",
      "action" : "filter",
      "matches" : [ {
        "key" : "resource_name",
        "value" : "resource1"
      } ],
      "tags" : [ {
        "key" : "key1",
        "values" : [ "*value1", "value2" ]
      } ]
    }
    

Example Responses

Status code: 200

Request body for filtering resources (streams) by tag

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

Status Codes

Status Code

Description

200

Request body for filtering resources (streams) by tag

Error Codes

See Error Codes.