• Spaces
  • Collections
  • Help
    • ×
     
     
    •  
    BMC TrueSight IT Data Analytics 2.5

    Page tree

    Use this API 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 API.

    Notes

    • Before running this API, you need to generate an authorization token by running the 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.
    • To log out from a given session, you need to run the logout API.

    For more information, see Developing.

    This topic contains the following information:

    Related topics

    Searching the data

    Search tips

    Searching and getting results asynchronously API

    Getting details of a saved search API

    API 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 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)

    The following example illustrates the input for running the saved search, "SS9".

    Request URL
    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".

    Request URL
    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".

    Request URL
    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
    Request URL

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

    Request body
    {
    "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"
    Request URL

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

    Request body
    {
    "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 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 API 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

    messages

    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.

    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
}

    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 API.

    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.
    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.

    • No labels
    © 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.