×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
BMC TrueSight IT Data Analytics 11.0 Developing

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:

SequenceMethodDescription
1POST

Request to obtain the search job ID.

You need to obtain the search job ID to run the subsequent search job and get asynchronous results.

While running this request, you need to specify all the inputs required to perform a search. The input parameters are the same as those used while running the search API, POST request.

By default the resulting job ID is only valid for ten minutes. After ten minutes, you will need to rerun the POST request for obtaining the job ID.

2GET

Request to run the search job using the job ID obtained by making the POST request.

Note: Each time you want to see the next batch of asynchronous results, you need to run the POST request to obtain a job ID, and then subsequently use that job ID to run the GET request.



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.

Parameter nameDescription

searchType

Supported with both POST and GET methods

Required for the POST method

Optional for the GET method, default is saved search name

Search criteria by which you want to search.

Can be one of the following:

  • savedSearchName: Indicates that you want to search by the saved search name.
  • savedSearchId: Indicates that you want to search by the saved search ID.
  • queryString: Indicates that you want to search by a query string. This parameter is not supported while running a GET request.

searchValue

Supported with both POST and GET methods

Required

Value corresponding to the searchType specified.

Can be one of the following:

  • Saved search name
  • Saved search ID
  • Query string

Note: Tabular commands are not supported in the query string or the saved search query. For more information about tabular commands, see Search commands.

startTime

Supported with POST method only

Optional, default is now-60min


Date and time marking the starting point of the search.

Can be one of the following:

  • Time in the epoch format (in milliseconds). 
  • Time in the format, now<sign><value><unit>
    For example, now+60m or now-2.

The following definitions apply while specifying time in the format, now<sign><value><unit>:

  • <sign>: can be "+" or "-" depending on whether you want to specify a value after some time from now (+) or before some time from now (-).
  • <value>: refers to a whole number.
  • <unit>: can be either seconds, minutes, hours, or days.
    Units can be specified in the following ways:
    • Seconds: s, sec, secs, seconds
    • Minutes: m, min, mins, minutes
    • Hours: h, hr, hrs, hour, hours
    • Days: d, day, days

Note: While running the POST request, the start time and end time parameters function in the following way:

  • While searching with the saved search name or ID: If not specified, the start and end time of the saved search is used.
  • While searching with the search query: If not specified, the default start and end time values are used (that is last 60 minutes from the time of running the search).

 

endTime

Supported with POST method only

Optional, default is now

Date and time marking the ending point of the search.

Can be one of the following:

  • Time in the epoch format. 
  • Time in the format, now<sign><value><unit>
    For example, now+60m or now-2.

The following definitions apply while specifying time in the format, now<sign><value><unit>:

  • <sign>: can be "+" or "-" depending on whether you want to specify a value after some time from now (+) or before some time from now (-).
  • <value>: refers to a whole number.
  • <unit>: can be either seconds, minutes, hours, or days.
    Units can be specified in the following ways:
    • Seconds: s, sec, secs, seconds
    • Minutes: m, min, mins, minutes
    • Hours: h, hr, hrs, hour, hours
    • Days: d, day, days

Note: While running the POST request, the start time and end time parameters function in the following way:

  • While searching with the saved search name or ID: If not specified, the start and end time of the saved search is used.
  • While searching with the search query: If not specified, the default start and end time values are used (that is last 60 minutes from the time of running the search).

 

pageNumber

Supported with POST method only

Optional, default is 0

Index of the page from which records (or events) must be returned.

pageSize

Supported with POST method only

Optional, default is 100

Maximum number of records (or events) to return in a page.

resultCountReq

Supported with both POST and GET methods

Optional, default is Yes

Total count of search results available for the search run.

Can be one of the following:

  • Yes
  • No

source

Supported with both POST and GET methods

Optional, applicable only if the searchType is a saved search name.

Source type of the saved search.

Can be one of the following:

  • cp: Indicates that the saved search was imported via a content pack.
  • user: Indicates that the saved search was created by a user.

sourceName

Supported with both POST and GET methods

Optional, applicable only if the searchType is a saved search name.

Value corresponding to the source specified.

Can be one of the following:

  • Name of the content pack via which the saved search was imported.
  • Name of the user who created the saved search.

Response elements

The following sections help you understand the response elements:

Element definitions

The endpoint response contains the following main elements:

Response elementDescription
Successful response

statusCode

String

A string describing the status code returned.

For more information, see HTTP status codes.

statusMessage  

String

Message explaining the reason for the response.

results

Array

Set of search results corresponding to the search type and search value specified.

totalRecords

Long

The total number of records (search results) present in the system.
Unsuccessful response
While obtaining a search job ID (POST)

messages

Array

Details of the error – severity, error code, and error message.

While running a search job (GET)

severity

String

Severity of the error.

code

String

Error code.

text

String

Message explaining the reason for the error.


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.

Status codeDescription
200

Request completed successfully.

Also occurs if no results were found.

400Invalid search type.
401Authorization error (invalid authorization token or authorization token not present).
404Incorrect saved search name.
500Invalid search job ID or the search job ID has expired.

Was this page helpful? Yes No Submitting... Thank you
Last modified by Melody Locke on Oct 20, 2017
developing endpoint searching

Comments

Log in or register to comment.

Modifying user groups associated with hosts with a REST API
Searching and getting results synchronously with a REST API
© Copyright 2014-2017 BMC Software, Inc
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.