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

Screenshot highlighting the Tag Search field on the Instances page of the Oracle SOA Cloud Service web console

Similarly, when you use the REST API to find tags or to find instances that are assigned specific tags, you can filter the results by appending the optional 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 value `dev`, or the instances that are assigned that tag.	The following tag, or the instances that are assigned this tag `env: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

Sample Expression	Description	Sample Search Result
`'env':'dev%'`	Finds the tags with the key `env` and a value starting with `dev`, 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 value `devX` 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`

'env':'dev%'

Finds the tags with the key env and a value starting with dev, 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 value devX 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 with `dev_`, 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 key `owner`, 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` and `owner`. 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 key `owner` but not the key `department`, 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`