Find Tags and Instances Using Search Expressions
A tag is an arbitrary key or a key-value pair that you can create and assign to your Oracle SOA Cloud Service instances. You can use tags to organize and categorize your instances, and to search for them. Over time, you might create dozens of tags, and you might assign one or more tags to your instances. To search for specific tags and to find instances that are assigned specific tags, you can use filtering expressions.
Search for Instances with Tags
From the Instances page of the web console, select Tags, and then enter a search expression in the Search field.
For example, you can search for the instances that are assigned a tag with the key env
and any value starting with dev
(example: env:dev1
, env:dev2
), by entering the search expression 'env':'dev%'
.
tagFilter=expression
query parameter to the REST endpoint URL.
- To find specific tags:
GET paas/api/v1.1/tags/{identity_domain}/tags?tagFilter={expression}
- To get a list of instances that are assigned specific tags:
GET paas/api/v1.1/instancemgmt/{identity_domain}/instances?tagFilter={expression}
Syntax and Rules for Building Tag-Search Expressions
-
When using cURL to send tag-search API requests, enclose the URL in double quotation marks.
Example:curl -s -u username:password -H "X-ID-TENANT-NAME:acme" "restEndpointURL/paas/api/v1.1/instancemgmt/acme/instances?tagFilter='env'"
This request returns all the tags that have the key
env
. -
Enclose each key and each value in single quotation marks. And use a colon (
:
) to indicate a key:value pair.Examples:'env' 'env':'dev'
-
You can include keys or key:value pairs in a tag-filtering expression.
Sample Expression Description Sample Search Result 'env'
Finds the tags with the key
env
, or the instances that are assigned the tags with that key.The following tags, or the instances that are assigned any of these tags:env:dev env:qa
'env':'dev'
Finds the tag with the key
env
and the valuedev
, or the instances that are assigned that tag.The following tag, or the instances that are assigned this tagenv:dev
-
You can build a tag-search expression by using actual keys and key values, or by using the following wildcard characters.
%
(percent sign): Matches any number of characters._
(underscore): Matches one character.Sample Expression Description Sample Search Result 'env':'dev%'
Finds the tags with the key
env
and a value starting withdev
, or the instances that are assigned such tags.Note: When you use
curl
or any command-line tool to send tag-search REST API requests, encode the percent sign as%25
.The following tags, or the instances that are assigned any of these tags:env:dev env:dev1
'env':'dev_'
Finds the tags with the key
env
and the valuedevX
where X can be any one character, or finds the instances that are assigned such tags.The following tags, or the instances that are assigned any of these tags:
env:dev1 env:dev2
-
To use a single quotation mark (
'
), the percent sign (%
), or the underscore (_
) as a literal character in a search expression, escape the character by prefixing a backslash (\
).Sample Expression Description Sample Search Result 'env':'dev\_%'
Finds the tags with the key
env
and a value starting withdev_
, or the instances that are assigned such tags.The following tags, or the instances that are assigned any of these tags:env:dev_1 env:dev_admin
-
You can use the Boolean operators AND, OR, and NOT in your search expressions:
Sample Expression Description Sample Search Result 'env' OR 'owner'
Finds the tags with the key
env
or the keyowner
, or the instances that are assigned either of those keys.The following tags, or the instances that are assigned any of these tags:env:dev owner:admin
'env' AND 'owner'
Finds the instances that are assigned the tags
env
andowner
.Note: This expression won’t return any results when used to search for tags, because a tag can have only one key.
The instances that are assigned all of the following tags:env:dev owner:admin
NOT 'env’
Finds the tags that have a key other than
env
, or the instances that are assigned such tags.Note: Untagged instances as well will satisfy this search expression.
The following tags, or the instances that are assigned any of these tags or no tags:owner:admin department
('env' OR 'owner') AND NOT 'department'
Finds the tags that have the key
env
or the keyowner
but not the keydepartment
, or the instances that are assigned such tags.The following tags, or the instances that are assigned any of these tags:env:dev owner:admin