Both sides previous revision
Previous revision
Next revision
|
Previous revision
Next revision
Both sides next revision
|
en:mervis-scada:50-api [2018/11/06 12:57] m.chlupac |
en:mervis-scada:50-api [2020/04/27 12:45] m.chlupac [api/set/history] |
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]]. | 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 ===== | ===== List of basic API methods ===== |
| |
^Function^Description| | ^Function^Description| |
| |
^api/checkCredentials|| | ^api/checkCredentials|| |
^api/logout|| | ^api/logout|| |
| |
| |
===== Example ===== | ===== 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==== | ====api/get/history==== |
"cred":{ | "cred":{ |
"n":"demo", //username | "n":"demo", //username |
"p":"demo", //password | "p":"demo" //password |
"pe":0 | |
}, | }, |
"projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID | "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID |
<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"> | <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. | @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. | 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"> | <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1"> |
<n1:v>12761</n1:v> | <n1:v>12761</n1:v> |
</hv> | </hv> |
<!-- value without gt - ts and gt are equeal--> | <!-- value without gt - ts and gt are equal--> |
<hv ts="2018-11-06T09:22:03.9461503Z"> | <hv ts="2018-11-06T09:22:03.9461503Z"> |
<n1:v>12761</n1:v> | <n1:v>12761</n1:v> |
| |
| |
| ====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 |
| |
| <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> |
| |
| |
| ===== 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. |