# Querying Resources by Tag

#### Description

- API name

  GetResourceInstances

- Function

  Query SMN resources by tag.

#### URI

- URI format

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

- Parameter description

  Parameter | Mandatory | Type | Description
  --- | --- | --- | ---
  project_id | Yes | String | Project ID See Obtaining a Project ID.
  resource_type | Yes | String | Resource type The value can be the following: smn_topic: topic

#### Request

- Parameter description

  Parameter | Mandatory | Type | Description
  --- | --- | --- | ---

  tags

  No

  Tags structure array

  Includes specified tags. For details, see Table 1.

  NOTE:

  The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in AND relationship.

  tags_any

  No

  Tags structure array

  Includes any of the specified tags. For details, see Table 1.

  NOTE:

  The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in OR relationship.

  not_tags

  No

  Tags structure array

  Excludes specified tags. For details, see Table 1.

  NOTE:

  The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in NAND relationship.

  not_tags_any

  No

  Tags structure array

  Excludes any of the specified tags. For details, see Table 1.

  NOTE:

  The structure body is mandatory. A maximum of 10 tag keys are allowed in each query operation. The tag key cannot be left blank or set to the empty string. Each tag key can have up to 10 tag values. Each tag key and tag values of one key must be unique. Resources identified by different keys are in NOR relationship.

  limit

  No

  String

  Maximum number of resources to be queried
  - If action is set to count, this parameter does not take effect.
  - If action is set to filter, this parameter takes effect. Its value ranges from 1 to 1000 (default).

  offset

  No

  String

  Start location of pagination query. The query starts from the next resource of the specified location. You do not need to specify this parameter when querying resources on the first page. When you query resources on subsequent pages, set this parameter to the location returned in the response body for the previous query.
  - If action is set to count, this parameter does not take effect.
  - If action is set to filter, this parameter takes effect. Its value can be 0 (default) or a positive integer.

  action | Yes | String | Operation to be performed. The value can be filter or count (case-sensitive). filter: queries resources in pages based on filter conditions. count: queries the total number of resources meeting filter conditions.
  matches | No | Match condition structure array | Key-value pair to be matched The key can only be resource_name. The value will be exactly matched.

  Table 1 Tags structure
  Parameter | Mandatory | Type | Description | Constraint
  --- | --- | --- | --- | ---
  key | Yes | String | Tag key | A key contains 127 Unicode characters and cannot be blank.
  values | Yes | String list | Value list | Each value contains a maximum of 255 Unicode characters. If the value starts with an asterisk (*), the character string following the asterisk is fuzzy-matched. The values field cannot be missing, but can be an empty list. If it is empty, any value will be matched. The values are in OR relationship.

- Request example

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

  - Request body when action is set to filter

        {
          "offset": "100",
          "limit": "100",
          "action": "filter",
          "matches":[
               {
                "key": "resource_name",
                "value": "resource1"
               }
           ],
           "not_tags": [
               {
                "key": "key1",
                "values": ["*value1","value2"]
               },
               {
                "key": "key2",
                "values": ["*value21","value22"]
               }
           ],
           "tags": [
            {
              "key": "key1",
              "values": ["*value1","value2"]
              }
             ],
           "tags_any": [
            {
              "key": "key1",
              "values": ["value1", "value2"]
            }
          ],
           "not_tags_any": [
            {
              "key": "key1",
              "values": ["value1", "value2"]
            }
          ]
        }

  - Request body when action is set to count

        {
          "action": "count",
          "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"]
            }
           ],
           "matches":[
           {
                "key": "resource_name",
                "value": "resouurce"
           }
          ]
        }

#### Response

- Parameter description

  Parameter | Mandatory | Type | Description
  --- | --- | --- | ---
  resources | Yes | Resource structure array | For details, see Table 2.
  total_count | Yes | Integer | Total number of resources

  Table 2 Resource structure
  Parameter | Mandatory | Type | Description
  --- | --- | --- | ---
  resource_id | Yes | String | Resource ID
  resource_detail | Yes | Object | Resource details. Resource object used for extension. The value is left blank by default. For topic resources, the value of this field is {"topic_urn":"${TopicUrn}","display_name":"display name"}. For other resources, the value is null.
  tags | Yes | Resource_tag structure array | List of queried tags. If no tag is matched, an empty array is returned. For details, see Table 3.
  resource_name | Yes | String | Resource name

  Table 3 Resource_tag structure
  Parameter | Mandatory | Type | Description | Constraint
  --- | --- | --- | --- | ---
  key | Yes | String | Tag key | The key contains 36 Unicode characters at most and cannot be blank or an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.
  value | Yes | String | Tag value | Each value contains 43 Unicode characters at most and can be an empty string. It can contain only digits, letters, hyphens (-), and underscores (_) and must not start or end with a space.

- Response example

  Response body when action is set to filter

      {
            "resources": [
               {
                  "resource_detail": {
                       "topic_urn":"urn:smn:regionId:f96188c7ccaf4ffba0c9aa149ab2bd57:resouece1",
                       "display_name":"testtest"
                   },
                  "resource_id": "cffe4fc4c9a54219b60dbaf7b586e132",
                  "resource_name": "resouece1",
                  "tags": [
                      {
                         "key": "key1",
                         "value": "value1"
                      }
                   ]
               }
             ],
            "total_count": 1000
      }

  Response body when action is set to count

      {
             "total_count": 1000
      }

#### Returned Value

See section Returned Value.

#### Error Code

See section Error Code.

Parent topic: Resource Tag Operations