# Using Tags to Filter Resources (Streams)

#### Function

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

#### 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. The token can be obtained by calling the IAM API (value of X-Subject-Token in the response header).

Table 3 Request body parameters
Parameter | Mandatory | Type | Description
--- | --- | --- | ---

action

Yes

String

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

- filter: queries data on multiple pages.

- count: queries the total number of data records. The total number of data records is returned based on the search criteria.

Enumeration values:

- filter

- count

limit | No | String | Number of queried records. This parameter is not displayed if action is set to count. The default value is 1000 if action is set to filter. The value must be an integer ranging from 1 to 1000. Default: 1000

offset

No

String

Index position. The query starts from the next data record indexed by this parameter. When querying data on the first page, you do not need to pass this parameter. When querying data on subsequent pages, set this parameter to the value in the response body returned by querying data of the previous page. This parameter is not displayed when action is set to count. If action is set to filter, the value defaults to 0. The value must be a positive integer.

tags | No | Array of Tags objects | The return result contains resources corresponding to all tags 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 set to 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 set to an empty string. Keys and the values of a key must be unique.
not_tags | No | Array of Tags objects | The return result does not contain resources corresponding to all tags 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 set to an empty string. Keys and the values of a 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 set to an empty string. Keys must be unique and values of a key must be unique.
matches | No | String | Search criteria. The tag key is the field to match. Currently, only resource_name is supported. value indicates the matched value. This field is a fixed dictionary value.

Table 4 Tags
Parameter | Mandatory | Type | Description
--- | --- | --- | ---

key

No

String

Key.

- This field cannot be left blank.

- The key value of a resource must be unique.

- Character set: A-Z, a-z, 0-9, '-', '_', and Unicode characters (\u4E00-\u9FFF).

Maximum: 36

values | No | Array of strings | Tag value list. If values are null, it indicates any_value. The relationship between values is OR.

#### Response Parameters

Status code: 200

Table 5 Response body parameters
Parameter | Type | Description
--- | --- | ---

action

String

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

- filter: queries data on multiple pages.

- count: queries the total number of data records. The total number of data records is returned based on the search criteria.

Enumeration values:

- filter

- count

limit | String | Number of queried records. This parameter is not displayed if action is set to count. The default value is 1000 if action is set to filter. The value must be an integer ranging from 1 to 1000. Default: 1000

offset

String

Index position. The query starts from the next data record indexed by this parameter. When querying data on the first page, you do not need to pass this parameter. When querying data on subsequent pages, set this parameter to the value in the response body returned by querying data of the previous page. This parameter is not displayed when action is set to count. If action is set to filter, the value defaults to 0. The value must be a positive integer.

tags | Array of Tags objects | The return result contains resources corresponding to all tags 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 set to 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 set to an empty string. Keys and the values of a key must be unique.
not_tags | Array of Tags objects | The return result does not contain resources corresponding to all tags 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 set to an empty string. Keys and the values of a 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 set to an empty string. Keys must be unique and values of a key must be unique.
matches | String | Search criteria. The tag key is the field to match. Currently, only resource_name is supported. value indicates the matched value. This field is a fixed dictionary value.

Table 6 Tags
Parameter | Type | Description
--- | --- | ---

key

String

Key.

- This field cannot be left blank.

- The key value of a resource must be unique.

- Character set: A-Z, a-z, 0-9, '-', '_', and Unicode characters (\u4E00-\u9FFF).

Maximum: 36

values | Array of strings | Tag value list. If values are null, it indicates any_value. The relationship between values is OR.

#### 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.

Parent topic: Tag Management