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 Cloud Foundry, IBM Containers, 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.

curl --request POST --header "content-type: application/json" --header "accept: application/json" --header "authorization: {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 values for your particular API call.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>platform-services</artifactId>
    <version>0.0.1</version>
</dependency>

Gradle

'com.ibm.cloud:platform-services:0.0.1'

GitHub

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install --save ibm-cloud

GitHub

The code examples on this tab use the client library that is provided for Python.

Installation

To install, use pip or easy_install:

pip install --upgrade "platform-services>=0.0.1"

or

easy_install --upgrade "platform-services>=0.0.1"

GitHub

There are a few different ways to download and install the Platform Services Go SDK project for use by your Go application:

Go get command

Use this command to download and install the Platform Services Go SDK project to allow your Go application to use it:

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

Go modules

If your application is using Go modules, you can add a suitable import to your Go application, like this:

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

Next, run go mod tidy to download and install the new dependency and update your Go application's go.mod file.

Dep dependency manager

If your application is using the dep dependency management tool, you can add a dependency to your Gopkg.toml file. Here is an example:

[[constraint]]
  name = "github.ibm.com/ibmcloud/platform-services-go-sdk/globalsearchv2"
  version = "0.0.1"

then run

dep ensure

GitHub

Authentication

REST APIs require the user to specify an OAuth2 security token in the header to be authorized by the IBM Cloud IAM service. You can obtain a bearer token by using the IBM Cloud command line command ibmcloud iam oauth-tokens. Another way to obtain a bearer token is through an API key. For more information, see Getting an IBM Cloud IAM token by using an API key.

Endpoint URLs

Global Search and Tagging search APIs use a global endpoint:

api.global-search-tagging.cloud.ibm.com
api.global-search-tagging.cloud.ibm.com

Search example

const GhoSTSearch = require('ibm-cloud/global-search/v2');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new IamAuthenticator({
  apikey: {apikey}
});

const query = {query}
const fields = ['crn', 'name'];
const limit = 100;

const params = {
    query: query,
    limit: limit,
    fields: fields
};

const options = {};
options.authenticator = authenticator;
const globalSearch = new GlobalSearchV2(options);

globalSearch.search(params).then(response => {
    assert(response.status === 200);
    for (let item of response.items) {
        console.log(item);
    }
}).catch(error => {
    console.error(error);
});

Replace {apikey} and {query} in this example with the values for your particular API call.

Search example


import com.ibm.cloud.sdk.core.security.IamAuthenticator;
import com.ibm.cloud.platform_services.global_search.v2.model.ScanResult;
import com.ibm.cloud.platform_services.global_search.v2.model.SearchOptions;
import com.ibm.cloud.platform_services.global_search.v2.model.SearchOptions.Builder;

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
GlobalSearch globalSearch = new GlobalSearch("global_search", authenticator);

Builder builder = new SearchOptions.Builder().query("{query}");
SearchOptions searchOpt = builder.build();
Response<ScanResult> response = globalSearch.search(searchOpt).execute();
ScanResult result = response.getResult();
System.out.println("Items found: " + result.getItems().size());

Replace {apikey} and {query}in this example with the values for your particular API call.

Search example

from platform_services import GlobalSearchV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
global_search = GlobalSearchV2(authenticator=authenticator)

env = global_search.search(query='{query}', search_cursor=None, transaction_id=None)
results = env.get_result()
items = results.get('items')
assert items is not None
assert len(items) == 2

Replace {apikey} and {query} in this example with the values for your particular API call.

Search example

import (
    "github.com/IBM/go-sdk-core/v3/core"
    . "github.com/onsi/ginkgo"
    . "github.com/onsi/gomega"
    "github.com/IBM/platform-services-go-sdk/globalsearchv2"
    "github.com/joho/godotenv"
    "os"
)
    authenticator := &core.IamAuthenticator{
  ApiKey: "{apikey}"
    }

  options := &globalsearchv2.GlobalSearchV2Options{
        Authenticator: authenticator,
    }
    service, err := globalsearchv2.NewGlobalSearchV2(options)

  searchOptionsModel := service.NewSearchOptions()
  searchOptionsModel.SetQuery("{query}");
  result, detailedResponse, err := service.Search(searchOptionsModel)

Replace {apikey} and {query} in this example with the values for your particular API call.

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.

Methods

Find instances of resources

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.

POST /v2/resources/search

Request

Custom Headers

  • 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

  • The account ID to filter resources.

    Constraints: Value must match regular expression ^[a-fA-F0-9-]+$|^[*]{1}$

  • The maximum number of hits to return. Defaults to 10.

    Constraints: 1 ≤ value ≤ 1000

    Default: 10

  • 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.

    Constraints: 0 ≤ value ≤ 600000

    Default: 0

  • The offset is the index of the item you want to start returning data from. Default is 0.

    Default: 0

  • Comma separated properties name used for sorting

  • 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

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

Response

The results of the requested search.

Status Code

  • A result paging with the list of resources matching the provided filters.

  • Bad Request

  • Unauthorized / Wrong auth token type IAM / Auth token not valid

  • Unauthorized operation

  • Internal Server Error / IAM not initialized / Malformed IAM credentials

  • Search IAM error

  • System problem or unexpected error

Example responses
  • {
      "items": {
        "...": "STRING",
        "crn": "STRING"
      },
      "more_data": "BOOLEAN",
      "token": "STRING"
    }
  • {
      "code": "STRING",
      "description": "STRING",
      "level": "STRING",
      "message": "STRING",
      "more_info": "STRING",
      "response": "STRING"
    }
  • {
      "code": "STRING",
      "description": "STRING",
      "level": "STRING",
      "message": "STRING",
      "more_info": "STRING",
      "response": "STRING"
    }
  • {
      "code": "STRING",
      "description": "STRING",
      "level": "STRING",
      "message": "STRING",
      "more_info": "STRING",
      "response": "STRING"
    }
  • {
      "code": "STRING",
      "description": "STRING",
      "level": "STRING",
      "message": "STRING",
      "more_info": "STRING",
      "response": "STRING"
    }
  • {
      "code": "STRING",
      "description": "STRING",
      "level": "STRING",
      "message": "STRING",
      "more_info": "STRING",
      "response": "STRING"
    }
  • {
      "code": "STRING",
      "description": "STRING",
      "level": "STRING",
      "message": "STRING",
      "more_info": "STRING",
      "response": "STRING"
    }

Find instances of resources

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.

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.

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.

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.

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

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

  • 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

  • The account ID to filter resources.

    Constraints: Value must match regular expression ^[a-fA-F0-9-]+$|^[*]{1}$

  • The maximum number of hits to return. Defaults to 10.

    Constraints: 1 ≤ value ≤ 1000

    Default: 10

  • 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.

    Constraints: 0 ≤ value ≤ 600000

    Default: 0

  • Comma separated properties names used for sorting

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

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.

Example:

WithContext method only

The Search options.

The search options.

parameters

  • The Lucene-formatted query string. Default to '*' if not set.

  • The list of the fields returned by the search. Defaults to all. crn is always returned.

    Constraints: number of items ≥ 1

  • An opaque search cursor that is returned on each operation call and that must be set on next call.

    Constraints: length ≥ 1

  • 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-".

  • The account ID to filter resources.

    Constraints: Value must match regular expression /^[a-fA-F0-9-]+$|^[*]{1}$/

  • The maximum number of hits to return. Defaults to 10.

    Constraints: 1 ≤ value ≤ 1000

  • 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.

    Constraints: 0 ≤ value ≤ 600000

  • Comma separated properties names used for sorting.

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

parameters

  • The Lucene-formatted query string. Default to '*' if not set.

  • The list of the fields returned by the search. Defaults to all. crn is always returned.

    Constraints: number of items ≥ 1

  • An opaque search cursor that is returned on each operation call and that must be set on next call.

    Constraints: length ≥ 1

  • 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-".

  • The account ID to filter resources.

    Constraints: Value must match regular expression /^[a-fA-F0-9-]+$|^[*]{1}$/

  • The maximum number of hits to return. Defaults to 10.

    Constraints: 1 ≤ value ≤ 1000

  • 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.

    Constraints: 0 ≤ value ≤ 600000

  • Comma separated properties names used for sorting.

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

  • curl -X POST -H "Authorization: {iam_token}"   -H "Accept: application/json"   -H "Content-Type: application/json"   -d '{"query": "GST-sdk-*", "fields": ["*"]}'   "{base_url}/v3/resources/search"
  • 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))
  • 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);
  • 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)
      });
  • response = global_search_service.search(query='GST-sdk-*',
                        fields=['*'])
    scan_result = response.get_result()
    
    print(json.dumps(scan_result, indent=2))

Response

The search scan response

The search scan response.

The search scan response.

The search scan response.

The search scan response.

Status Code

  • A result paging with the list of resources matching the provided filters.

  • Bad Request

  • Unauthorized / Wrong auth token type IAM / Auth token not valid

  • Unauthorized operation

  • Internal Server Error / IAM not initialized / Malformed IAM credentials

  • Search IAM error

  • System problem or unexpected error

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

Get all supported resource types

Retrieves a list of all the resource types supported by GhoST.

Retrieves a list of all the resource types supported by GhoST.

Retrieves a list of all the resource types supported by GhoST.

Retrieves a list of all the resource types supported by GhoST.

Retrieves a list of all the resource types supported by GhoST.

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

Request

No Request Parameters

This method does not accept any request parameters.

WithContext method only

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET -H "Authorization: {iam_token}"   -H "Accept: application/json"   "{base_url}/v2/resources/supported_types"
  • getSupportedTypesOptions := globalSearchService.NewGetSupportedTypesOptions()
    
    supportedTypesList, response, err := globalSearchService.GetSupportedTypes(getSupportedTypesOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(supportedTypesList, "", "  ")
    fmt.Println(string(b))
  • GetSupportedTypesOptions getSupportedTypesOptions = new GetSupportedTypesOptions();
    
    Response<SupportedTypesList> response = service.getSupportedTypes(getSupportedTypesOptions).execute();
    SupportedTypesList supportedTypesList = response.getResult();
    
    System.out.println(supportedTypesList);
  • globalSearchService.getSupportedTypes({})
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • supported_types_list = global_search_service.get_supported_types(
    ).get_result()
    
    print(json.dumps(supported_types_list, indent=2))

Response

A list of resource types supported by GhoST.

A list of resource types supported by GhoST.

A list of resource types supported by GhoST.

A list of resource types supported by GhoST.

A list of resource types supported by GhoST.

Status Code

  • List of supported resource types

  • System problem or unexpected error

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