Differences
This shows you the differences between two versions of the page.
|
en:mervis-scada:50-api [2023/09/26 14:39] v.kohout [api/v3/get/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 [[: | ||
| - | |||
| - | **Important: | ||
| - | ===== List of basic API methods ===== | ||
| - | |||
| - | ^Function^Description| | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | ^api/ | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | ===== 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> | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | }, | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | } | ||
| - | ] | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | **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 " | ||
| - | * " | ||
| - | | ||
| - | | ||
| - | | ||
| - | | ||
| - | | ||
| - | | ||
| - | | ||
| - | * " | ||
| - | |||
| - | |||
| - | <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> | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | ] | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | }, | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | ] | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | }, | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | ] | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | } | ||
| - | ], | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | } | ||
| - | } | ||
| - | |||
| - | </ | ||
| - | |||
| - | ==== [Depricated] api/ | ||
| - | |||
| - | **Request** | ||
| - | |||
| - | * URL: / | ||
| - | * Method: POST | ||
| - | |||
| - | <code javascript> | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | **Response** | ||
| - | |||
| - | <code xml> | ||
| - | <?xml version=" | ||
| - | < | ||
| - | <!-- | ||
| - | @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' | ||
| - | | ||
| - | --> | ||
| - | <hist projId=" | ||
| - | < | ||
| - | < | ||
| - | <!--ts - time stamp, gt - good through, value is valid in the whole time span between these two--> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | <!-- value without gt - ts and gt are equal--> | ||
| - | <hv ts=" | ||
| - | < | ||
| - | </hv> | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | |||
| - | |||
| - | </ | ||
| - | |||
| - | |||
| - | ====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/ | ||
| - | |||
| - | 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=" | ||
| - | < | ||
| - | </p> | ||
| - | </ | ||
| - | </d> | ||
| - | <d id=" | ||
| - | < | ||
| - | <p n=" | ||
| - | < | ||
| - | </p> | ||
| - | </ | ||
| - | </d> | ||
| - | </ | ||
| - | </v> | ||
| - | </ | ||
| - | </ | ||
| - | |||
| - | ====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> | ||
| - | <dp id=" | ||
| - | < | ||
| - | < | ||
| - | <p n=" | ||
| - | <n1:r n2: | ||
| - | < | ||
| - | </ | ||
| - | <n1:w r: | ||
| - | < | ||
| - | </ | ||
| - | < | ||
| - | </ | ||
| - | <p n=" | ||
| - | < | ||
| - | </ | ||
| - | <p n=" | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | <n3:p r: | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | < | ||
| - | < | ||
| - | <def enabled=" | ||
| - | < | ||
| - | <status user=" | ||
| - | </ | ||
| - | </dp> | ||
| - | </ | ||
| - | </ | ||
| - | ===== 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. | ||