Use this API to perform a search and return results asynchronously.
Notes
login
API. 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 API.logout
API.For more information, see Developing.
This topic contains the following information:
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:
Sequence | Method | Description |
---|---|---|
1 | POST | 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. |
2 | GET | 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. |
Ensure that the following requirements are met:
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.
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.
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.
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:
POST
http://localhost:9797/olaengine/itdaws/searchservices/searchJob
{ "searchValue": "ITDA collection polls with no data", "searchType": "savedSearchName", "startTime": 1450956821246, "endTime": 1451561621246, "pageSize": 100, "pageNumber": 10 }
{ "id": "1395581436753.-1201449283", "searchResults": { "statusCode": "200", "statusMessage": "Ok", "results": [ 0 ], "totalRecords": 0 }, "status": "RUNNING" }
The following example illustrates the input and response for running a saved search, "DetectDowntime" with the following inputs by using the POST method:
POST
http://localhost:9797/olaengine/itdaws/searchservices/
searchJob
{ "searchValue": "DetectDowntime", "searchType": "savedSearchName", "startTime": "now-60m", "endTime": "now", "pageSize": "100", "pageNumber": "1", "source": "cp", "sourceName": "BPPMCP2" }
{ "id": "1463381436753.-1201559275", "searchResults": { "statusCode": "200", "statusMessage": "Ok", "results": [ 0 ], "totalRecords": 0 }, "status": "RUNNING" }
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.
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.
{ "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 }
The following parameters can be used in the request body.
Note The parameter names are case sensitive. 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: Supported with both POST and GET methods Required Value corresponding to the Can be one of the following: Note: Tabular commands are not supported in the query string or the saved search query. For more information about tabular commands, see Search commands. 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: The following definitions apply while specifying time in the format, now<sign><value><unit>: Note: While running the POST request, the start time and end time parameters function in the following way: 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: The following definitions apply while specifying time in the format, now<sign><value><unit>: Note: While running the POST request, the start time and end time parameters function in the following way: Supported with POST method only Optional, default is 0 Index of the page from which records (or events) must be returned. Supported with POST method only Optional, default is 100 Maximum number of records (or events) to return in a page. 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: 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: Supported with both POST and GET methods Optional, applicable only if the searchType is a saved search name. Value corresponding to the Can be one of the following:Parameter name Description searchType
searchValue
searchType
specified.startTime
For example, now+60m or now-2.
Units can be specified in the following ways:s
, sec
, secs
, seconds
m
, min
, mins
, minutes
h
, hr
, hrs
, hour
, hours
d
, day
, days
endTime
For example, now+60m or now-2.
Units can be specified in the following ways:s
, sec
, secs
, seconds
m
, min
, mins
, minutes
h
, hr
, hrs
, hour
, hours
d
, day
, days
pageNumber
pageSize
resultCountReq
source
sourceName
source
specified.
The following sections help you understand the response elements:
The API response contains the following main elements:
Response element | Description |
---|---|
Successful response | |
String | A string describing the status code returned. For more information, see HTTP status codes. |
String | Message explaining the reason for the response. |
Array | Set of search results corresponding to the search type and search value specified. |
Long | The total number of records (search results) present in the system. |
Unsuccessful response | |
While obtaining a search job ID (POST) | |
Array | Details of the error – severity, error code, and error message. |
While running a search job (GET) | |
String | Severity of the error. |
String | Error code. |
String | Message explaining the reason for the error. |
See examples.
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." }]
The following table describes the status codes that are likely to appear while working with this API.HTTP status codes
Status code | Description |
---|---|
200 | Request completed successfully. Also occurs if no results were found. |
400 | Invalid search type. |
401 | Authorization error (invalid authorization token or authorization token not present). |
404 | Incorrect saved search name. |
500 | Invalid search job ID or the search job ID has expired. |
1 Comment
Cathi Biagi