Searching and getting results asynchronously with a REST API

Use this endpoint to perform a search and return results asynchronously.

Notes

  • Before running this endpoint, you need to generate an authorization token by running the login endpoint. This token is used to authenticate a user into the product. You need to pass this token in the header each time you want to run the endpoint.
  • To log out from a given session, you need to run the logout endpoint.

For more information, see Developing.

This topic contains the following information:

Related topics

Getting-started-with-search

Search-strategies

Searching-and-getting-results-synchronously-with-a-REST-API

Getting-details-of-a-saved-search-with-a-REST-API

Endpoint overview

Use the POST and GET methods to perform a search and return results asynchronously.

Displaying results asynchronously means that the results are displayed immediately on completion of the search job. Conversely, synchronous results are displayed only after examining the entire data set against the search query.

Running this API is useful if you are running a very generic search query or if you are running the search on a very large data set.

To search and get results asynchronously, you need to run the following requests in the given sequence:


Before you begin

Ensure that the following requirements are met:

  • The data on which you want to search is available for searching. This means the data needs to be already collected and indexed.
  • You have appropriate permissions to view the data that you want to search.
  • The saved search that you want to use for searching is created by you or is a public saved search (that is accessible by all users).

Request URL

Use the following request URL to obtain the search job ID:

POST <protocol>://<host>:<port>/olaengine/itdaws/searchservices/searchJob? version=<apiVersion>

Use the following request URL to run the search job:

GET <protocol>://<host>:<port>/olaengine/itdaws/searchservices/searchJob?searchJobID=<jobID>& version=<apiVersion>

In the preceding URLs, the following definitions apply:

  • <protocol> refers to the protocol that you want to use for communication with the Console Server.
  • <host> refers to the host name of the Console Server
  • <port> refers to the port number of the Console Server. The default port is 9797.
  • <apiVersion> refers to the search job ID obtained by running the POST request.

  • (Optional)   <apiVersion> refers to the API version. In this case, the value must be 2.5.

    Tip

    Generally the API version is the same as the product version on which the API can be run.

Request body

The request body is applicable only for obtaining the search job ID by using the POST method. While running the POST request, at a minimum you need to specify the search type and the and search value. Specifying the other parameters is optional. For more information about the parameters, see Parameter definitions.

To understand the structure of the request body, see the examples.

Examples

The following examples illustrate the inputs and response for obtaining the search job ID by using the POST method and for running the search job and getting results asynchronously by using the GET method.

Example 1: Obtain the search job ID by running a saved search for the epoch time

The following example illustrates the input and response for running a saved search, "ITDA collection polls with no data" with the following inputs by using the POST method:

  • Specified epoch time
  • Page number set to 10
  • Page size set to 50

Request URL

POST http://localhost:9797/olaengine/itdaws/searchservices/searchJob

Request body
{
   "searchValue": "ITDA collection polls with no data",
   "searchType": "savedSearchName",
   "startTime": 1450956821246,
   "endTime": 1451561621246,
   "pageSize": 100,
   "pageNumber": 10
}
Response
{
   "id":   "1395581436753.-1201449283",
   "searchResults":   {
       "statusCode":   "200",
       "statusMessage":   "Ok",
       "results":   [
           0
        ],
       "totalRecords":  0
    },
   "status":   "RUNNING"
}

Example 2: Obtain the search job ID by running a saved search coming from a content pack

The following example illustrates the input and response for running a saved search, "DetectDowntime" with the following inputs by using the POST method:

  • Specified time – last 60 minutes
  • Page number set to 1
  • Page size set to 100
  • Content pack name (or source name) set to "BPPMCP2"

Request URL

POST http://localhost:9797/olaengine/itdaws/searchservices/searchJob

Request body
{
   "searchValue": "DetectDowntime",
   "searchType": "savedSearchName",
   "startTime": "now-60m",
   "endTime": "now",
   "pageSize": "100",
   "pageNumber": "1",
   "source": "cp",
   "sourceName": "BPPMCP2"
}
Response
{
   "id":   "1463381436753.-1201559275",
   "searchResults":   {
       "statusCode":   "200",
       "statusMessage":   "Ok",
       "results":   [
           0
        ],
       "totalRecords":  0
    },
   "status":   "RUNNING"
}

Example 3: Running a search job to get results corresponding to the job ID

The following example illustrates the input and response for getting search results by running the search job ID, 1451553915591.-1450710764 by using the GET method.

Request URL

GET http://localhost:9797/olaengine/itdaws/searchservices/searchJob?searchJobId=1451553915591.-1450710764

Note: Because search results can be quite verbose, in the following response, repeated elements have been omitted for clarity.

Response
{
   "statusCode": "200",
   "statusMessage": "Ok",
   "results": [{
       "timestamp": 1463764706366,
       "fieldValues": {
           "COLLECTOR_NAME": {
               "values": [{
                   "value": "ITDA Collection Metrics_Collection Metrics_clm-pun.bmc.com"
                }]
            },
           "HOST": {
               "values": [{
                   "value": "clm-pun.bmc.com"
                }]
            },
           "COLLECTOR": {
               "values": [{
                   "value": "C:\\Program Files\\BMC Software\\TrueSight\\ITDA\\station\\collection\\logs\\Collection_metrics.log"
                }]
            },
           "DATA_PATTERN": {
               "values": [{
                   "value": "ITDA Metrics"
                }]
            },
           "events": {
               "values": [{
                   "value": "1"
                }]
            }
        },
       "raw": "[2016-05-20 22:48:26.366] [COLLECTION_STATION] [collection-station_clm-pun.bmc.com] [duration-in-milliseconds=0, source=ITDA Collection Metrics_Collection Metrics_clm-pun.bmc.com, events=1, indexing-lag=60047]",
       "score": 0,
       "host": "clm-pun.bmc.com",
       "id": "AVTPLc7sQ0CjiY-3F2kF",
       "fields": ["COLLECTOR_NAME", "HOST", "COLLECTOR", "DATA_PATTERN", "events"]
    }],
   "totalRecords": 1
}

Parameter definitions

The following parameters can be used in the request body.

Note

The parameter names are case sensitive.

Response elements

The following sections help you understand the response elements:

Element definitions

The endpoint response contains the following main elements:


Successful response sample

See examples.

Unsuccessful response sample

The following response can occur while requesting the search job ID.

{
   "messages": [{
       "severity": "Error",
       "code": "saved.search.with.provided.searchtype.or.searchvalue.doesnot.exist",
       "text": "No saved search found with provided savedSearchName = DetectDowntime or User does not have access to it."
    }]
}

The following response can occur while running a search job.

[{
   "severity": "Error",
   "code": "searchcomponenet.failed",
   "text": "Could not connect to the Search Component. Go to Administration > Components to see if Search Component is installed or contact your Administrator for support."
}]

HTTP status codes

The following table describes the status codes that are likely to appear while working with this endpoint.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*