This article will guide you through retrieving event logs that is sorted via BioStar 2 API.
* From BioStar v2.7.14, it supports sorting the event logs by "datetime" in a specific order (ascending/descending).
You can find a more detailed introduction to BioStar 2 New Local API in this article : [BioStar 2 API] How To Use BioStar 2 New Local API
In this article, we'll guide you on how to call an API to retrieve the log data that is sorted by the way you define.
* Currently, log data can be sorted by 'datetime' or 'id'.
'id' refers to the index of the server log table. This index will start from 1 for every new log table in the server (for each month).
This article also includes an example of API call made via Postman, a program used for building & testing RESTful API calls.
Part 1. API Call & Parameters
[POST]: /events/search
You can also find information regarding this API in the following link : Search Events API Documentation
[Body Parameters]
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | Number | Y | Limit the response records by the value stated on this parameter |
| conditions | Array | N | Array of conditions |
| :column | String | Field which the conditions will be based from. ['datetime','device_id.id','door_id.id','event_type_id.code', 'user_group_id.id','user_id.user_id'] Required if you want to add conditions | |
| :operator | Number | Condition Operator EQUAL : 0, NOT_EQUAL : 1, CONTAINS : 2, BETWEEN : 3, LIKE : 4, GREATER : 5, LESS : 6 For field encrypted in encryption mode (ex. user_id.user_id), it only supports Equal (0), Not Equal (1), and Contains(2). Required if you want to add conditions | |
| :values | String Array | Value for the conditions. (If condition is for 'datetime', datetime needs to be in UTC ISO-8601 format. ex: 2015-06-10T02:14:05.268Z ) Required if you want to add conditions | |
| orders | N | sort logs. | |
| :column | String | Field which the sorting will be based on Required if you want to add orders | |
| :descending | Boolean | Toggle true to set the sorting as descending Required if you want to add orders |
Part 2. Request Body & Response Model
Example : Retrieve logs between specific datetime (conditions) and sort it in ascending order by 'id'
[Request Body]
{ "Query": { "limit" : 2, "conditions": [ { "column": "datetime", "operator": 3, "values": [ "2024-07-15T00:00:00.000Z", "2024-07-16T16:59:59.000Z" ] } ], "orders" : [ { "column" : "id", "descending" : false } ] } } |
In this example, the "conditions" filters the logs so that you’d only see the logs from the period of time between first value(time) and the second value(time).
"Orders" sorts the log data to be in the ascending order of each log’s id value.
* If you change the "column" value of "orders" to other values, you can sort the logs by other values as well.
For example, instead "id", if you put "datetime", you can order it in ascending/descending order by datetime.
[Response]
{ "EventCollection": { "rows": [ { "id": "29", "server_datetime": "2024-07-16T09:58:37.00Z", "datetime": "2024-07-15T00:02:33.00Z", "index": "2466", "user_group_id": { "id": "0", "name": "" }, "device_id": { "id": "543458315", "name": "X-Station 2 543458315 (192.168.40.47)" }, "event_type_id": { "code": "15360" }, "is_dst": "0", "timezone": { "half": "1", "hour": "4", "negative": "0" }, "user_update_by_device": "false", "hint": "172100175305434583150000002466", "user_id": { "photo_exists": "false" } }, { "id": "30", "server_datetime": "2024-07-16T09:58:37.00Z", "datetime": "2024-07-15T00:04:54.00Z", "index": "2467", "user_group_id": { "id": "0", "name": "" }, "device_id": { "id": "543458315", "name": "X-Station 2 543458315 (192.168.40.47)" }, "event_type_id": { "code": "15104" }, "is_dst": "0", "timezone": { "half": "1", "hour": "4", "negative": "0" }, "user_update_by_device": "false", "hint": "172100189405434583150000002467", "user_id": { "photo_exists": "false" } } ] }, "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
In the response, you can see that the response has two logs that are in ascending order of the id within the datetime specified.
The first log has id of 29 and the second log has id of 30.
Additional Notes :
* Please note that there might be logs that have the same id value. It is because the log data are stored in different data tables that are for each month of each year. For instance, there can be 2 logs with the same id value but from different log tables for August & September of 2021.
* "server_datetime" refers to the timestamp when the logs from the device get synchronized to the server. "datetime" refers to the timestamp when the event actually occurs on the device.
"timezone" holds information regarding the timezone set in the device of which the log occurred.
To find more information regarding these values, please refer to the following article :
[BioStar 2 API] How to Interpret Time in Device Timezone from Event Log API
Part 4. Retrieve Logs via Postman
[Request Example: Headers]
*You must use the ‘be-session-id’ value from the response header of the Login API call to authenticate API use for other API calls.
[Request Example]
[Response Example]
