Rozdíly
Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.
| Obě strany předchozí revize Předchozí verze Následující verze | Předchozí verze | ||
|
cs:mervis-scada:50-api [2020/04/06 11:24] v.kohout |
cs:mervis-scada:50-api [2026/07/17 12:58] (aktuální) z.moustis |
||
|---|---|---|---|
| Řádek 1: | Řádek 1: | ||
| - | ====== API ====== | + | ====== |
| - | Mervis SCADA nabízí otevřené REST-like API postavené | + | Mervis SCADA nabízí otevřené REST-like API založené |
| - | ===== Přehled základních | + | **Důležité upozornění k formátům: |
| - | ^Function^Description| | + | ===== Podporované API metody ===== |
| - | ^api/ | + | Níže je uveden konsolidovaný seznam doporučených API metod. Jsou zde uvedeny pouze metody s kompletní dokumentací a ověřenými příklady. |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| - | ^api/ | + | |
| + | ^ Funkce ^ Popis | | ||
| + | | **Autentizace** | | | ||
| + | | '' | ||
| + | | **Projekty a datová struktura** | | | ||
| + | | '' | ||
| + | | '' | ||
| + | | **Čtení dat** | | | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | **Zápis dat a provádění akcí** | | | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| - | ===== Příklad ===== | + | **Poznámka k přihlašovacím údajům:** API metody můžete testovat pomocí přihlašovacích údajů `n: demo` a `p: demo`. V produkčních aplikacích je doporučeno nejprve získat autentizační token pomocí metody `api/ |
| - | ====api/ | + | ===== Autentizace ===== |
| - | **Request** | + | ==== api/ |
| + | **Požadavek:** | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| - | * URL: https:// | + | Standardní přihlášení: |
| - | * Method: POST | + | <code javascript> |
| + | {" | ||
| + | </ | ||
| - | **Request** | + | Přihlášení do konkrétní domény: |
| + | <code javascript> | ||
| + | {" | ||
| + | </ | ||
| + | |||
| + | **Vlastnosti odpovědi:** | ||
| + | * **token** (string) – autentizační token používaný při dalších API voláních. | ||
| + | * **tokenValidFor** (TimeSpan) – doba platnosti tokenu (např. " | ||
| + | * **changePwdBefore** (DateTime nebo null) – datum a čas, do kterého je nutné změnit aktuální heslo. | ||
| <code javascript> | <code javascript> | ||
| - | {"cred": | + | { |
| + | | ||
| + | | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | } | ||
| </ | </ | ||
| - | **Response** | + | ===== Čtení dat ===== |
| + | ==== api/ | ||
| + | Vrací aktuální hodnoty datových bodů (vlastnost " | ||
| + | |||
| + | **Požadavek: | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }] | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Odpověď: | ||
| <code xml> | <code xml> | ||
| <?xml version=" | <?xml version=" | ||
| - | <checkCredentialsResult | + | <values |
| + | < | ||
| + | <v projId=" | ||
| + | < | ||
| + | <d id=" | ||
| + | < | ||
| + | <p n=" | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </values> | ||
| </ | </ | ||
| - | * Získaný token **t** lze použít místo dvojice jméno/heslo v následujících | + | ==== api/v3/ |
| + | Stažení jednoho nebo více trendů jedním | ||
| - | ====api/ | + | **Pravidla: |
| + | * Položky **segmentation**, | ||
| - | **Request** | + | **Požadavek:** |
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| - | * URL: /api/ | + | <code javascript> |
| - | | + | { |
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </code> | ||
| + | |||
| + | **Popis odpovědi:** | ||
| + | * **v** – hodnota | ||
| + | * **ts** – časová známka (začátek období platnosti) | ||
| + | * **gt** – goodthrough (konec období platnosti) | ||
| + | * **meta.interval** – očekávaný interval mezi uloženými záznamy. Lze využít k identifikaci chybějících dat. | ||
| <code javascript> | <code javascript> | ||
| - | { | + | { |
| - | | + | "result": { " |
| - | "n":" | + | "data": |
| - | "p":" | + | |
| - | "pe":0 | + | "historyData": |
| - | }, | + | { |
| - | | + | |
| - | | + | "provider": |
| - | | + | " |
| - | "to":" | + | "parameters": |
| - | "offset":0, | + | " |
| - | | + | "dataPointId": " |
| - | | + | } |
| + | }, | ||
| + | "meta": | ||
| + | "values": | ||
| + | { " | ||
| + | ] | ||
| + | } | ||
| + | ] | ||
| + | }, | ||
| + | | ||
| } | } | ||
| </ | </ | ||
| - | **Response** | + | ==== api/ |
| + | **Požadavek:** | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| + | * **dataSpec: | ||
| + | * **refTime: | ||
| - | < | + | < |
| - | <?xml version=" | + | { |
| - | < | + | " |
| - | | + | |
| - | < | + | "p": "demo" |
| - | < | + | }, |
| - | <hv ts=" | + | " |
| - | < | + | " |
| - | </ | + | " |
| - | <hv ts="2018-11-03T20: | + | " |
| - | < | + | " |
| - | </ | + | " |
| - | <hv ts=" | + | } |
| - | < | + | </code> |
| - | </ | + | |
| - | <hv ts="2018-11-05T17: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-05T19: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-05T22: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-06T02: | + | |
| - | < | + | |
| - | </hv> | + | |
| - | <hv ts="2018-11-06T04: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts="2018-11-06T06: | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | </ | + | |
| - | </ | + | |
| - | </getHistoryResult> | + | |
| + | ===== Zápis dat a provádění akcí ===== | ||
| + | ==== api/ | ||
| + | **Požadavek: | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| + | |||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | <values projId=" | ||
| + | <dps> | ||
| + | <d id=" | ||
| + | < | ||
| + | <p n=" | ||
| + | < | ||
| + | </p> | ||
| + | </ | ||
| + | </d> | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| </ | </ | ||
| - | ====api/ | + | ==== api/set/executeActions |
| + | **Požadavek: | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| - | **Request** | + | <code xml> |
| + | <?xml version=" | ||
| + | < | ||
| + | <n1:cred n=" | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| - | * URL: /api/set/ | + | ==== api/ |
| - | | + | Atribut **i** určuje **interval** (ISO 8601), ve kterém je očekávána následující hodnota. Všechny datumové a časové údaje musí být uvedeny v UTC. |
| + | |||
| + | **Příklad požadavku Replace History: | ||
| + | * **URL:** '' | ||
| + | * **Metoda:** POST | ||
| <code xml> | <code xml> | ||
| <?xml version=" | <?xml version=" | ||
| - | <setHistoryRequest | + | <replaceHistoryRequest |
| - | xmlns: | + | <n2:cred n=" |
| - | xmlns: | + | <vals> |
| - | projId=" | + | <hv ts=" |
| - | dpId=" | + | < |
| - | < | + | </ |
| - | < | + | <hv ts=" |
| - | <hv ts=" | + | < |
| - | < | + | </ |
| - | </ | + | </ |
| - | <hv ts=" | + | </replaceHistoryRequest> |
| - | <n1:v> | + | </ |
| - | </hv> | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | <hv ts=" | + | |
| - | < | + | |
| - | </ | + | |
| - | </ | + | |
| - | </setHistoryRequest></ | + | |
| - | **Response** | + | ===== Správa projektů ===== |
| + | |||
| + | ==== api/ | ||
| + | **Požadavek:** | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Odpověď: | ||
| + | <code xml> | ||
| + | <?xml version=" | ||
| + | < | ||
| + | < | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | <project id=" | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ==== api/ | ||
| + | Vrací strukturu Visual tree a seznam datových bodů. | ||
| + | |||
| + | **Požadavek: | ||
| + | * **URL:** ''/ | ||
| + | * **Metoda:** POST | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ===== Matlab Client ===== | ||
| + | |||
| + | ==== Obecné poznámky ==== | ||
| + | * Názvy parametrů **ID** a **Guid** jsou v klientovi Matlab používány zaměnitelně. Vždy se jedná o globálně jedinečný identifikátor projektu nebo datového bodu. | ||
| + | * Pokud je parametr uveden v množném čísle, očekává se pole GUID (např. '' | ||
| + | |||
| + | ==== ScadaClient ==== | ||
| + | <code matlab> | ||
| + | Konstruktor obalové třídy Mervis API. | ||
| + | |||
| + | ==== findAllDPsWithReqTags ==== | ||
| + | <code matlab> | ||
| + | Vrátí seznam datových bodů podle zadaných tagů. Příklad definice tagů: '' | ||
| + | |||
| + | ==== getDpTags ==== | ||
| + | <code matlab> | ||
| + | Vrátí tagy konkrétního datového bodu. | ||
| + | |||
| + | ==== getAllProjectDPs ==== | ||
| + | <code matlab> | ||
| + | Vrátí ID a názvy projektů dostupných přihlášenému uživateli. | ||
| + | |||
| + | ==== getData ==== | ||
| + | <code matlab> | ||
| + | Stáhne data. | ||
| + | |||
| + | * **span:** interval vzorkování v sekundách, výchozí hodnota je 300 s. | ||
| + | * **zone:** časové pásmo (' | ||
| + | * **Vrací:** '' | ||
| + | |||
| + | **Příklad stažení dat:** | ||
| + | <code matlab> | ||
| + | scada = ScadaClient(' | ||
| + | |||
| + | dataPointIDs = {' | ||
| + | projectId = ' | ||
| + | chartLegend = {'Temp UT1',' | ||
| + | from = now - 4; | ||
| + | to = now; | ||
| + | timeSpan = 300; | ||
| + | |||
| + | [data, time] = scada.getData(projectId, | ||
| + | |||
| + | plot(time, | ||
| + | legend(chartLegend); | ||
| + | datetick; | ||
| + | </ | ||
| + | |||
| + | ==== saveData ==== | ||
| + | <code matlab> | ||
| + | Uloží data do databáze Mervis. | ||
| + | |||
| + | ==== setDataPointValue ==== | ||
| + | <code matlab> | ||
| + | Nastaví hodnotu datového bodu pomocí tlačítka. Jsou podporovány pouze číselné hodnoty. Parametr '' | ||
| + | |||
| + | **Příklad: | ||
| + | <code matlab> | ||
| + | dpGuid = ' | ||
| + | projectId = ' | ||
| + | buttonName = ' | ||
| + | newValue = 1; | ||
| + | |||
| + | scada = ScadaClient(' | ||
| + | scada.setDataPointValue(projectId, | ||
| + | </ | ||
| - | * 200 OK | + | ==== deleteVariable ==== |
| + | <code matlab> | ||
| + | **Upozornění: | ||