Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
en:mervis-scada:50-api [2017/06/29 11:23] m.chlupac [Example] |
en:mervis-scada:50-api [2025/02/27 11:43] (current) v.kohout [api/get/projectByParts] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== API ====== | ====== API ====== | ||
| - | Mervis SCADA offers open REST API based on JSON and XML data formats. For full description please contact our [[: | + | Mervis SCADA offers open REST-like API based on JSON and XML data formats. For full description please contact our [[: |
| - | ===== Example | + | **Important: |
| + | ===== List of basic API methods | ||
| - | **Request: GetHistoryRequest** | + | ^Function^Description| |
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| + | ^api/ | ||
| - | * URL: / | ||
| - | <sxh json> | + | |
| + | |||
| + | ===== Examples ===== | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | |||
| + | <code javascript> | ||
| + | {" | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | </ | ||
| + | |||
| + | * You **should** use the received token **t** in subsequent API calls. | ||
| + | |||
| + | |||
| + | |||
| + | ==== api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * Downloading of one or multiple trends with single API call | ||
| + | * You should always use " | ||
| + | * " | ||
| + | * " | ||
| + | * Items: " | ||
| + | |||
| + | |||
| + | <code javascript> | ||
| { | { | ||
| - | | + | |
| - | "projId":" | + | |
| - | "dpId":" | + | }, |
| - | "providerId":" | + | " |
| - | "from":"/ | + | " |
| - | " | + | " |
| + | " | ||
| + | | ||
| + | "series": | ||
| + | { | ||
| + | | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | | ||
| + | "dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | * Empty " | ||
| + | * " | ||
| + | * Values | ||
| + | * v - value | ||
| + | * ts - timestamp - start of the value validity period | ||
| + | * gt - goodthrough - end of the value validity period | ||
| + | * i - interval, only present if it differs from the interval in Meta section | ||
| + | * Meta | ||
| + | * type - value type - double, string, datetime | ||
| + | * unit - unit | ||
| + | * interval - expected interval between the stored records. Useful to identify missing data. | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | ] | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | |||
| + | |||
| + | </ | ||
| + | |||
| + | **Demo** | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | |||
| + | </code> | ||
| + | |||
| + | ==== api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * You should always use token (" | ||
| + | * " | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | * " | ||
| + | |||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| " | " | ||
| - | " | + | " |
| - | "historyState":"" | + | "dataSpec":2, |
| + | " | ||
| + | " | ||
| } | } | ||
| - | </sxh> | + | </code> |
| **Response** | **Response** | ||
| - | <sxh xml> | + | * Values |
| + | * v - value | ||
| + | * ts - timestamp - start of the value validity period | ||
| + | * gt - goodthrough - end of the value validity period | ||
| + | * i - interval | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ], | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | |||
| + | </ | ||
| + | |||
| + | ==== [Depricated] api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| < | < | ||
| - | <hist projId=" | + | |
| + | @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' | ||
| + | |||
| + | --> | ||
| + | | ||
| < | < | ||
| < | < | ||
| - | <hv ts="2017-05-08T22:26:53.32684Z" gt="2017-05-08T22:31:53.465467Z"> | + | |
| - | < | + | |
| + | < | ||
| </hv> | </hv> | ||
| - | <hv ts="2017-05-08T22:36:53.283875Z"> | + | <hv ts="2018-11-03T20:41:09.0100479Z" |
| - | < | + | < |
| </hv> | </hv> | ||
| - | <hv ts="2017-05-08T22:41:53.435042Z"> | + | <hv ts="2018-11-05T11:40:04.0077949Z" |
| - | < | + | < |
| </hv> | </hv> | ||
| - | <hv ts="2017-05-08T22:46:53.711496Z" gt="2017-05-08T23:36:53.776657Z"> | + | <hv ts="2018-11-05T17:28:03.4133447Z" gt="2018-11-05T19:40:03.0246122Z"> |
| - | < | + | < |
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <!-- value without gt - ts and gt are equal--> | ||
| + | <hv ts=" | ||
| + | < | ||
| </hv> | </hv> | ||
| - | |||
| </ | </ | ||
| </ | </ | ||
| Line 48: | Line 476: | ||
| - | </sxh> | + | </code> |
| + | ====api/ | ||
| + | **Request** | ||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * Content-Type: | ||
| + | Attribute **i** sets **interval** ([[https:// | ||
| + | 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=" | ||
| + | < | ||
| + | xmlns: | ||
| + | xmlns: | ||
| + | projId=" | ||
| + | dpId=" | ||
| + | <n2:cred t=" | ||
| + | < | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | * 200 OK | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * Content-Type: | ||
| + | |||
| + | Attribute **i** sets **interval** ([[https:// | ||
| + | |||
| + | 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=" | ||
| + | < | ||
| + | xmlns: | ||
| + | xmlns: | ||
| + | projId=" | ||
| + | dpId=" | ||
| + | from=" | ||
| + | to=" | ||
| + | <n2:cred t=" | ||
| + | < | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | * 200 OK | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * Content-Type: | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | xmlns: | ||
| + | xmlns: | ||
| + | xmlns: | ||
| + | <n1:cred t=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml><? | ||
| + | < | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * Content-Type: | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | <values projId=" | ||
| + | <dps> | ||
| + | <d id=" | ||
| + | < | ||
| + | <p n=" | ||
| + | < | ||
| + | </p> | ||
| + | </ | ||
| + | </d> | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml><? | ||
| + | < | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | The right way how to retrieve current values of data points (property " | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| <code javascript> | <code javascript> | ||
| { | { | ||
| - | " | + | " |
| - | " | + | " |
| - | | + | }, |
| - | | + | " |
| - | | + | " |
| - | | + | "count": 1000, |
| - | | + | " |
| - | " | + | " |
| - | " | + | " |
| - | "count":5000, | + | " |
| - | " | + | } |
| + | ] | ||
| } | } | ||
| + | |||
| </ | </ | ||
| **Response** | **Response** | ||
| - | <code xml> | + | <code xml><? |
| - | <getHistoryResult | + | <values |
| - | <hist projId=" | + | <vals> |
| - | <errMsg/> | + | <v projId=" |
| - | <vals> | + | < |
| - | <hv ts="2017-05-08T22:26:53.32684Z" | + | <d id="e089dde2-a097-4e0d-8012-c8cf3dc62694" |
| - | < | + | |
| - | </hv> | + | <p n=" |
| - | <hv ts="2017-05-08T22: | + | |
| - | <n1: | + | </p> |
| - | </hv> | + | |
| - | <hv ts="2017-05-08T22:41:53.435042Z"> | + | </ |
| - | < | + | <d id="1089dde2-a097-4e0d-8012-c8cf3dc62696" |
| - | </hv> | + | |
| - | <hv ts=" | + | <p n="Output" |
| - | <n1:v>4</n1:v> | + | |
| - | </hv> | + | </p> |
| + | | ||
| + | </d> | ||
| + | </ | ||
| + | | ||
| + | </vals> | ||
| + | </ | ||
| - | </vals> | + | ====api/get/projectByParts==== |
| - | </hist> | + | |
| - | </ | + | |
| + | To get the list of datapoints. | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| </ | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml><? | ||
| + | < | ||
| + | < | ||
| + | <dp id=" | ||
| + | < | ||
| + | < | ||
| + | <p n=" | ||
| + | <n1:r n2: | ||
| + | < | ||
| + | </ | ||
| + | <n1:w r: | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | <p n=" | ||
| + | < | ||
| + | </ | ||
| + | <p n=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | <n3:p r: | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | </dp> | ||
| + | <dp id=" | ||
| + | < | ||
| + | < | ||
| + | <p n=" | ||
| + | <n1:r n2: | ||
| + | < | ||
| + | </ | ||
| + | <n1:w r: | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | <p n=" | ||
| + | < | ||
| + | </ | ||
| + | <p n=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | <n3:p r: | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | <def enabled=" | ||
| + | < | ||
| + | <status user=" | ||
| + | </ | ||
| + | </dp> | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | To get the list of projects. | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml><? | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | <project id=" | ||
| + | <loc> | ||
| + | <n1:gps lat=" | ||
| + | </ | ||
| + | <mdi> | ||
| + | <mi n2: | ||
| + | <mi n3: | ||
| + | </ | ||
| + | </ | ||
| + | <project id=" | ||
| + | <mdi> | ||
| + | <mi r: | ||
| + | <mi r: | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </mi> | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | ===== 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. {' | ||
| + | |||
| + | ==== Data download example ==== | ||
| + | |||
| + | <code matlab> | ||
| + | |||
| + | dataPointIDs = {' | ||
| + | projectId = ' | ||
| + | chartLegend = {'/ | ||
| + | from = now - 4; | ||
| + | to = now; | ||
| + | timeSpan = 300; %sec | ||
| + | |||
| + | [data, time] = scada.getData(projectId, | ||
| + | |||
| + | plot(time, | ||
| + | legend(chartLegend); | ||
| + | datetick;</ | ||
| + | |||
| + | |||
| + | ==== ScadaClient ==== | ||
| + | |||
| + | <code matlab> | ||
| + | |||
| + | Constructor of Mervis API wrapper. | ||
| + | |||
| + | ==== findAllDPsWithReqTags ==== | ||
| + | |||
| + | <code matlab> | ||
| + | |||
| + | Returns list of datapoints based on tags query. Example of tags definition: {' | ||
| + | |||
| + | ==== saveData==== | ||
| + | <code matlab> | ||
| + | Saves data into the Mervis database. | ||
| + | |||
| + | ==== deleteVariable ==== | ||
| + | <code matlab> | ||
| + | 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> | ||
| + | Sets data point value using a button (primary the INIT button). Only numerical values are supported. Parameter buttonName is not mandatory. Value ' | ||
| + | |||
| + | {{ : | ||
| + | |||
| + | **Example: | ||
| + | <code matlab> | ||
| + | dpGuid = ' | ||
| + | projectId = ' | ||
| + | buttonName = ' | ||
| + | newValue = 1; | ||
| + | |||
| + | scada = ScadaClient(' | ||
| + | scada.setDataPointValue(projectId, | ||
| + | |||
| + | </ | ||
| + | ==== getData==== | ||
| + | <code matlab> | ||
| + | Downloads data. Span is a sampling interval in seconds, default is 300 sec. Zone is time zone ' | ||
| + | |||
| + | ==== getDpTags==== | ||
| + | <code matlab> | ||
| + | Returns tags of the particular datapoint. | ||
| + | ==== getAllProjectDPs==== | ||
| + | <code matlab> | ||
| + | Returns project IDs and names that are accessible to logged user. | ||