This article lists and describes the parameters you can use in Devo Query API query requests as well as the different response formats:
...
Parameter | Type | Description |
---|
Content-Type *required
| String (header) | This is always application/json |
Authorization
| String (header) | Include this header if you want to use a token to authorize your request. When you use a token, only the Content-Type and Authorization parameters are required. See Authorizing Query API requests for more information. |
x-logtrust-apikey
| String (header) | This is the Devo domain API key found in Administration → Credentials. |
x-logtrust-sign
| String (header) | HMAC SHA-256 using the API_SECRET to sign the concatenation of the api_key, body message and timestamp |
x-logtrust-timestamp
| String (header) | Timestamp in milliseconds. |
query
| String (body) | This is the query that you want to run, expressed in LINQ. To find the query's LINQ script, open the query in the Data Search area, then chooseToggle Query Editorcode editor from the toolbar. The body of the request must contain either the query or the queryId parameter. |
queryId
| String (body) | This is the ID of the query that you want to run. To find the query ID, open the query in the Data Search area, then choose Additional Tools → Query Info Current query → Get ID. The body of the request must contain either the query or the queryId parameter. |
from *required
| Number (body) | The start date as a UTC timestamp in seconds. See the Relative dates section below to learn more about this parameter. |
to
| Number (body) | The end date as a UTC timestamp in seconds. If this parameter is left out, the query will be continuous. See the Relative dates section below to learn more about this parameter. |
mode
| Object (body) | This object contains the mode.type parameter to specify the format of the response. If left out of the request body, the default response type JSON will be used. |
mode.type
| String (body) | The format in which you want the response to be sent. The possible values are: json json/compact json/simple json/simple/compact msgpack csv tsv xls
These response formats are fully described later in this article. When you indicate a response format other than json , you must include the dateFormat and timeZone parameters. |
destination
| Object (body) | This object specifies where the response should be sent. If this object is left out of the request body, the response will be sent back to the request source. |
destination.type
| String (body) | This is the type of system to which the response should be sent. The possible values are: Depending on the destination.type , additional parameters will be required. See the related HDFS, S3, email, SNMP and Kafka articles. |
destination.params
| List (body) | Destination parameters, depend on the destination.type . Check the HDFS, Kafka, S3, email and SNMP articles to see the parameters required for each destination. |
dateFormat
| String (body) | This is only required when you specify a mode.type other than json . The possible formats are: default - yyyy-MM-dd' 'HH:mm:ss.SSSsql - yyyy-MM-dd' 'HH:mm:ss.SSSiso - yyyy-MM-dd'T'HH:mm:ss.SSSXX
|
timeZone
| String (body) | Change the timezone of the query, only for mode types different from JSON. This parameter supports any positive or negative GMT timezones, like GMT-2 or GMT+1 |
skip/offset
| Number (body) | You can use either the skip or offset parameters to skip the first X elements of the query. |
limit
| Number (body) | Limit the results of the query. The query will stop after returning the first X elements of the query or reaching its end. |
ipAsString
| Boolean (body) | Set this parameter to true (ipAsString = true) if you want to get IP addresses as dotted strings (for example, 94.2.23.1 ). If you don't add this parameter in your request or set it to false, IP addresses will be returned as numbers (for example, 1577195265 ). |
progressInfo
| Boolean (body) | Set this parameter to true if you want to get progress info about the requested query. You will get an entry p with the timestamp of the event that is being processed at that moment. Progress info will be sent at most once every 5s. This is only available if you set mode.type as json/simple/compact . See an example below. |
...
Info |
---|
For all the examples that don't use a timestamp to specify a date, we assume that the moment of execution is 08-10-2018, 14:33:12 UTC. |
Dates
Operator | Description |
---|
today
| Get the current day at 00:00:00. Note that the timeZone parameter affects the date settings. "from": "today" This sets the starting date to 08-10-2018, 00:00:00 UTC
"to": "today" This sets the ending date to 08-10-2018, 00:00:00 UTC
"from" : "today"
"timeZone": "GMT+2" This sets the starting date to 08-10-2018, 00:00:00 GMT+2 (07-10-2018, 22:00:00 UTC)
"to" : "today"
"timeZone": "GMT+2" This sets the ending date to 08-10-2018, 00:00:00 GMT+2 (07-10-2018, 22:00:00 UTC)
|
now
| Get the current day and time "from": "now" This sets the starting date to 08-10-2018, 14:33:12 UTC
"to": "now" This sets the ending date to 08-10-2018, 14:33:12 UTC
|
endday
| If you use this in the from field you will get the current day and the last second of the day. If you use it in the to field you will get the from date and the last second of that day. Note that the timeZone parameter affects the date settings. "from": "endday" This sets the starting date to 08-10-2018, 23:59:59 UTC
"from" : 1515500531 (this timestamp corresponds to 01/09/2018 12:22:11 UTC)
"to": "endday" This sets the ending date to 01-09-2018, 23:59:59 UTC .
"from" : "endday"
"timeZone": "GMT+2" This sets the ending date to 08-10-2018, 23:59:59 GMT+2 (08-10-2018, 21:59:59 UTC)
"from" : 1515493331 (this timestamp corresponds to 01/09/2018, 12:22:11 GMT+2) "to": "endday"
"timeZone": "GMT+2" This sets the ending date to 01-09-2018 23:59:59 GMT+2 (01-09-2018, 21:59:59 UTC)
"from" : 1515452400 (this timestamp corresponds to 01/09/2018, 01:00:00 GMT+2) "to": "endday"
"timeZone" : "GMT+2 " This sets the ending date to 01-09-2018 23:59:59 GMT+2 (01-09-2018, 21:59:59 UTC)
|
endmonth
| If you use this in the from field you will get the last day of the current month and the last second of that day. If you use it in the to field, you will get last day of the month indicated in the date field and the last second of that day. Note that the timeZone parameter affects the date settings. "from": "endmonth" This sets the starting date to 31-10-2018, 23:59:59 UTC
"to": "endmonth" This sets the ending date to 30-09-2018, 23:59:59 UTC .
"from" : 1536150131 (this timestamp corresponds to 05/09/2018, 12:22:11 UTC) "to": "endmonth"
This sets the ending date to 30-09-2018, 23:59:59 UTC
"from" : 1536142931 (this timestamp corresponds to 05/09/2018, 12:22:11 GMT+2) "to": "endmonth"
"timeZone" : "GMT+2 " This sets the ending date to 30-09-2018 23:59:59 GMT+2 (30-09-2018, 21:59:59 UTC)
|
Days
Operator | Description |
---|
d
| Enter a number followed by d in the from parameter to substract N days from the current date. If you use it in the to field you will get the from date plus the indicated number of days. "from": "2d" This sets the starting date to 06-10-2018, 14:33:12 UTC
"from": 1536150131 (this timestamp corresponds to 05-09-2018, 12:22:11 UTC)
"to": "2d" This sets the ending date to 07-09-2018, 12:22:11 UTC
"from": "5d"
"to": "2d" This sets the starting date to 03-10-2018, 14:33:12 UTC and the ending date to 05-10-2018, 14:33:12 UTC
|
ad
| Enter a number followed by ad in the from parameter to subtract N days from the current date and set time to 00:00:00. If you use it in the to field you will get the from date plus the indicated number of days and set time to 00:00:00. Note that the timeZone parameter affects the date settings. "from": "2ad" This sets the starting date to 06-10-2018, 00:00:00 UTC
"from": 1536150131 (this timestamp corresponds to 05-09-2018, 12:22:11 UTC)
"to": "2ad" This sets the ending date to 07-09-2018, 00:00:00 UTC
"from":"5ad" "to": "2ad"
This sets the starting date to 03-10-2018, 00:00:00 UTC and the ending date to 05-10-2018, 00:00:00 UTC
"from" : 1536142931 (this timestamp corresponds to 05/09/2018, 12:22:11 GMT+2) "to": "2ad"
"timeZone" : "GMT+2 " This sets the ending date to 07-09-2018, 00:00:00 GMT+2 (06-09-2018, 22:00:00 UTC)
"from" : "5ad" "to": "2ad"
"timeZone" : "GMT+2 " This sets the starting date to 03-10-2018, 00:00:00 GMT+2 (02-10-2018, 22:00:00 UTC), and the ending date to 05-10-2018, 00:00:00 GMT+2 (04-10-2018, 22:00:00 UTC)
|
Hours
Operator | Description |
---|
h
| Enter a number followed by h in the from parameter to subtract N hours from the current time. If you use it in the to field you will get the from time plus the indicated number of hours. "from": "2h" This sets the starting date to 08-10-2018, 12:33:12 UTC
"from": "16h" This sets the starting date to 07-10-2018, 22:33:12 UTC
"from": 1536150131 (this timestamp corresponds to 05/09/2018, 12:22:11 UTC)
"to": "2h" This sets the ending date to 05-09-2018, 14:22:11 UTC
"from": "5h"
"to": "2h" This sets the starting date to 08-10-2018, 09:33:12 UTC and the ending date to 08-10-2018, 11:33:12 UTC
|
ah
| Enter a number followed by ah in the from parameter to subtract N hours from the current date at 00:00:00. If you use it in the to field you will add the indicated number of hours to the from date at 00:00:00. Note that the timeZone parameter affects the date settings. "from": "2ah" This sets the starting date to 07-10-2018, 22:00:00 UTC
"from" : "2ah"
"timeZone" : "GMT+2 " This sets the starting date to 07-10-2018, 22:00:00 GMT+2 (07-10-2018, 20:00:00 UTC)
"from" : 1536114131 (this timestamp corresponds to 05-09-2018, 02:22:11 UTC)
"to": "12ah" This sets the starting date to 07-10-2018, 22:00:00 GMT+2 (07-10-2018, 20:00:00 UTC)
"from" : 1536106931 (this timestamp corresponds to 05-09-2018, 12:22:11 GMT+2) "to": "12aH"
"timeZone" : "GMT+2 " This sets the ending date to 05-09-2018, 12:00:00 GMT+2 (05-09-2018, 10:00:00 UTC)
. "from" : "5ah"
"to" : "21ah " This sets the starting date to 07-10-2018, 19:00:00 UTC and the ending date to 07-10-2018, 21:00:00 UTC
|
Responses to your queries can be either returned to the source of the request or , forwarded to an an HDFS, S3, or SNMP, or Kafka type type system, or sent via email.
Given the different possible destinations for query responses, you can also specify the format in which you want the response to be sent. This is specified in the mode.type
parameter of the request body. The available response formats are:
...
The JSON response will include the following fields:
Field name | Type | Description |
---|
msg/error
| String | This describes the error in the case that the request was not successful. This field will be named msg or error depending on the type of error returned. The corresponding error code will be shown in the status field. Check the possible codes and corresponding messages below. |
status
| Integer | Numeric value that specifies the error code. When it shows 0 , it means no error occured. These are the possible error codes that you may get. The corresponding error descriptions will be displayed in the msg/error field. Also, when you get a 400 status code and the error Bad parameters , the object field will include more information about the specific error returned, as in the following example: {
"error": "Bad parameters",
"status": 400,
"timestamp": 1584033078759,
"cid": "XXXX",
"object": [
"405: Date from not valid or not found"
]
}
|
object
| JSON Object | This object contains the query result. The format of the object's content depends on the query data. |
cid
| String | An ID value to uniquely identify yourself across multiple systems. |
timestamp
| String | Indicates the moment when a certain event occurred. |
Example
Here is a response in JSON format that occurred without error.
...
- The
m
object lists the fields included in each query result along with their type
and index
metadata.
Field name | Description |
---|
type | The data type of the value returned. This will be one of:
timestamp - epoch value in milliseconds
str - string
int8 - 8-byte integer
int4 - 4-byte integer
bool - boolean
float8 - 8-byte floating point
|
index | An integer value that indicates the position of the field's value in the arrays returned in the object.d object.
|
- The
metadata
object gives information about the fields as an array, and includes the following fields:
Field name | Description |
---|
name | Name of the field. |
type | The data type of the value returned. This will be one of:
timestamp - epoch value in milliseconds
str - string
int8 - 8-byte integer
int4 - 4-byte integer
bool - boolean
float8 - 8-byte floating point
|
- The object
d
includes lightweight event info.
Example
Here is an example of a response in JSON/compact format that occurred without error:
...
- The
m
object lists the fields included in each query result along with their type
and index
metadata.
Field name | Description |
---|
type | The data type of the value returned. This will be one of:
timestamp - epoch value in millisecondsstr - stringint8 - 8-byte integerint4 - 4-byte integerbool - booleanfloat8 - 8-byte floating point
|
index | An integer value that indicates the position of the field's value in the arrays returned in the object.d object.
|
- The
metadata
object gives information about the fields as an array, and includes the following fields:
Field name | Description |
---|
name | Name of the field. |
type | The data type of the value returned. This will be one of:
timestamp - epoch value in millisecondsstr - stringint8 - 8-byte integerint4 - 4-byte integerbool - booleanfloat8 - 8-byte floating point
|
- The object
d
includes the array of values with the returned events data. Every row is a valid JSON object.
...