Introduction

The search service is a global and shared resource properties repository that is integrated in the IBM Cloud® platform. It's used for storing and searching cloud resource attributes. It categorizes and classifies resources. A resource is controlled and owned by resource providers within the IBM Cloud platform, such as IBM Cloud Kubernetes Service, or Resource Controller. Resources are uniquely identified by a Cloud Resource Naming identifier (CRN). The properties of a resource include tags and system properties. Both properties are defined within an IBM Cloud billing account, and span across many regions.

The search service can list, query, and retrieve information about IBM Cloud resources in the user IBM Cloud billing account, including IAM Access Groups (AG) and IAM Service IDs. It cannot retrieve resources that are:

Users
IAM API keys
IAM Trusted profiles
Context Based Restrictions (CBR) Zones and Rules
Support Cases
Billing data
Cost estimations.

The search service cannot retrieve Deployable Architectures (DA) and related information, documentation, or release notes.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

To filter search results, you can apply query strings following the Lucene query syntax:

Basic Term: A single word is a term, and it searches for that word in all the resource attributes.
Example: database searches for the word database in all the resource attributes.
Phrase: A group of words surrounded by double quotes (" ") forms a phrase query, and it searches for all the words in the same order.
Example: "My resource" searches for the exact phrase in all the resource attributes.
Field: Specify a resource attribute for a term by prefixing it with the attribute name followed by a colon (:).
Example: name:my-resource searches for resources whose attribute name is my-resource.
Boolean Operators:
AND (finds resources containing both terms),
OR (finds resources containing either term),
NOT (excludes resources containing the term).
Boolean operators must be capitalized.
Example: my-resource AND database searches for words my-resource and database in all the resource attributes.
Wildcards: * matches any character sequence (including none), and ? matches a single character.
Example: my-res* finds my-resource, my-resources, etc.
Special characters: Enclose in double-quotes terms containing special characters: + & | ! ( ) { } [ ] ^ ~ : \ / as they are reserved in Lucene query syntax (e.g. CRNs, type-4 GUIDs). Example: name:"Fancy!Resource&Co.".
Ranges: Search for terms within a range. Can be numeric or alphabetical.
Inclusive range: [start TO end], exclusive range: {start TO end}.
Example: creation_date:[2021-01-01 TO 2021-12-31] finds resources whose creation_date is in the range.
Grouping: Group queries with parentheses (()) to control operator precedence.
Example: (database OR containers-kubernetes) AND name:my-resource find database or container-kubernetes resources named my-resource.

The most commonly used resource attributes (or fields) that you can query and retrieve are:

access_tags: The list of access management tags attached to the resource.
account_id: The billing account ID of the resource.
catalog_tags: The list of tags determining the resource categories.
creation_date: The date on which the resource was created in ISO format "YYYY-MM-DDTHH:mm:ss.SSSZ".
crn: The Cloud Resource Name in the format: "crn:version:cname:ctype:service-name:location:scope:service-instance:resource-type:resource".
modification_date: The date on which the resource was last updated in ISO format "YYYY-MM-DDTHH:mm:ss.SSSZ".
name: The user-provided resource name.
region: The IBM Cloud location of the resource.
resource_group_id: The unique identifier of the resource group into which the resource is provisioned.
service_instance: The unique identifier of the service instance.
resource_id: The unique identifier of the resource provisioned by a service instance.
service_name: The name of the service as it appears in the Name column of the output of ibmcloud catalog service-marketplace.
service_tags: The list of service tags attached to the resource.
tags: The list of user tags attached to the resource.
type: The type of the resource.

Using the /resources/search API you can retrieve or list IBM Cloud resources and services using a variety of filters.
Only resources that belong to the account ID and that are accessible by the client are returned.

Hereafter only some of the use cases that you can accomplish by building the right Lucene query.

To check if your backup policies are correctly configured you can use the query:
service_name:is AND type:backup-policy
which returns the backup policies that you are entitled to view.

You can verify when a PostgreSQL database named mydb was created and updated by using the query service_name:compose-for-postgresql AND name:mydb and check the creation_date and modification_date fields.

You can list resources whose name starts with either climate_change or global_warming by using the query name:(climate_change* OR global_warming*).

You can retrieve resources by date. For example, those updated between 2020 and 2022 using the query modification_date:[2020 TO 2022].
You can use the notation [now-X TO now] for time relative queries:

For "last X years" use the range [now-Xy TO now]
For "last X months" use the range [now-XM TO now]
For "last X weeks" use the range [now-Xw TO now]
For "last X days" use the range [now-Xd TO now]
For "last X hours" use the range [now-Xh TO now]
For "last X minutes" use the range [now-Xm TO now]
For "last X seconds" use the range [now-Xs TO now]

For example, the query creation_date:[now-1w TO now] returns the resources created in the last week.

Another interesting set of use cases is querying resources in your account by category: e.g., compute, network, storage, databases, security, devops.
Suppose you want to know if there are databases in your account. You can list them using the query:
catalog_tags:databases.

Similarly, if you want to know if there are specific services provisioned in your account you can use a query like:
service_name:(databases-for-elasticsearch OR cloudantnosqldb)
which returns instances of Elasticsearch or Cloudant databases that you are entitled to view.

Sometimes, you need to obtain the CRN of a resource given its name, or vice versa: the name of a resource given its CRN.
To do so you can use the queries:
name:your-resource-name and crn:”your-resource-crn” respectively.
You can use the service_instance:your-service-instance-id or resource_id:your-resource-id as an alternative to the CRN to retrieve the name of a resource.

Finally, you can filter resources by tags.
Suppose that you are interested in resources tagged as dev, test, and production.
You can use the queries:
tags:dev, tags:test, and tags:production respectively.

What if you are interested in resources provisioned with an enterprise project configuration?
All resources provisioned with a project do have service tags, which can be used to get them. For example, the query:
service_tags:(”project::config_id:1e3bf974-0f34-4a96-960b-15823558f952” AND “project::project_id:efd46015-1902-4465-99a4-a0e12fba5759”)
returns all the resources provisioned with the specified project_id and config_id.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>global-search</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:global-search:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/globalsearchv2"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/globalsearchv2

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Endpoint URLs

The Global Search API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://api.global-search-tagging.cloud.ibm.com

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL for VPC infrastructure (Dallas, Washington, Sydney, London, Frankfurt, Madrid, San Paulo, Tokyo, Osaka, Toronto, Montreal, Chennai, Mumbai regions): https://api.private.global-search-tagging.cloud.ibm.com
Private endpoint URL for classic infrastructure:
- Dallas https://api.private.us-south.global-search-tagging.cloud.ibm.com
- Washington https://api.private.us-east.global-search-tagging.cloud.ibm.com
- Sydney https://api.private.au-syd.global-search-tagging.cloud.ibm.com
- London https://api.private.eu-gb.global-search-tagging.cloud.ibm.com
- Frankfurt https://api.private.eu-de.global-search-tagging.cloud.ibm.com

Example API request

curl --request POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer <IAM token>" \
--data "{\"query\":\"string\"}" \
--url "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=string&limit=10&timeout=0&sort=string"

Replace <IAM token> in this example with the value for your particular API call.

Authentication

Authorization to the Global Search API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, --header "Authorization: Bearer <TOKEN>".

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/globalsearchv2"
}
...
serviceClientOptions := &globalsearchv2.GlobalSearchV2Options{}
serviceClient, err := globalsearchv2.NewGlobalSearchV2UsingExternalConfig(serviceClientOptions)

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.global_search.v2.GlobalSearch;
...
GlobalSearch serviceClient = GlobalSearch.newInstance();

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>

Example of constructing the service client

const GlobalSearchV2 = require('@ibm-cloud/platform-services/global-search/v2');
...
const serviceClient = GlobalSearchV2.newInstance({});

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import GlobalSearchV2
...
global_search_service = GlobalSearchV2.new_instance()

Error handling

Global Search uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response always indicates success. A 400 type response is a failure, and a 500 type response is an internal system error.

| HTTP Error Code | Description | Recovery | |-----------------|-------------|----------| | 200 | Success | The request was successful. | | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized to access '{namespace}'. | | 404 | Not Found | The requested resource could not be found. | | 409 | Conflict | The entity is already in the requested state. | | 410 | Gone | The resource is valid but has been removed already in a previous call | | 500 | Internal Server Error | offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |

Global Search | IBM Cloud API Docs