Searching and getting results synchronously with a REST API
Use this endpoint to perform a search and return results synchronously.
Recommendation
If your search query is too generic and is likely to produce a large set of results, search performance might be impacted. In such a scenario, BMC recommends you to use the Searching and getting results asynchronously with a REST API.
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. If the
check.csrf.header.XRequestedWith
olaengineConfig.properties
file is set to TRUE, then you need a new headerX-Requested-With=XMLHttpRequest
to be added to the API calls. For accessing the application in secure mode (from CSRF), the addition of this header is mandatory in every request.- 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:
Endpoint overview
You can use this API to run by using the GET method and by using the POST method.
With the GET method, you can run the search by specifying the saved search name or the saved search ID and by specifying minimum parameters. The time range used for running the search is based on the saved search specified.
With the POST method, you can run the search by specifying the saved search name, saved search ID, or a query string. With this kind of search, you can specify many more parameters (as compared to the GET method).
Notes
- Tabular commands are not supported in the saved search query and the query string (specified as input). For more information about tabular commands, see Search commands.
- The parameter names and their corresponding values must be enclosed in double quotes ("). For example,
"searchType"
:
"savedSearchName"
. - To obtain the saved search ID, you need to run the Getting details of a saved search with a REST API.
Using the search ID while performing a search (rather than a saved search name) might be more useful in scenarios when duplicate saved search names occur. Duplicate saved searches can occur in a scenario where one user creates a saved search with a particular name, while another user creates a saved search with the same name and also marks it as public. In this scenario, the first user can see two saved searches with the same name. Similarly, a duplicate saved search can occur when you import a content pack containing saved search with a duplicate name.
The expected response of this API is a set of search results returned synchronously.
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 run a search by the saved search name or saved search ID by using the GET method:
GET <protocol>://<host>:<port>/olaengine/itdaws/
searchservices/
search?<supportedParameters>&version=<apiVersion>
Use the following request URL to run a search by the saved search name, saved search ID, or query string by using the POST method:
POST <protocol>://<host>:<port>/olaengine/itdaws/
searchservices/
search?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.<supportedParameters>
refers to parameters to be specified for running the search. These parameters need to be specified as name=value pairs separated by an ampersand (&).
For more information, see the parameter definitions and examples.(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 running a search by using the POST method. For more information about the parameters that can be used in the request body, see Parameter definitions (advanced search).
To understand the structure of the request body, see the Examples for running an advanced search.
Examples
The following examples illustrate the inputs for running a search by using the GET method and the POST method.
- Example 1: Search by the saved search name (GET method)
- Example 2: Search by the saved search imported via a content pack (GET method)
- Example 3: Search by saved search ID (GET method)
- Example 4: Search by the saved search name for the epoch time specified (POST method)
- Example 5: Search by the saved search that is imported via a content pack (POST method)
Example 1: Search by the saved search name (GET method)
The following example illustrates the input for running the saved search, "SS9".
GET http://localhost:9797/olaengine/itdaws/searchservices/
search?searchValue=SS9
To understand the response structure and its elements, see Response elements.
Example 2: Search by the saved search imported via a content pack (GET method)
The following example illustrates the input for running the saved search, "SS1", imported via the content pack, "BPPMCP".
GET
http://localhost:9797/olaengine/itdaws/searchservices/
search
?searchValue=SS1&searchType=savedSearchName&
source="cp"&sourceName="BPPMCP"
To understand the response structure and its elements, see Response elements.
Example 3: Search by saved search ID (GET method)
The following example illustrates the input for running the saved search ID, "102be3d4-8729-44e8-b962-927bfdc30bbc".
GET
http://localhost:9797/olaengine/itdaws/searchservices/
search
?searchValue=102be3d4-8729-44e8-b962-927bfdc30bbc&searchType=savedSearchID
To understand the response structure and its elements, see Response elements.
Example 4: Search by the saved search name for the epoch time specified (POST method)
The following example illustrates the input 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 5
- Page size set to 50
POST http://localhost:9797/olaengine/itdaws/
searchservices/
search
{
"searchValue": "ITDA collection polls with no data",
"searchType": "savedSearchName",
"startTime": 1450956821246,
"endTime": 1451561621246,
"pageSize": 50,
"pageNumber": 5
}
To understand the response structure and its elements, see Response elements.
Example 5: Search by the saved search that is imported via a content pack (POST method)
The following example illustrates the input 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"
POST
http://localhost:9797/olaengine/itdaws/searchservices/
search
{
"searchValue": "DetectDowntime",
"searchType": "savedSearchName",
"startTime": "now-60m",
"endTime": "now",
"pageSize": "100",
"pageNumber": "1",
"source": "cp",
"sourceName": "BPPMCP2"
}
To understand the response structure and its elements, see Response elements.
Parameter definitions
The following parameters can be used in the request URL and the request body.
All the parameters can be used in the request body, while a limited set is supported in the request URL (while running the GET method).
Note
The parameter names are case sensitive.
Parameter name | Description |
---|---|
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:
|
Response elements
The following sections help you understand the response elements:
Element definitions
The endpoint 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 | |
Array | Details of the error – severity, error code, and error message. |
Successful response sample
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
}
Unsuccessful response sample
{
"messages": [{
"severity": "Error",
"code": "saved.search.with.provided.searchtype.or.searchvalue.doesnot.exist",
"text": "No saved search found with provided savedSearchName "SS1" or User does not have access to it."
}]
}
HTTP status codes
The following table describes the status codes that are likely to appear while working with this endpoint.
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 | Error occurred while processing the request. Occurrence of this error is rare. For more information, see the error message. Alternatively, see the itda.log located at %BMC_ITDA_HOME%\logs. |
Comments
Log in or register to comment.