Querying Topics by Tag

Description

• API name

  GetResourceInstances

• Function

  Query topics 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 Only smn_topic (topic) is supported.

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 20 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 20 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 20 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 20 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 20 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 20 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 20 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 20 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	The 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 you query 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 operation 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 can contain up to 36 Unicode characters and cannot be left blank.
  values	Yes	String list	Value list	Each value can contain up to 43 Unicode characters. If a value starts with an asterisk (*), the 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. Values are in the OR relationship.

• Example request

  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": "resource"
       }
      ]
    }

Response

• Parameter description

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

  Table 2 Resource structure

  Parameter	Type	Description
  resource_id	String	Resource ID
  resource_detail	Object	Resource details Resource object used for extension. resource_detail 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	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	String	Resource name

  Table 3 Resource_tag structure

  Parameter	Type	Description	Constraint
  key	String	Tag key	A key can contain up to 36 Unicode characters, including only digits, letters, hyphens (-), and underscores (_). A key cannot be left blank, be an empty string, or start or end with a space.
  value	String	Tag value	A value can contain up to 43 Unicode characters, including only digits, letters, hyphens (-), and underscores (_). A value can be an empty string, but it cannot start or end with a space.

• Example response

  Response body when action is set to filter

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

  Response body when action is set to count

  {
         "total_count": 1000
  }

Returned Value

See Returned Value.

Error Codes

See Error Codes.