Differences

This shows you the differences between two versions of the page.

--- access_via_api [2020/04/07 10:05] – [Getting graph data] emozolyak
+++ access_via_api [2022/01/26 10:03] – atolstov
@@ Line 1: / Line 1: @@
+<WRAP center round tip 60%>There is Excel VBA scripts codes example [[example_of_data_access_from_excel_via_api|here]]</WRAP>
 ====== Using API ======
@@ Line 25: / Line 28: @@
   Content-Type: application/json
+<WRAP center round important 60%>
+Note that, if you are using another WebHMI as client (via [[Lua_API|cURL Lua]]'s library), the following line should be removed
+  Accept-Encoding: gzip, deflate, sdch
+</WRAP>
 Example of a connection list request:
@@ Line 518: / Line 526: @@
 }
 </code>
+==== Register's attributes ====
 ^ Register's attributes: ^^^
 |**id**|	int 	 | Unique register id |
@@ Line 609: / Line 617: @@
 |3|Double Word |
 |4|Unix Time |
+|5|String |
 ^Storage formats identifiers:^^
@@ Line 1238: / Line 1248: @@
 |min_val	|double	|Minimal value of the Y axis|
 |max_val	|double	|Maximal value of the Y axis|
+===== Alert list =====
+To get a list of all alerts, you must perform a GET request on the URL like this: http://192.168.1.1/api/alerts.
+To obtain information about a particular alert, you must perform a following GET request on a URL 'http://192.168.1.1/api/alerts/1' . Here "1" is the ID of the desired alert.
+In the headers, it is necessary to pass API key. For example:
+  X-WH-APIKEY: F3C74230818DA487BB2017CE5D0290F4DABCAFD7
+Also, in the headers, you must specify the desired data exchange format. Currently, only the JSON format is supported.
+  Accept: application/json
+  Content-Type: application/json
+Example of query for the full graph list:
+  ***URL:** http://192.168.1.1/api/alerts
+  ***Method:** GET
+  *Headers:
+  Accept: application/json
+  Content-Type: application/json
+  Accept-Encoding: gzip, deflate, sdch
+  X-WH-APIKEY: F3C74230818DA487BB2017CE5D0290F4DABCAFD7
+Reply example:
+<code>
+[
+    {
+        "id": "1",
+        "title": "a1",
+        "description": "<p>my alert</p>",
+        "image": "",
+        "level": "0",
+        "sound": "0",
+        "canack": "1",
+        "dict_id": "",
+        "condition": "[{\"condition\":\"moreThan\",\"regId\":1,\"min\":\"0\",\"max\":\"\",\"bitNum\":\"\",\"state\":\"\",\"value\":\"\"}]",
+        "category": "",
+        "group_id": ""
+    },
+    {
+        "id": "2",
+        "title": "a2",
+        "description": "<p>my alert</p>",
+        "image": "",
+        "level": "0",
+        "sound": "0",
+        "canack": "1",
+        "dict_id": "",
+        "condition": "[{\"condition\":\"moreThan\",\"regId\":1,\"min\":\"0\",\"max\":\"\",\"bitNum\":\"\",\"state\":\"\",\"value\":\"\"}]",
+        "category": "",
+        "group_id": ""
+    }
+]
+</code>
+<WRAP center round info 60%>
+To get information about currently active alerts, you can use [[current_alerts?s[]=getcurrentalerts |GetCurrentAlerts]] function and copying its output to some register (and then use GET method for current register's values).
+</WRAP>
 ===== Image list =====
@@ Line 1296: / Line 1370: @@
 |title	|string	|Image name|
-===== Getting meters log =====
+===== Getting graph data =====
-There is an option to use some registers as totalizers of resources, like heat, water, electricity etc. Then  each hour the register current values and hourly consumption values will be stored in the log.
+To get data from graph log, it is necessary to run following GET-query for URL http://192.168.1.1/api/graph-data/2. Here 2 - is the ID of the graph of interest.
-To obtain entries from the meters, you must perform follwing GET request on a URL
+Also, instead of specifying the graph ID, you can send the X-WH-REGISTERS header. It specifies, through the comma, the ID of the registers for which data is to be extracted. Example:
-  http://192.168.1.1/api/meters-log
-In the request headers, it is necessary to pass the API key, the boundaries of the time interval of interest, and a list of register identifiers. X-WH-START and X-WH-END are transmitted in UnixTime format. The register ID is passed by a comma-separated list in the X-WH-REGISTERS header. For example:
+  X-WH-REGISTERS: 23,12,4
+In the request headers, you must pass the API key, the boundaries of the time interval of interest (X-WH-START, X-WH-END) and the number of values (X-WH-SLICES). X-WH-START and X-WH-END are transmitted in UnixTime format. For example:
   X-WH-APIKEY: F3C74230818DA487BB2017CE5D0290F4DABCAFD7
-  X-WH-START: 1422595501
+  X-WH-START: 1422797440
-  X-WH-END: 1422599101
+  X-WH-END: 1422997405
-  X-WH-REGISTERS: 8,10 ?? check this
+  X-WH-SLICES: 300
-Also, in the headers, you must specify the desired data exchange format. Currently, only the JSONformat is supported.
+X-WH-SLICES is the number of values. The time interval X-WH-START-X-WH-END will be divided into X-WH-SLICES of equal intervals and the system will take the most detailed values for each of them.
+X-WH-SLICES should be chosen based on the necessary detail of the graph. So, if you need to build a graph 800 pixels wide, then it makes no sense to choose more than 800 values from the log. And sometimes there will be enough 200-400 values depending on the width of the line on the graph.
+To speed up the operation, the system can store the averaged values of the registers for different intervals (1 minute, 2 minutes, 5 minutes, 15 minutes, 1 hour). In the configuration of each register, you can specify the required detail of the stored data. Depending on the selected time interval and the number of values, the system will attempt to take data from the most appropriate table of averaged values. or from the register register (if it is included for the specified register)
+Also, in the headers, you must specify the desired data exchange format. Currently, only the JSON format is supported.
   Accept: application/json
   Content-Type: application/json
+Example of getting data for graph #1:
-Example of querying records from the register log:
+  ***URL:** http://192.168.1.1/api/graph-data/1
+  ***Method:** GET
-  ***URL**: http://192.168.1.1/api/register-log
+  *Headers:
-  ***Method**: GET
-  *Header:
   Accept: application/json
@@ Line 1325: / Line 1405: @@
   Accept-Encoding: gzip, deflate, sdch
   X-WH-APIKEY: F3C74230818DA487BB2017CE5D0290F4DABCAFD7
-  X-WH-START: 1422595501
+  X-WH-START: 1422854081
-  X-WH-END: 1422599101
+  X-WH-END: 1422856235
-  X-WH-REGISTERS: 8,10
+  X-WH-SLICES: 20
-Reply example:
+Response example:
 <code>
-{
+[
-  "1422598266": [
+  {
-    {
+    "8": "NaN;NaN;NaN",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "6",
+    "16": "NaN;NaN;NaN",
-      "s": "-1"
+    "x": 1422861065000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "NaN;NaN;NaN",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "NaN;NaN;NaN",
-    }
+    "x": 1422861173000
-  ],
+  },
-  "1422598271": [
+  {
-    {
+    "8": "NaN;NaN;NaN",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "11",
+    "16": "NaN;NaN;NaN",
-      "s": "-1"
+    "x": 1422861281000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "NaN;NaN;NaN",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "NaN;NaN;NaN",
-    }
+    "x": 1422861388000
-  ],
+  },
-  "1422598276": [
+  {
-    {
+    "8": "0.000000;9.292714;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "16",
+    "16": "0.000000;0.674894;1.000000",
-      "s": "-1"
+    "x": 1422861496000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.489933;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.742101;1.000000",
-    }
+    "x": 1422861604000
-  ],
+  },
-  "1422598280": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "0",
+    "16": "0.000000;0.747650;1.176471",
-      "s": "-1"
+    "x": 1422861711000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.748471;1.176471",
-    }
+    "x": 1422861819000
-  ],
+  },
-  "1422598285": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "5",
+    "16": "0.000000;0.746659;1.176701",
-      "s": "-1"
+    "x": 1422861927000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.755068;1.176932",
-    }
+    "x": 1422862034000
-  ],
+  },
-  "1422598290": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "10",
+    "16": "0.000000;0.741844;1.000000",
-      "s": "-1"
+    "x": 1422862142000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.740291;1.000000",
-    }
+    "x": 1422862250000
-  ],
+  },
-  "1422598295": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "15",
+    "16": "0.000000;0.756320;1.176701",
-      "s": "-1"
+    "x": 1422862358000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.746004;1.176471",
-    }
+    "x": 1422862465000
-  ],
+  },
-  "1422598300": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "0",
+    "16": "0.000000;0.754233;1.176932",
-      "s": "-1"
+    "x": 1422862573000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.740343;1.000000",
-    }
+    "x": 1422862681000
-  ],
+  },
-  "1422598305": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "5",
+    "16": "0.000000;0.751393;1.176932",
-      "s": "-1"
+    "x": 1422862788000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.750868;1.176932",
-    }
+    "x": 1422862896000
-  ],
+  },
-  "1422598310": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "10",
+    "16": "0.000000;0.745956;1.176701",
-      "s": "-1"
+    "x": 1422863004000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.758306;1.176932",
-    }
+    "x": 1422863111000
-  ],
+  },
-  "1422598315": [
+  {
-    {
+    "8": "0.000000;9.500000;19.000000",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "15",
+    "16": "0.000000;0.741780;1.000000",
-      "s": "-1"
+    "x": 1422863219000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "0.000000;9.500000;19.000000",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "0.000000;0.741780;1.000000",
-    }
+    "x": 1422863327000
-  ],
+  },
-  "1422598320": [
+  {
-    {
+    "8": "NaN;NaN;NaN",
-      "r": 8,
+    "10": "NaN;NaN;NaN",
-      "v": "0",
+    "16": "NaN;NaN;NaN",
-      "s": "-1"
+    "x": 1422863435000
-    },
+  },
-    {
+  {
-      "r": 10,
+    "8": "NaN;NaN;NaN",
-      "v": "",
+    "10": "NaN;NaN;NaN",
-      "s": ""
+    "16": "NaN;NaN;NaN",
-    }
+    "x": 1422863542000
-  ],
+  }
-  "1422598325": [
-    {
-      "r": 8,
-      "v": "5",
-      "s": "-1"
-    },
-    {
-      "r": 10,
-      "v": "",
-      "s": ""
-    }
-  ],
-  "1422598330": [
-    {
-      "r": 8,
-      "v": "10",
-      "s": "-1"
-    },
-    {
-      "r": 10,
-      "v": "",
-      "s": ""
-    }
-  ],
-  "1422598335": [
-    {
-      "r": 8,
-      "v": "15",
-      "s": "-1"
-    },
-    {
-      "r": 10,
-      "v": "",
-      "s": ""
-    }
-  ],
-  "1422598340": [
-    {
-      "r": 8,
-      "v": "0",
-      "s": "-1"
-    },
-    {
-      "r": 10,
-      "v": "",
-      "s": ""
-    }
-  ],
-  "1422598345": [
-    {
-      "r": 8,
-      "v": "5",
-      "s": "-1"
-    },
-    {
-      "r": 10,
-      "v": "",
-      "s": ""
-    }
-  ],
-  и т.д.
 ]
 </code>
-Returns the array, where the index is time in UnixTime format. Elements of the array have another array of objects.
+The structure of the returned data is as follows. An array of objects is returned. Each object has an attribute 'x' - this is the timestamp of this entry. The time format is UnixTime multiplied by 1000 (the dimension is milliseconds).
-Each object has three properties: r, v, s.
+Also in this object there are attributes with values for each register. The attribute name is the register ID. The attribute value is a string where the minimum, average and maximum value of the register on this interval is combined through a semicolon. For example, '0.000000; 0.755068; 1.176932' means that the register took values from 0 to 1.176932, with its arithmetic mean being 0.755068. If in the given interval there is no data on the value of this register, the system will return 'NaN; NaN; NaN'.
-^r|is the register ID. For example, 10 |
-^v|is the value of the register at the specified time point or an empty string if there is no data for this register at this time. |
-^s|is the state of the register that matched it at the specified time: |
-| -1|Unknown |
-| 0|Disabled |
-| 1|Normal |
-| 2|Warning |
-| 3|Alert |
-| '' (an empty string)|there is no register value. |
 ===== Event list =====
@@ Line 1690: / Line 1698: @@
   Content-Type: application/json
-Consider an example of two events. Event number 1 is the parent event. It starts on the 5th second of every minute and ends on the 40th second of every minute. The log records data once for the entire event. The time of the beginning of the event and the last value of the interval register I60 are recorded in the log. Screenshots illustrate the setting of this event.
-{{::api_ev_1_example.png?direct}}
-{{::api_ev_1_example_actions.png?direct}}
-The second event is the child event for the first event. Therefore, it can only be executed when the first event is executed. In addition, the condition is limited so that it starts at the 25th second of every minute and ends at the 35th. Data for it is written to the log every 2 seconds. The current value of the I60 register is written to the log. Screenshots illustrate the setting of this event.
-{{::api_ev_child_1.png?direct}}
-{{::api_ev_child_2.png?direct}}
+<WRAP center round info 80%>
+Please refer for [[events]] chapter for more information.
+</WRAP>
-{{::api_ev_child_3.png?direct}}
 Example of getting date about event #1:
@@ Line 2273: / Line 2273: @@
 If the request is valid, API will return HTTP-code 200.
+===== Getting meters log =====
+There is an option to use a register as a tolalizers for resources like water, has, heat, electricity etc. Then its current value together with hourly consumption will be stored in the database.
+To obtain entries from the meters log, you must perform follwing GET request on a URL http://192.168.1.1/api/meters-log.
+In the request headers, it is necessary to pass the API key, the boundaries of the time interval of interest, X-WH-START and X-WH-END are transmitted in UnixTime format. All meter registers will be returned, so X-WH-REGISTER header is omitted. For example:
+  X-WH-APIKEY: F3C74230818DA487BB2017CE5D0290F4DABCAFD7
+  X-WH-START: 1422595501
+  X-WH-END: 1422599101
+Also, in the headers, you must specify the desired data exchange format. Currently, only the JSON format is supported.
+  Accept: application/json
+  Content-Type: application/json
+Example of querying records from the register log:
+  ***URL**: http://192.168.1.1/api/meters-log
+  ***Method**: GET
+  ***Headers**:
+  Accept: application/json
+  Content-Type: application/json
+  Accept-Encoding: gzip, deflate, sdch
+  X-WH-APIKEY: F3C74230818DA487BB2017CE5D0290F4DABCAFD7
+  X-WH-START: 1422595501
+  X-WH-END: 1422599101
+Reply example:
+<code>
+[
+  {
+    "t": 1586253600, // timestamp
+    "r": 65,         // register id
+    "s": "0.0",      // hour start value
+    "e": "5.0",      // hour end value
+    "v": "5.0"       // difference
+  },
+  {
+    "t": 1586257200,
+    "r": 65,
+    "s": "5.0",
+    "e": "20.0",
+    "v": "15.0"
+  },
+  {
+    "t": 1586257200,
+    "r": 76,
+    "s": "100.0",
+    "e": "200.0",
+    "v": "100.0"
+  }
+]
+</code>
+The %%//%% are comments, they are absent in the real reponse.
+====== API usage examples ======
+    * [[example_of_data_access_from_excel_via_api|Data access from Excel]]
+    * [[example_of_data_access_from_c_c|Data access from C/C++]]
+    * [[google_sheet_api_example|Data access from the Google Sheets]]
+    * [[Android demo application]]
+    * [[Android application via Chrome]]