Global Search - IBM Cloud API Docs

Introduction

Last updated: 2021-05-19

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

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.

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-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: https://api.private.global-search-tagging.cloud.ibm.com
Private endpoint URL (Dallas) for classic infrastructure: https://api.private.us-south.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.test.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-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
...
service_client = GlobalSearchV2.new_instance()

Error handling

The resource manager 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.

Find resources in the internal search platform for a specific account ID. You can optionally apply query strings. To filter results, you can insert a string using the Lucene syntax and the query string is parsed into a series of terms and operators. A term can be a single word or a phrase, in which case the search is performed for all the words, in the same order. To filter for a specific value regardless of the property that contains it, use an asterisk as the key name. Results are filtered by the account ID and IAM subsystem. Only resources that belong to the account ID and that are accessible by the client are returned. The usage of this API is deprecated for cases when the provider is not specified or provider=ghost. /v3/resources/search replaces this API for the deprecated cases.

POST /v2/resources/search

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

global-search-tagging.resource.read

Request

Custom Headers

transaction-id
string
An aplhanumeric string that can be used to trace a request across services. If not specified it will be automatically generated with the prefix "gst-"

Query Parameters

account_id
string
The account ID to filter resources.

Possible values: Value must match regular expression ^[a-fA-F0-9-]+$|^[*]{1}$
limit
integer
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
Default: 10
timeout
integer
A search timeout, bounding the search request to be executed within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
offset
integer
The offset is the index of the item you want to start returning data from. Default is 0.

Default: 0
sort
string
Comma separated properties name used for sorting
provider
string
Search providers. Supported values are ghost and ims. If not specified, the defaults to ghost. Specify a single provider.

Allowable values: [ghost,ims]
Default: ghost

Request Body

Required*

SearchBody

It contains the query filters, the list of fields to be returned, and the search token (initally set to null or undefined)

Response

Response Body

SearchResults

The results of the requested search.

Status Code

200
A result paging with the list of resources matching the provided filters.
400
Bad Request
401
Unauthorized / Wrong auth token type IAM / Auth token not valid
403
Unauthorized operation
500
Internal Server Error / IAM not initialized / Malformed IAM credentials
502
Search IAM error
default
System problem or unexpected error

Example responses

Status 200

{
  "items": {
    "...": "STRING",
    "crn": "STRING"
  },
  "more_data": "BOOLEAN",
  "token": "STRING"
}

Status 400

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 401

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 403

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 500

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 502

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status default

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Find Cloud Foundry resources, IAM-enabled resources, or storage and network resources running on classic infrastructure in a specific account ID. You can apply query strings if necessary.

To filter results, you can insert a string using the Lucene syntax and the query string is parsed into a series of terms and operators. A term can be a single word or a phrase, in which case the search is performed for all the words, in the same order. To filter for a specific value regardless of the property that contains it, type the search term without specifying a field. Only resources that belong to the account ID and that are accessible by the client are returned.

You must use /v3/resources/search when you need to fetch more than 10000 resource items. The /v2/resources/search prohibits paginating through such a big number. On the first call, the operation returns a live cursor on the data that you must use on all the subsequent calls to get the next batch of results until you get the empty result set. By default, the fields returned for every resource are "crn", "name", "family", "type", and "account_id". You can specify the subset of the fields you want in your request.

Find cloud foundry resources, resource controller-enabled resources, or storage and network resources running on classic infrastructure in a specific account ID. You can apply query strings if necessary. To filter results, you can insert a string using the Lucene syntax and the query string is parsed into a series of terms and operators. A term can be a single word or a phrase, in which case the search is performed for all the words, in the same order. To filter for a specific value regardless of the property that contains it, use an asterisk as the key name. Only resources that belong to the account ID and that are accessible by the client are returned. You must use this operation when you need to fetch more than 10000 resource items. The /v2/resources/search prohibits paginating through such a big number. On the first call, the operation returns a live cursor on the data that you must use on all the subsequent calls to get the next batch of results until you get the empty result set. By default, the fields returned for every resources are: "crn", "name", "family", "type", "account_id". You can specify the subset of the fields you want in your request.

POST /v3/resources/search

(globalSearch *GlobalSearchV2) Search(searchOptions *SearchOptions) (result *ScanResult, response *core.DetailedResponse, err error)

(globalSearch *GlobalSearchV2) SearchWithContext(ctx context.Context, searchOptions *SearchOptions) (result *ScanResult, response *core.DetailedResponse, err error)

ServiceCall<ScanResult> search(SearchOptions searchOptions)

search(params)

search(self,
        *,
        query: str = None,
        fields: List[str] = None,
        search_cursor: str = None,
        transaction_id: str = None,
        account_id: str = None,
        limit: int = None,
        timeout: int = None,
        sort: List[str] = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

global-search-tagging.resource.read

Request

Instantiate the SearchOptions struct and set the fields to provide parameter values for the Search method.

Use the SearchOptions.Builder to create a SearchOptions object that contains the parameter values for the search method.

Custom Headers

transaction-id
string
An aplhanumeric string that can be used to trace a request across services. If not specified it will be automatically generated with the prefix "gst-"

Query Parameters

account_id
string
The account ID to filter resources.

Possible values: Value must match regular expression ^[a-fA-F0-9-]+$|^[*]{1}$
limit
integer
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
Default: 10
timeout
integer
A search timeout, bounding the search request to be executed within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
sort
string[]
Comma separated properties names used for sorting

Possible values: Value must match regular expression ^[+-]?\w+[\w\-\.]*$

Request Body

Required*

ScanBody

It contains the query filters on the first operation call, or the search_cursor on next calls. On subsequent calls, set the search_cursor to the value returned by the previous call. After the first, you must set only the search_cursor. Any other parameter but the search_cursor will be ignored. The search_cursor encodes all the information needed to get the next batch of limit data.

Examples:

View

parameter

WithContext method only

SearchOptions

The Search options.

SearchOptions

The search options.

parameters

query
string
The Lucene-formatted query string. Default to '*' if not set.
fields
string[]
The list of the fields returned by the search. Defaults to all. crn is always returned.

Possible values: number of items ≥ 1
searchCursor
string
An opaque search cursor that is returned on each operation call and that must be set on next call.

Possible values: length ≥ 1
transactionId
string
An aplhanumeric string that can be used to trace a request across services. If not specified it will be automatically generated with the prefix "gst-".
accountId
string
The account ID to filter resources.

Possible values: Value must match regular expression /^[a-fA-F0-9-]+$|^[*]{1}$/
limit
number
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
timeout
number
A search timeout, bounding the search request to be executed within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
sort
string[]
Comma separated properties names used for sorting.

Possible values: Value must match regular expression /^[+-]?\\w+[\\w\\-\\.]*$/

parameters

query
str
The Lucene-formatted query string. Default to '*' if not set.
fields
List[str]
The list of the fields returned by the search. Defaults to all. crn is always returned.

Possible values: number of items ≥ 1
search_cursor
str
An opaque search cursor that is returned on each operation call and that must be set on next call.

Possible values: length ≥ 1
transaction_id
str
An aplhanumeric string that can be used to trace a request across services. If not specified it will be automatically generated with the prefix "gst-".
account_id
str
The account ID to filter resources.

Possible values: Value must match regular expression /^[a-fA-F0-9-]+$|^[*]{1}$/
limit
int
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
timeout
int
A search timeout, bounding the search request to be executed within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
sort
List[str]
Comma separated properties names used for sorting.

Possible values: Value must match regular expression /^[+-]?\\w+[\\w\\-\\.]*$/

Example request

curl -X POST --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   -d '{"query": "GST-sdk-*", "fields": ["*"]}'   "{base_url}/v3/resources/search"

Example request

searchOptions := globalSearchService.NewSearchOptions()
searchOptions.SetLimit(10)
searchOptions.SetQuery("GST-sdk-*")
searchOptions.SetFields([]string{"*"})

scanResult, response, err := globalSearchService.Search(searchOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(scanResult, "", "  ")
fmt.Println(string(b))

Example request

SearchOptions searchOptions = new SearchOptions.Builder()
  .query("GST-sdk-*")
  .fields(new java.util.ArrayList<String>(java.util.Arrays.asList("*")))
  .searchCursor(searchCursor)
  .build();

Response<ScanResult> response = service.search(searchOptions).execute();
ScanResult scanResult = response.getResult();

System.out.println(scanResult);

Example request

const params = {
  query: 'GST-sdk-*',
  fields: ['*'],
  searchCursor: searchCursor,
};

globalSearchService.search(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

response = global_search_service.search(query='GST-sdk-*',
                    fields=['*'])
scan_result = response.get_result()

print(json.dumps(scan_result, indent=2))

Response

Response Body

ScanResult

The search scan response

ScanResult

The search scan response.

ScanResult

The search scan response.

ScanResult

The search scan response.

ScanResult

The search scan response.

Status Code

200
A result paging with the list of resources matching the provided filters.
400
Bad Request
401
Unauthorized / Wrong auth token type IAM / Auth token not valid
403
Unauthorized operation
500
Internal Server Error / IAM not initialized / Malformed IAM credentials
502
Search IAM error
default
System problem or unexpected error

Example responses

Status 400

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Error example

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 401

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Error example

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 403

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Error example

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 500

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Error example

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status 502

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Error example

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Status default

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Error example

{
  "code": "STRING",
  "description": "STRING",
  "level": "STRING",
  "message": "STRING",
  "more_info": "STRING",
  "response": "STRING"
}

Retrieves a list of all GhoST indices.

GET /v2/resources/supported_types

(globalSearch *GlobalSearchV2) GetSupportedTypes(getSupportedTypesOptions *GetSupportedTypesOptions) (result *SupportedTypesList, response *core.DetailedResponse, err error)

(globalSearch *GlobalSearchV2) GetSupportedTypesWithContext(ctx context.Context, getSupportedTypesOptions *GetSupportedTypesOptions) (result *SupportedTypesList, response *core.DetailedResponse, err error)

ServiceCall<SupportedTypesList> getSupportedTypes()

getSupportedTypes(params)

get_supported_types(self,
        **kwargs
    ) -> DetailedResponse