Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
en:mervis-scada:50-api [2018/11/21 15:54] j.siroky [Matlab] |
en:mervis-scada:50-api [2023/09/26 14:41] v.kohout [api/get/history/specific] |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| Mervis SCADA offers open REST-like 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 [[: | ||
| + | **Important: | ||
| ===== List of basic API methods ===== | ===== List of basic API methods ===== | ||
| ^Function^Description| | ^Function^Description| | ||
| - | |||
| ^api/ | ^api/ | ||
| ^api/ | ^api/ | ||
| Line 15: | Line 15: | ||
| ^api/ | ^api/ | ||
| ^api/ | ^api/ | ||
| + | ^api/ | ||
| ^api/ | ^api/ | ||
| ^api/ | ^api/ | ||
| Line 32: | Line 33: | ||
| - | ===== Example | + | ===== Examples |
| - | ====api/ | + | ====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> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **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> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | |||
| + | </ | ||
| + | |||
| + | ==== api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * You should always use token (" | ||
| + | * " | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | * " | ||
| + | |||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | * Values | ||
| + | * v - value | ||
| + | * ts - timestamp - start of the value validity period | ||
| + | * gt - goodthrough - end of the value validity period | ||
| + | * i - interval | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ], | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | |||
| + | </ | ||
| + | |||
| + | ==== [Depricated] | ||
| **Request** | **Request** | ||
| Line 117: | Line 478: | ||
| </ | </ | ||
| - | ==== Matlab | + | |
| - | ^ Function | + | ====api/ |
| - | | ScadaClient(url, | + | |
| - | | findAllDPsWithReqTags(projIds, | + | **Request** |
| - | | saveData(projID, | + | |
| - | | deleteVariable(projGuid, | + | * URL: / |
| - | | [data, time, dataInCell, info] = getData(this,projID, | + | * 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 ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **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 ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | * 200 OK | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | * Content-Type: | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | xmlns: | ||
| + | xmlns: | ||
| + | xmlns: | ||
| + | <n1:cred t=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml><? | ||
| + | < | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | The right way how to retrieve current values of data points (property " | ||
| + | |||
| + | **Request** | ||
| + | |||
| + | * URL: / | ||
| + | * Method: POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | ] | ||
| + | } | ||
| + | |||
| + | </ | ||
| + | |||
| + | **Response** | ||
| + | |||
| + | <code xml><? | ||
| + | <values xmlns: | ||
| + | < | ||
| + | <v projId=" | ||
| + | < | ||
| + | <d id=" | ||
| + | < | ||
| + | <p n=" | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | <d id=" | ||
| + | < | ||
| + | <p n=" | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ====api/ | ||
| + | |||
| + | 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 id=" | ||
| + | < | ||
| + | < | ||
| + | <p n=" | ||
| + | <n1:r n2: | ||
| + | < | ||
| + | </ | ||
| + | <n1:w r: | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | <p n=" | ||
| + | < | ||
| + | </ | ||
| + | <p n=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | <n3:p r: | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | < | ||
| + | <def enabled=" | ||
| + | < | ||
| + | <status user=" | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | ===== 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>ScadaClient(url, | ||
| + | |||
| + | Constructor | ||
| + | |||
| + | ==== findAllDPsWithReqTags ==== | ||
| + | |||
| + | <code matlab>findAllDPsWithReqTags(projIds, | ||
| + | |||
| + | Returns list of datapoints based on tags query. Example of tags definition: {' | ||
| + | |||
| + | ==== saveData==== | ||
| + | <code matlab>saveData(projID, | ||
| + | Saves data into the Mervis database. | ||
| + | |||
| + | ==== deleteVariable ==== | ||
| + | <code matlab>deleteVariable(projGuid, | ||
| + | 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>[data, time, dataInCell, info] = getData(projID, | ||
| + | Downloads | ||
| + | |||
| + | ==== getDpTags==== | ||
| + | <code matlab>getDpTags(projectId, | ||
| + | Returns tags of the particular datapoint. | ||
| + | |||
| + | |||
| + | ==== getAllProjectDPs==== | ||
| + | <code matlab> | ||
| + | Returns project IDs and names that are accessible to logged user. | ||