This article will guide you through retrieving event logs from BioStar 2 server via BioStar 2 API.
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, you can learn how to call an API function to retrieve the log data within a specific timeframe.
This article also includes a sample code of a C# program that incorporates the API, and also 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
[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','server_datetime'] 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
[Request Body Example]
{ "Query": { "limit": 100, "conditions": [ { "column": "datetime", "operator": 3, "values": [ "2021-08-01T15:00:00.000Z", "2021-08-02T14:59:59.000Z" ] } ] } } |
* "limit" : 100 indicates that you’d only see 100 logs in the response as a result of the API call.
* Please set this value accordingly since retrieving a large amount of data can cause delays or server crashes. (Recommended Max. limit: 2,000)
* "conditions" : in the example above, it's filtering the logs by 'datetime (column : datetime)' by retrieving the logs that occurred 'between (operator - 3)' 2021-08-01T15:00:00.000Z and 2021-08-02T14:59:59.000Z (from "values").
So in this case, you’ll only see the logs from 2021-08-01T15:00:00.000Z to 2021-08-02T14:59:59.000Z.
* If you change the "column" to "id" or other values, it will filter the logs by their id or other values accordingly.
[Response: Successful]
{ "EventCollection": { "rows": [ { "id": "133", "server_datetime": "2021-08-02T13:08:27.00Z", "datetime": "2021-08-02T04:08:30.00Z", "index": "346", "user_group_id": { "id": "0", "name": "" }, "device_id": { "id": "939271697", "name": "BioStation A2 939271697 (192.168.13.132)" }, "event_type_id": { "code": "20736" }, "door_id": [ { "id": "4", "name": "Door1" } ], "is_dst": "0", "timezone": { "half": "0", "hour": "9", "negative": "0" }, "user_update_by_device": "false", "hint": "162787731009392716970000000346", "user_id": { "photo_exists": "false" } }, . |
*
"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 3. Console Retrieve Logs Example
This is a sample of Visual C# console application made for those who might need some guide for integrating the BioStar 2 New Local API.
You can simply copy & paste the source code to use the same function in your own integration.
[Retrieve Logs Method Source Code]
static async void GetLogTask() { if(sessionID == null) { Console.WriteLine("You must log in first!"); return; }
CookieContainer cookieContainer = new CookieContainer();
HttpClientHandler handler = new HttpClientHandler(); handler.CookieContainer = cookieContainer;
HttpClient httpClient = new HttpClient(handler);
HttpClient client = new HttpClient(handler); httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID); cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID)); string resourceAddress = "https://127.0.0.1/api/events/search"; Console.WriteLine("How many results do you want to see?"); string limit = Console.ReadLine(); string startTime = "1970-01-01T00:00:00Z"; string endTime = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");
DateTime dtLatestLogTime = new DateTime(1970, 1, 1);
JavaScriptSerializer serializer = new JavaScriptSerializer();
string payload2 = "{ \"Query\": { \"limit\": " + limit + ", \"conditions\": [ { \"column\": \"datetime\", \"operator\": 3, \"values\": [ \"" + startTime + "\", \"" + endTime + "\" ] } ] }}"; Console.WriteLine(payload2);
StringContent sc = new StringContent(payload2, Encoding.UTF8, "application/json"); HttpResponseMessage httpResponse = httpClient.PostAsync(resourceAddress, sc).Result;
if (httpResponse.IsSuccessStatusCode == true) { Console.WriteLine("Succeeded to retrieve log from " + startTime + " to " + endTime); string httpResponseBody = await httpResponse.Content.ReadAsStringAsync(); //Console.WriteLine(httpResponseBody); dynamic obj = JsonConvert.DeserializeObject(httpResponseBody); Console.WriteLine("************** LOG("+limit+") : **************"); Console.WriteLine("** LogID ********* DateTime *********** DeviceID ******************** DeviceName ********************* EventCode *****"); for (int i = 0; i < Int16.Parse(limit); i++) { Console.WriteLine(obj.EventCollection.rows[i].id + " " + obj.EventCollection.rows[i].datetime + " " + obj.EventCollection.rows[i].device_id.id + " " + obj.EventCollection.rows[i].device_id.name + " " + obj.EventCollection.rows[i].event_type_id.code); } System.Threading.Thread.Sleep(1000); } else { Console.WriteLine("Log Retrieval Failed from " + startTime + " to " + endTime); Console.WriteLine(httpResponse.ToString()); }
} |
[After Retrieve Logs Successfully: only managed to see a few values of the logs]
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: body]
Part 5. Retrieve Logs via Swagger (Video Example)
FAQ
1. How can we know the event type code if I want to add condition for "event_type_id.code" ?
- You can call GET /api/event_types to view a list of event types recorded on BioStar 2 database.
Please refer to the following link for more information on this API : View Event Types API Documentation