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 [2019/03/13 15:12] m.chlupac [setDataPointValue] |
en:mervis-scada:50-api [2026/07/17 12:41] (current) z.moustis |
||
|---|---|---|---|
| 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 [[: | + | Mervis SCADA offers |
| - | ===== List of basic API methods ===== | + | **Important Note on Formatting: |
| - | ^Function^Description| | + | ===== Supported API Methods ===== |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| + | Below is the consolidated list of recommended API endpoints. Note: Only methods with fully documented and verified examples are listed below. | ||
| + | ^ Function ^ Description | | ||
| + | | **Authentication** | | | ||
| + | | '' | ||
| + | | **Project & Data Structure** | | | ||
| + | | '' | ||
| + | | '' | ||
| + | | **Reading Data** | | | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | **Writing & Execution** | | | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | **Note on Credentials: | ||
| - | ===== Example | + | ===== Authentication |
| - | ====api/ | + | ==== api/v2/get/authenticate |
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| - | **Request** | + | Standard login: |
| + | <code javascript> | ||
| + | {" | ||
| + | </ | ||
| - | * URL: /api/ | + | Domain-specific login: |
| - | | + | <code javascript> |
| + | {" | ||
| + | </code> | ||
| + | |||
| + | **Response Properties:** | ||
| + | * **token** (string) - Authentication token for calling other API methods. | ||
| + | * **tokenValidFor** (TimeSpan) - The duration for which the provided token is valid (e.g., " | ||
| + | * **changePwdBefore** (DateTime or null) - Specifies the date and time by which the current password must be changed. | ||
| <code javascript> | <code javascript> | ||
| - | { | + | { |
| - | | + | "data": { |
| - | "n":" | + | "ChangePwdBefore": |
| - | "p":" | + | " |
| - | }, | + | " |
| - | | + | " |
| - | | + | " |
| - | | + | "Login": " |
| - | | + | " |
| - | | + | "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f", |
| - | "count":5000, | + | "TokenValidFor": "P1D", |
| - | "historyState":"" | + | "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e", |
| + | "Username": "" | ||
| + | }, | ||
| + | "result": | ||
| } | } | ||
| </ | </ | ||
| - | **Response** | + | ===== Reading Data ===== |
| + | |||
| + | ==== api/ | ||
| + | Retrieves current values of data points (property " | ||
| + | |||
| + | **Request:** | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }] | ||
| + | } | ||
| + | </ | ||
| + | **Response: | ||
| <code xml> | <code xml> | ||
| <?xml version=" | <?xml version=" | ||
| - | <getHistoryResult | + | <values |
| - | <!-- | + | <vals> |
| - | @Interval - ISO interval of trend values defined by the database client. | + | <v projId=" |
| - | @historyState - to be copied into the next request | + | |
| - | @nextValOfs - to be copied into the next request until value -1 is reached. | + | <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" |
| - | If ts of value in not within the interval time span after the previous value' | + | |
| - | + | <p n="Output" | |
| - | --> | + | |
| - | <hist projId=" | + | </p> |
| - | < | + | |
| - | < | + | </d> |
| - | <!--ts - time stamp, gt - good through, value is valid in the whole time span between these two--> | + | |
| - | <hv ts=" | + | </ |
| - | <n1: | + | </ |
| - | </ | + | </values> |
| - | | + | </code> |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-05T11: | + | |
| - | <n1: | + | |
| - | </hv> | + | |
| - | <hv ts="2018-11-05T17: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-05T19: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-05T22: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </hv> | + | |
| - | < | + | |
| - | < | + | |
| - | </hv> | + | |
| - | < | + | |
| - | < | + | |
| - | </hv> | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | <!-- value without gt - ts and gt are equal--> | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | | + | |
| - | </hist> | + | |
| - | </getHistoryResult> | + | |
| + | ==== api/ | ||
| + | Downloading one or multiple trends with a single API call. | ||
| + | **Rules:** | ||
| + | * Items " | ||
| + | |||
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Response Details:** | ||
| + | * **v** - value | ||
| + | * **ts** - timestamp (start of validity period) | ||
| + | * **gt** - goodthrough (end of validity period) | ||
| + | * **meta.interval** - expected interval between stored records. Useful to identify missing data. | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | { " | ||
| + | ] | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== api/ | ||
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | * **dataSpec: | ||
| + | * **refTime: | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ===== Writing Data & Execution ===== | ||
| + | |||
| + | ==== api/ | ||
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | <values projId=" | ||
| + | <dps> | ||
| + | <d id=" | ||
| + | < | ||
| + | <p n=" | ||
| + | < | ||
| + | </p> | ||
| + | </ | ||
| + | </d> | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ==== api/ | ||
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | <n1:cred n=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ==== api/ | ||
| + | Attribute **i** sets **interval** (ISO 8601) in which the next value should be expected. All date/time values must be in UTC. | ||
| + | |||
| + | **Replace History Request Example:** | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | <n2:cred n=" | ||
| + | < | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | <hv ts=" | ||
| + | < | ||
| + | </hv> | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ===== Projects Management ===== | ||
| + | |||
| + | ==== api/ | ||
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Response: | ||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ==== api/ | ||
| + | To get the visual tree and list of datapoints. | ||
| + | |||
| + | **Request: | ||
| + | * **URL:** ''/ | ||
| + | * **Method:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| </ | </ | ||
| ===== Matlab Client ===== | ===== 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 | + | ==== General Notes ==== |
| + | * Parameter names **ID** and **Guid** are used interchangeably in the Matlab client; it is always a universally unique identifier referring to a project or datapoint. | ||
| + | * When plural is used, an array of guids is expected (ie. '' | ||
| - | <code matlab> | + | ==== ScadaClient ==== |
| + | <code matlab>ScadaClient(url, | ||
| + | Constructor of the Mervis API wrapper. | ||
| + | |||
| + | ==== findAllDPsWithReqTags ==== | ||
| + | <code matlab> | ||
| + | Returns list of datapoints based on tags query. Example of tags definition: '' | ||
| + | |||
| + | ==== getDpTags ==== | ||
| + | <code matlab> | ||
| + | Returns tags of the particular datapoint. | ||
| + | |||
| + | ==== getAllProjectDPs ==== | ||
| + | <code matlab> | ||
| + | Returns project IDs and names that are accessible to the logged-in user. | ||
| + | |||
| + | ==== getData ==== | ||
| + | <code matlab> | ||
| + | Downloads data. | ||
| + | * **span:** sampling interval in seconds, default is 300 sec. | ||
| + | * **zone:** time zone (' | ||
| + | * **Returns: | ||
| + | |||
| + | **Data Download Example: | ||
| + | <code matlab> | ||
| + | scada = ScadaClient(' | ||
| dataPointIDs = {' | dataPointIDs = {' | ||
| projectId = ' | projectId = ' | ||
| - | chartLegend = {'/Plynová kotelna/ | + | chartLegend = {'Temp UT1',' |
| from = now - 4; | from = now - 4; | ||
| to = now; | to = now; | ||
| Line 136: | Line 378: | ||
| plot(time, | plot(time, | ||
| legend(chartLegend); | legend(chartLegend); | ||
| - | datetick;</ | + | datetick; |
| + | </ | ||
| - | + | ==== saveData ==== | |
| - | ==== 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> | <code matlab> | ||
| Saves data into the Mervis database. | 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 ==== | ==== setDataPointValue ==== | ||
| <code matlab> | <code matlab> | ||
| - | Sets data point value using a button | + | Sets a datapoint |
| **Example: | **Example: | ||
| Line 168: | Line 393: | ||
| dpGuid = ' | dpGuid = ' | ||
| projectId = ' | projectId = ' | ||
| - | buttonName = ' | + | buttonName = ' |
| newValue = 1; | newValue = 1; | ||
| - | scada = ScadaClient(' | + | scada = ScadaClient(' |
| scada.setDataPointValue(projectId, | scada.setDataPointValue(projectId, | ||
| - | |||
| </ | </ | ||
| - | ==== getData==== | ||
| - | <code matlab> | ||
| - | Downloads data. Span is a sampling interval in seconds, default is 300 sec. Zone is time zone ' | ||
| - | ==== getDpTags==== | + | ==== deleteVariable |
| - | <code matlab>getDpTags(projectId, DpId) </ | + | <code matlab>deleteVariable(projGuid, dpGuid, from, to)</ |
| - | Returns tags of the particular datapoint. | + | **Warning: |
| - | + | ||
| - | + | ||
| - | ==== getAllProjectDPs==== | + | |
| - | <code matlab> | + | |
| - | Returns project IDs and names that are accessible to logged user. | + | |