IBM Cloud API Docs

Introduction

Last updated: 2022-05-09

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

Methods

Find instances of resources (v2)

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 by 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 > User > Access.

  • global-search-tagging.resource.read

Request

Custom Headers

  • x-request-id
    string

    An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

    Possible values: Value must match regular expression .*

  • x-correlation-id
    string

    An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

    Possible values: Value must match regular expression .*

  • X-IMS-Auth-Token
    string

    The SoftLayer authorization token. You must set it only if you are searching SoftLayer resources, which you do adding ims to the search providers query parameter.

    Possible values: Value must match regular expression ^Basic .*$

Query Parameters

  • account_id
    string

    The account ID to filter resources.

    Possible values: Value must match regular expression ^[a-fA-F0-9]{32}$|^[*]{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 in milliseconds, bounding the search request to run 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

  • is_deleted
    string

    Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

    Allowable values: [true,false,any]

    Default: false

  • is_reclaimed
    string

    Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

    Allowable values: [true,false,any]

    Default: false

  • is_public
    string

    Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

    Allowable values: [true,false,any]

    Default: false

  • impersonate_user
    string

    The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

    Possible values: Value must match regular expression ^.*-.*$

  • can_tag
    string

    Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

    Allowable values: [true,false]

    Default: false

  • is_project_resource
    string

    Determines if documents belonging to Project family should be included in result set or not. Possible values are false (default), true or any. If false, documents belonging to all families except Project are returned; if true, only documents belonging to Project family are returned; if any, documents of any family are returned. Only authorized ServiceIds can use this query parameter.

    Allowable values: [true,false,any]

    Default: false

  • offset
    integer

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

    Possible values: 0 ≤ value ≤ 10000

    Default: 0

  • sort
    string

    Comma separated properties name that is 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 (initially set to null or undefined)

Examples: 
{
  "query": "(region:us-south OR region:us-east) AND (type:image OR type:key)",
  "fields": [
    "crn",
    "doc.*"
  ]
}

Response

Response Body

SearchResults

The results of the requested search.

Status Code

  • 200

    A result paging with the list of resources that match the provided filters.

  • 400

    Bad Request

  • 401

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

  • 403

    Unauthorized operation

  • 429

    Too Many Requests

  • 500

    Internal Server Error / IAM not initialized / Malformed IAM credentials

  • 502

    Search IAM error

  • default

    System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Find instances of resources (v3)

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

To filter results, you can insert a string by 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. 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 that are 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 using the fields request body attribute. Set "fields": ["*"] to discover the set of fields which are available to request.

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

To filter results, you can insert a string by 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. 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 that are 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, IAM-enabled resources, or storage and network resources that run on classic infrastructure in a specific account ID. You can apply query strings if necessary.

To filter results, you can insert a string by 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. 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 that are 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, IAM-enabled resources, or storage and network resources that run on classic infrastructure in a specific account ID. You can apply query strings if necessary.

To filter results, you can insert a string by 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. 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 that are 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, IAM-enabled resources, or storage and network resources that run on classic infrastructure in a specific account ID. You can apply query strings if necessary.

To filter results, you can insert a string by 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. 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 that are 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.

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,
        is_deleted: str = None,
        is_reclaimed: str = None,
        is_public: str = None,
        impersonate_user: str = None,
        can_tag: 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 > User > Access.

  • 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

  • x-request-id
    string

    An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

    Possible values: Value must match regular expression .*

  • x-correlation-id
    string

    An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

    Possible values: Value must match regular expression .*

Query Parameters

  • account_id
    string

    The account ID to filter resources.

    Possible values: Value must match regular expression ^[a-fA-F0-9]{32}$|^[*]{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 in milliseconds, bounding the search request to run 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 that are used for sorting

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

  • is_deleted
    string

    Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

    Allowable values: [true,false,any]

    Default: false

  • is_reclaimed
    string

    Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

    Allowable values: [true,false,any]

    Default: false

  • is_public
    string

    Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

    Allowable values: [true,false,any]

    Default: false

  • impersonate_user
    string

    The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

    Possible values: Value must match regular expression ^.*-.*$

  • can_tag
    string

    Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

    Allowable values: [true,false]

    Default: false

  • is_project_resource
    string

    Determines if documents belonging to Project family should be included in result set or not. Possible values are false (default), true or any. If false, documents belonging to all families except Project are returned; if true, only documents belonging to Project family are returned; if any, documents of any family are returned. Only authorized ServiceIds can use this query parameter.

    Allowable values: [true,false,any]

    Default: false

Request Body

Required*
One of

    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 are ignored. The search_cursor encodes all the information that needs to get the next batch of limit data.

    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. By default, the returned fields are the account_id, name, type, family, and crn. For all queries, crn is always returned.

      Possible values: number of items ≥ 1, Value must match regular expression /^\\S+$/

    • searchCursor
      string

      An opaque cursor that is returned on each call and that must be set on the subsequent call to get the next batch of items. If the search returns no items, then the search_cursor is not present in the response.

      Possible values: length ≥ 1

    • transactionId
      string

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

      Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/

    • accountId
      string

      The account ID to filter resources.

      Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/

    • limit
      number

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

      Possible values: 1 ≤ value ≤ 1000

      Default: 10

    • timeout
      number

      A search timeout in milliseconds, bounding the search request to run 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 that are used for sorting.

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

    • isDeleted
      string

      Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

      Allowable values: [true,false,any]

      Default: false

    • isReclaimed
      string

      Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

      Allowable values: [true,false,any]

      Default: false

    • isPublic
      string

      Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

      Allowable values: [true,false,any]

      Default: false

    • impersonateUser
      string

      The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

      Possible values: Value must match regular expression /^.*-.*$/

    • canTag
      string

      Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

      Allowable values: [true,false]

      Default: false

    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. By default, the returned fields are the account_id, name, type, family, and crn. For all queries, crn is always returned.

      Possible values: number of items ≥ 1, Value must match regular expression /^\\S+$/

    • search_cursor
      str

      An opaque cursor that is returned on each call and that must be set on the subsequent call to get the next batch of items. If the search returns no items, then the search_cursor is not present in the response.

      Possible values: length ≥ 1

    • transaction_id
      str

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

      Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/

    • account_id
      str

      The account ID to filter resources.

      Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/

    • limit
      int

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

      Possible values: 1 ≤ value ≤ 1000

      Default: 10

    • timeout
      int

      A search timeout in milliseconds, bounding the search request to run 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
      List[str]

      Comma separated properties names that are used for sorting.

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

    • is_deleted
      str

      Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

      Allowable values: [true,false,any]

      Default: false

    • is_reclaimed
      str

      Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

      Allowable values: [true,false,any]

      Default: false

    • is_public
      str

      Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

      Allowable values: [true,false,any]

      Default: false

    • impersonate_user
      str

      The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

      Possible values: Value must match regular expression /^.*-.*$/

    • can_tag
      str

      Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

      Allowable values: [true,false]

      Default: false

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

    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 that match the provided filters.

    • 400

      Bad Request

    • 401

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

    • 403

      Unauthorized operation

    • 429

      Too Many Requests

    • 500

      Internal Server Error / IAM not initialized / Malformed IAM credentials

    • 502

      Search IAM error

    • default

      System problem or unexpected error

    No Sample Response

    This method does not specify any sample responses.

    Get Globalcatalog categories

    Collects from Globalcatalog the information about categories, subcategories (children), and services that belong to those categories.

    GET /v3/resources/catalog_categories

    Request

    Custom Headers

    • x-request-id
      string

      An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    • x-correlation-id
      string

      An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    Query Parameters

    • translations_lang
      string

      The language you want to retrieve the Catalog translations. Default to English if not set.

      Allowable values: [en,de,es,fr,it,pt-br,ja,ko,zh-cn,zh-tw]

      Default: en

    Response

    Response Body

    CatalogCategories

    The Global catalog categories, subcategories, and services

    Status Code

    • 200

      A request status object

    • 401

      Missing or bad authentication

    • 429

      Too Many Requests

    • 500

      Internal Server Error

    • default

      System problem or unexpected error

    Example responses
    • {
  "categories": [
    {
      "id": "the category identifier in GC",
      "tags": [
        "category tags"
      ],
      "display_name": "the display name in the selected language",
      "services": [
        {
          "id": "the service identifier in GC",
          "name": "the service name in GC... and in GhoST",
          "display_name": "the display name in the selected language",
          "kind": "service|any other GC entry type",
          "gst_support": true
        }
      ],
      "children": [
        {
          "id": "id of a child/sub-category in GC",
          "tags": [
            "sub-category tags"
          ],
          "display_name": "the display name in the selected language",
          "services": [
            {
              "id": "the service identifier in GC",
              "display_name": "the service name in GC and in GhoST",
              "name": "the display name in the selected language",
              "kind": "service|any other GC entry type",
              "gst_support": true
            }
          ]
        }
      ]
    }
  ]
}

    Get service health information

    health endpoint

    GET /health

    Request

    Custom Headers

    • x-request-id
      string

      An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    • x-correlation-id
      string

      An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    Response

    Response Body

    HealthResponse

    Definition of success health response

    Status Code

    • 200

      Success

    • 424

      Failed Dependency Error

    • 429

      Failed - Too Many Requests

    No Sample Response

    This method does not specify any sample responses.

    Get service alive information

    alive endpoint

    GET /alive

    Request

    Custom Headers

    • x-request-id
      string

      An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    • x-correlation-id
      string

      An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    Response

    Response Body

    AliveResponse

    Definition of success alive response

    Status Code

    • 200

      Success

    • 429

      Too Many Requests

    • 501

      Failed Dependency Error

    No Sample Response

    This method does not specify any sample responses.

    Group resources into buckets based on field values

    Group resources into buckets based on field values, ranges, or other criteria. You can apply query strings if necessary. The query string follows the Lucene syntax, like for the /v3/resources/search.

    POST /v3/resources/aggregate

    Request

    Custom Headers

    • x-request-id
      string

      An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    • x-correlation-id
      string

      An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

      Possible values: Value must match regular expression .*

    Query Parameters

    • timeout
      integer

      A search timeout in milliseconds, bounding the search request to run 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

    • is_deleted
      string

      Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

      Allowable values: [true,false,any]

      Default: false

    • is_reclaimed
      string

      Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

      Allowable values: [true,false,any]

      Default: false

    • is_project_resource
      string

      Determines if documents belonging to Project family should be included in result set or not. Possible values are false (default), true or any. If false, documents belonging to all families except Project are returned; if true, only documents belonging to Project family are returned; if any, documents of any family are returned. Only authorized ServiceIds can use this query parameter.

      Allowable values: [true,false,any]

      Default: false

    Request Body

    Required*
    AggregateBody

    It contains the query filters and the terms aggregation instructions.

    Examples: 
    {
  "query": "region:(us-south OR us-east) AND service_name:cloudantsqldb",
  "aggregation": {
    "terms": {
      "field": "account_id",
      "missing": "N/A",
      "order": "term_asc"
    }
  }
}

    Response

    Response Body

    AggregateResult

    The resources aggregate response

    Status Code

    • 200

      The aggregated query results. filters.

    • 400

      Bad Request

    • 401

      Unauthorized, missing or invalid authorization.

    • 403

      Forbidden request.

    • 429

      Too Many Requests.

    • 500

      Internal server error.

    • 502

      Proxy or gateway error.

    • 503

      The server is currently unabled to handle the request.

    • default

      Temporary server error.

    Example responses
    • {
  "aggregation": {
    "terms": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 4794,
      "buckets": [
        {
          "term": "f065ca930006416511b1ebd61681ef9f",
          "doc_count": 123234
        },
        {
          "term": "b0000a9831104111171eae0089e90300",
          "doc_count": 3456
        }
      ]
    }
  }
}
    id=curlclassName=tab-item-selected