A tag is an arbitrary key or a key-value pair that you can create and assign to your 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 several of your instances. To search for specific tags and to find instances that are assigned specific tags, you can use filtering expressions.
For example, on the home page of the web console, 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%'
in the Search field.
tagFilter=expression
query parameter to the REST endpoint URL.
GET paas/api/v1.1/tags/{identity_domain}/tags?tagFilter={expression}
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.
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.
'env' 'env':'dev'
You can include keys or key:value pairs in a tag-filtering expression.
Sample Expression | Description | Sample Search Result |
---|---|---|
|
Finds the tags with the key |
The following tags, or the instances that are assigned any of these tags:
env:dev env:qa |
|
Finds the tag with the key |
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 |
---|---|---|
|
Finds the tags with the key |
The following tags, or the instances that are assigned any of these tags:
env:dev env:dev1 |
|
Finds the tags with the key |
The following tags, or the instances that are assigned any of these tags: env:dev1 env:dev2 |
'
), 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 |
---|---|---|
|
Finds the tags with the key |
The following tags, or the instances that are assigned any of these tags:
env:dev_1 env:dev_admin |
Sample Expression | Description | Sample Search Result |
---|---|---|
|
Finds the tags with the key |
The following tags, or the instances that are assigned any of these tags:
env:dev owner:admin |
|
Finds the instances that are assigned the tags 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 |
|
Finds the tags that have a key other than 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 |
|
Finds the tags that have the key |
The following tags, or the instances that are assigned any of these tags:
env:dev owner:admin |