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