|
|
en:mervis-scada:50-api [2021/04/08 13:04] 127.0.0.1 external edit |
en:mervis-scada:50-api [2024/05/08 10:42] |
====== 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|| | |
| |
| |
| |
| |
===== Examples ===== | |
| |
====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 | |
* Content-Type: text/xml | |
| |
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 | |
* Content-Type: text/xml | |
| |
<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 t="xxxxxx"/> | |
<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> | |
| |
====api/get/values==== | |
| |
The right way how to retrieve current values of data points (property "Output" which is usually what you want) from one or multiple projects. | |
| |
**Request** | |
| |
* URL: /api/get/values?format=xml | |
* Method: POST | |
| |
<code javascript> | |
{ | |
"cred": { | |
"t": "xxxxxx" //token | |
}, | |
"propNamesToSerialize": ["Output"], | |
"offset": 0, | |
"count": 1000, | |
"serverState": null, | |
"dps": [{ | |
"projId": "ba1a92f7-f213-4a72-90e4-f7142b50274b", | |
"dpIds": ["e089dde2-a097-4e0d-8012-c8cf3dc62694", "1089dde2-a097-4e0d-8012-c8cf3dc62696"] | |
} | |
] | |
} | |
| |
</code> | |
| |
**Response** | |
| |
<code xml><?xml version="1.0" encoding="utf-8"?> | |
<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2020-04-07T07:46:34.850422Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints"> | |
<vals> | |
<v projId="ba1a92f7-f213-4a72-90e4-f7142b50274b" dataVersion="637217783110000000" serverTime="2020-04-07T07:46:34.850422Z"> | |
<dps> | |
<d id="e089dde2-a097-4e0d-8012-c8cf3dc62694" serAlr="true"> | |
<props> | |
<p n="Output" t="2020-04-07T07:43:42.1000676Z" q="Bad" r:type="177e726a-3180-4152-bef2-6254e7055e1f"> | |
<n1:v>ON</n1:v> | |
</p> | |
</props> | |
</d> | |
<d id="1089dde2-a097-4e0d-8012-c8cf3dc62696" serAlr="true"> | |
<props> | |
<p n="Output" t="2020-04-07T07:45:00.2408399Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55"> | |
<n1:v>0</n1:v> | |
</p> | |
</props> | |
</d> | |
</dps> | |
</v> | |
</vals> | |
</values></code> | |
| |
====api/get/projectByParts==== | |
| |
To get the list of datapoints. | |
| |
**Request** | |
| |
* URL: /api/get/projectByParts?format=xml | |
* Method: POST | |
| |
<code javascript> | |
{ | |
"cred": { | |
"t": "xxxxxx" | |
}, | |
"projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", | |
"treeId": "Visual tree", | |
"partType": 0, | |
"offset": 0, | |
"count": 250 | |
} | |
</code> | |
| |
**Response** | |
| |
<code xml><?xml version="1.0" encoding="utf-8"?> | |
<getProjectByPartsResult xmlns:r="http://dev.rcware.eu/serialization/references" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dataVersion="637305748282414171" totalCount="79" nextOffset="-1" xmlns:n1="http://dev.rcware.eu/scada/comm-props" xmlns:n2="http://dev.rcware.eu/rt2com" xmlns:n3="http://dev.rcware.eu/scada/basic-props" xmlns:n4="http://dev.rcware.eu/scada/legacy-props" xmlns="http://dev.rcware.eu/scada/datapoints"> | |
<dps> | |
<dp id="393df7b4-bb8d-4e8f-92a7-bf785508894a" n="Provozni podminky OK" canAct="true" canAlr="true"> | |
<v> | |
<props> | |
<p n="Source" t="2020-10-05T07:17:11.601879Z" q="Good" n1:dateTimeKind="UTC" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> | |
<n1:r n2:rp="PT0S" r:type="7b047602-40da-4095-9093-062ba30fd15e"> | |
<n2:a id="3b1e3b8b-2186-4dcf-b157-8032c768d1e1" n="SW.Provozni podminky OK"/> | |
</n1:r> | |
<n1:w r:type="5ddc9dbf-a6bd-458b-a6ab-f661db0e3a64"> | |
<n2:a id="3b1e3b8b-2186-4dcf-b157-8032c768d1e1" n="SW.Provozni podminky OK"/> | |
</n1:w> | |
<n1:v>1</n1:v> | |
</p> | |
<p n="Output" t="2020-10-05T07:16:58.751431Z" q="Good" r:type="177e726a-3180-4152-bef2-6254e7055e1f"> | |
<n3:v>OK</n3:v> | |
</p> | |
<p n="StdVis_V1" t="2015-06-03T13:17:13.5190205Z" q="Good" r:type="b0db7bd7-0375-4830-90f2-6d918bac41ee"> | |
<n3:v> | |
<n3:props> | |
<n3:p> | |
<n3:pn>Output</n3:pn> | |
<n3:props> | |
<n3:p r:type="256a44f6-32e4-4a75-b7c2-08eed38f151d"> | |
<n3:ordMap> | |
<n3:grOrd> | |
<n3:t>OK</n3:t> | |
<n3:o>0</n3:o> | |
</n3:grOrd> | |
<n3:grOrd> | |
<n3:t>ALARM</n3:t> | |
<n3:o>1</n3:o> | |
</n3:grOrd> | |
</n3:ordMap> | |
</n3:p> | |
</n3:props> | |
</n3:p> | |
</n3:props> | |
</n3:v> | |
</p> | |
</props> | |
</v> | |
<core r:type="2f04d90c-ee95-4cb6-b945-146e33021945"/> | |
</dp> | |
<dp id="3e5c0b88-45fd-4e3f-b1b2-1a365327ec90" n="Zaplavení" canAct="true" canAlr="true"> | |
<v> | |
<props> | |
<p n="Source" t="2020-08-17T10:21:46.470472Z" q="Good" n1:dateTimeKind="UTC" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> | |
<n1:r n2:rp="PT0S" r:type="7b047602-40da-4095-9093-062ba30fd15e"> | |
<n2:a id="45c31fe4-00b0-4498-b9f6-adfe6a2fe34b" n="SW.Zaplavení mem"/> | |
</n1:r> | |
<n1:w r:type="5ddc9dbf-a6bd-458b-a6ab-f661db0e3a64"> | |
<n2:a id="45c31fe4-00b0-4498-b9f6-adfe6a2fe34b" n="SW.Zaplavení mem"/> | |
</n1:w> | |
<n1:v>0</n1:v> | |
</p> | |
<p n="Output" t="2020-08-17T10:21:46.470472Z" q="Good" r:type="177e726a-3180-4152-bef2-6254e7055e1f"> | |
<n3:v>OK</n3:v> | |
</p> | |
<p n="StdVis_V1" t="2015-06-03T13:17:13.5190205Z" q="Good" r:type="b0db7bd7-0375-4830-90f2-6d918bac41ee"> | |
<n3:v> | |
<n3:props> | |
<n3:p> | |
<n3:pn>Output</n3:pn> | |
<n3:props> | |
<n3:p r:type="256a44f6-32e4-4a75-b7c2-08eed38f151d"> | |
<n3:ordMap> | |
<n3:grOrd> | |
<n3:t>OK</n3:t> | |
<n3:o>0</n3:o> | |
</n3:grOrd> | |
<n3:grOrd> | |
<n3:t>ALARM</n3:t> | |
<n3:o>1</n3:o> | |
</n3:grOrd> | |
</n3:ordMap> | |
</n3:p> | |
</n3:props> | |
</n3:p> | |
</n3:props> | |
</n3:v> | |
</p> | |
</props> | |
</v> | |
<core r:type="2f04d90c-ee95-4cb6-b945-146e33021945"/> | |
<alr> | |
<def enabled="true" delay="PT1M"/> | |
<galrs/> | |
<status user="SYSTEM" incidentId="88ba7198-de57-4854-8130-60c240a09522" lastChangeTime="2020-08-11T12:37:04.8002341Z"/> | |
</alr> | |
</dp> | |
</dps> | |
</getProjectByPartsResult></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. | |