Differences

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

--- en:mervis-scada:50-api [2020/04/06 13:16]
m.chlupac [api/set/history]
+++ en:mervis-scada:50-api [2024/05/08 10:42]
@@ Line 1: / Line 1: @@
-====== API ======
-Mervis SCADA offers open REST-like API based on JSON and XML data formats. For full description please contact our [[:en:help:support|technical support]].
-**Important:** Only officially supported response format is XML!
-===== List of basic API methods =====
-^Function^Description|
-^api/checkCredentials||
-^api/logout||
-^api/get/projects||
-^api/get/projectData||
-^api/get/projectByParts||
-^api/get/history||
-^api/get/history/specific||
-^api/set/history||
-^api/get/values||
-^api/get/alarms||
-^api/get/alarmHistory||
-^api/get/eventHistory||
-^api/get/changes||
-^api/set/executeActions||
-^api/set/values||
-^api/set/executeAlarmOps||
-^api/set/projectPriorityRefresh||
-^api/get/schema||
-^api/get/schema/datapoints||
-^api/get/schema/values||
-^api/get/schema/image||
-===== Example =====
-====api/checkCredentials====
-**Request**
-   * URL: /api/checkCredentials?format=xml
-   * Method: POST
-**Request**
-<code javascript>
-{"cred":{"n":"demo","p":"demo"}}
-</code>
-**Response**
-<code xml>
-<?xml version="1.0" encoding="utf-8"?>
-<checkCredentialsResult xmlns:r="http://dev.rcware.eu/serialization/references" d="GlobalDomain" l="demo" t="2:85be00d3-5875-4dec-a9b4-c98e2ff2acbe" xmlns="http://dev.rcware.eu/auth" />
-</code>
-  * You **should** use the received token **t** in subsequent API calls.
-====api/get/history====
-**Request**
-   * URL: /api/get/history?format=xml
-   * Method: POST
-<code javascript>
-{
-   "cred":{
-      "n":"demo", //username
-      "p":"demo" //password
-   },
-   "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID
-   "dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0",  //single datapoint ID
-   "from":"/Date(1541199600000)/", //UTC in ms
-   "to":"/Date(1541496190357)/",  //UTC in ms
-   "offset":0,
-   "count":5000,
-   "historyState":"" //client has to send historyState value from the last response with the following request
-}
-</code>
-**Response**
-<code xml>
-<?xml version="1.0" encoding="utf-8"?>
-<getHistoryResult xmlns:r="http://dev.rcware.eu/serialization/references" r:type="b133774d-21ce-42b6-add3-57c012079c55" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/history">
-  <!--
-  @Interval - ISO interval of trend values defined by the database client.
-  @historyState - to be copied into the next request
-  @nextValOfs - to be copied into the next request until value -1 is reached.
-  If ts of value in not within the interval time span after the previous value's gt - some data is missing.
-  -->
-  <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1">
-    <errMsg/>
-    <vals>
-      <!--ts - time stamp, gt - good through, value is valid in the whole time span between these two-->
-      <hv ts="2018-11-02T21:26:08.7936747Z" gt="2018-11-03T20:35:08.8060769Z">
-        <n1:v>12754</n1:v>
-      </hv>
-      <hv ts="2018-11-03T20:41:09.0100479Z" gt="2018-11-05T11:35:08.7415158Z">
-        <n1:v>12754</n1:v>
-      </hv>
-      <hv ts="2018-11-05T11:40:04.0077949Z" gt="2018-11-05T17:25:03.4285643Z">
-        <n1:v>12754</n1:v>
-      </hv>
-      <hv ts="2018-11-05T17:28:03.4133447Z" gt="2018-11-05T19:40:03.0246122Z">
-        <n1:v>12755</n1:v>
-      </hv>
-      <hv ts="2018-11-05T19:43:03.6499981Z" gt="2018-11-05T22:01:03.2620552Z">
-        <n1:v>12756</n1:v>
-      </hv>
-      <hv ts="2018-11-05T22:04:03.1530787Z" gt="2018-11-06T02:37:03.454926Z">
-        <n1:v>12757</n1:v>
-      </hv>
-      <hv ts="2018-11-06T02:40:03.61157Z" gt="2018-11-06T04:52:03.1759539Z">
-        <n1:v>12758</n1:v>
-      </hv>
-      <hv ts="2018-11-06T04:55:03.14511Z" gt="2018-11-06T06:40:03.8621601Z">
-        <n1:v>12759</n1:v>
-      </hv>
-      <hv ts="2018-11-06T06:43:03.2063072Z" gt="2018-11-06T08:55:03.3019409Z">
-        <n1:v>12760</n1:v>
-      </hv>
-      <hv ts="2018-11-06T08:58:03.083875Z" gt="2018-11-06T09:10:03.0695797Z">
-        <n1:v>12761</n1:v>
-      </hv>
-      <hv ts="2018-11-06T09:13:03.5389214Z" gt="2018-11-06T09:19:03.5238805Z">
-        <n1:v>12761</n1:v>
-      </hv>
-      <!-- value without gt - ts and gt are equal-->
-      <hv ts="2018-11-06T09:22:03.9461503Z">
-        <n1:v>12761</n1:v>
-      </hv>
-    </vals>
-  </hist>
-</getHistoryResult>
-</code>
-====api/set/history====
-**Request**
-   * URL: /api/set/history?format=xml
-   * Method: POST
-Attribute **i** sets **interval** ([[https://en.wikipedia.org/wiki/ISO_8601#Time_intervals|ISO 8601]]) in which the next value should be expected to be saved into a database.
-Even though there could be used name and password in **cred** - you should always use **token** to get the best performance.
-All date and time values are supposed to be in UTC.
-<code xml>
-<?xml version="1.0" encoding="UTF-8"?>
-<setHistoryRequest xmlns="http://dev.rcware.eu/scada/history"
-xmlns:n2="http://dev.rcware.eu/auth"
-xmlns:n1="http://dev.rcware.eu/scada/basic-props"
-projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0"
-dpId="e86dba6d-1250-4e7f-aafb-84fd28324710">
-  <n2:cred t="xxxxx"/><!-- token should be used here -->
-  <vals>
-    <hv ts="2020-03-15T11:00:00+00:00" i="P1D">
-      <n1:v>2.7</n1:v>
-    </hv>
-    <hv ts="2020-03-16T11:00:00+00:00" i="P1D">
-      <n1:v>3.0</n1:v>
-    </hv>
-    <hv ts="2020-03-17T11:00:00+00:00" i="P1D">
-      <n1:v>2.0</n1:v>
-    </hv>
-    <hv ts="2020-03-18T11:00:00+00:00" i="P1D">
-      <n1:v>2.3</n1:v>
-    </hv>
-  </vals>
-</setHistoryRequest></code>
-**Response**
-   * 200 OK
-====api/set/executeActions====
-**Request**
-   * URL: /api/set/executeActions?format=xml
-   * Method: POST
-<code xml>
-<?xml version="1.0" encoding="UTF-8"?>
-<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs"
-xmlns:n2="http://dev.rcware.eu/scada/basic-props"
-xmlns:n1="http://dev.rcware.eu/auth"
-xmlns:r="http://dev.rcware.eu/serialization/references">
-  <n1:cred n="userName" p="password"/>
-  <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">
-    <actions>
-      <actionDefItem propName="INIT" dpId="afc22e18-f8e4-4e08-899c-fb9e4759df3d">
-        <execParam r:type="495c9644-eed1-4b94-933b-3fae702a9aca">
-          <n2:value>16</n2:value>
-        </execParam>
-      </actionDefItem>
-      <actionDefItem propName="ZAP" dpId="34306c80-73f1-4465-ab51-2b2c1e85ab70">
-      </actionDefItem>
-    </actions>
-  </actionDefs>
-</executeActionsRequest></code>
-**Response**
-<code xml><?xml version="1.0" encoding="utf-8"?>
-<executeActionsResponse xmlns:r="http://dev.rcware.eu/serialization/references" code="Ok" message="OK" xmlns="http://dev.rcware.eu/scada/error-reporting" /></code>
-===== Matlab Client =====
-==== General notes client function parameters ====
-  * parameter names ID and Guid are used interchangeably in the Matlab client, it is always a universally unique identifier referring to project or a particular datapoint
-  * when plural is used, array of guids is expected (ie. {'guid1', 'guid2'}), otherwise just one guid is expected (ie. 'guid1')
-==== Data download example ====
-<code matlab>scada = ScadaClient('https://scada.mervis.info/','demo','demo');
-dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'};
-projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0';
-chartLegend = {'/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1','/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1 zpátečka','/Plynová kotelna/ÚT1 - SEVER/Poloha ventilu'};
-from = now - 4;
-to = now;
-timeSpan = 300; %sec
-[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan);
-plot(time,data);
-legend(chartLegend);
-datetick;</code>
-==== ScadaClient ====
-<code matlab>ScadaClient(url, username, password)</code>
-Constructor of Mervis API wrapper.
-==== findAllDPsWithReqTags ====
-<code matlab>findAllDPsWithReqTags(projIds, tags)</code>
-Returns list of datapoints based on tags query. Example of tags definition: {'label','indoor_air_temperature';'room_type','office'}
-==== saveData====
-<code matlab>saveData(projID, dpID, time, data)</code>
-Saves data into the Mervis database.
-==== deleteVariable ====
-<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code>
-Deletes data of one variable based on from - to interval. If from - to is not defined, all data are deleted. Use carefully, there is no undo!
-==== setDataPointValue ====
-<code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code>
-Sets data point value using a button (primary the INIT button). Only numerical values are supported. Parameter buttonName is not mandatory. Value 'INIT' is used if buttonName is not defined.
-{{ :en:mervis-scada:init.png?direct&800 |}}
-**Example:**
-<code matlab>
-dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f';
-projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa';
-buttonName = 'INIT' %see action ("button") name in Mervis SCADA GUI
-newValue = 1;
-scada = ScadaClient('https://scada.mervis.info/','username','password');
-scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
-</code>
-==== getData====
-<code matlab>[data, time, dataInCell, info] = getData(projID,dpsIds,from,to,span,zone,doublesInterpolationMethod, interpolate_gaps_shorter_than)</code>
-Downloads data. Span is a sampling interval in seconds, default is 300 sec. Zone is time zone 'local' or 'utc' is applied to from/to parameters as well as to output time, default is 'local'. DoubleInterpolationMethod is same as e.g. interp1, applied to double values only the other types use method 'previous'. Interpolate_gaps_shorter_than - interpolates missing values periodes that are not shorer than this parameter (in seconds). Return parameters: data - downloaded data resampled, NaN is used for missing values; time - datenum time axis according to selected zone; dataInCell - usefull for strings; info - summary info about the request.
-==== getDpTags====
-<code matlab>getDpTags(projectId, DpId) </code>
-Returns tags of the particular datapoint.
-==== getAllProjectDPs====
-<code matlab>getAllProjectDPs(projectGuid)</code>
-Returns project IDs and names that are accessible to logged user.