Rozdíly

Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.

Odkaz na výstup diff

Obě strany předchozí revize Předchozí verze
Následující verze 		Předchozí verze
cs:mervis-scada:50-api [2017/06/29 14:50]
m.chlupac [API] 		cs:mervis-scada:50-api [2026/07/17 12:58] (aktuální)
z.moustis
Řádek 1: Řádek 1:
-====== API ======+====== Mervis SCADA API ======
  
-Mervis SCADA nabízí otevřené REST-like API postavené na JSON a XML formátech dat. Pro kompletní popis API kontaktujte naši [[cs:help:support|technickou podporu]].+Mervis SCADA nabízí otevřené REST-like API založené na datových formátech JSON a XML pro bezproblémovou integraci s aplikacemi třetích stran. Podrobný popis pokročilých funkcí získáte u [[:cs:help:20-support|technické podpory]].
  
-===== Příklad =====+**Důležité upozornění k formátům:** Přestože jsou v novějších API metodách ve velké míře využívány formáty JSON, jediným oficiálně podporovaným zpětně kompatibilním formátem odpovědí v rámci celého původního API je XML.
  
-==GetHistoryRequest==+===== Podporované API metody =====
  
-**Request**+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.
  
-   * URL: /api/get/history?format=xml +^ Funkce ^ Popis | 
-   * Method: POST+| **Autentizace** | | 
 +| ''api/v2/get/authenticate'' | Ověří uživatele a vrátí token relace pro následná API volání. | 
 +| **Projekty a datová struktura** | | 
 +| ''api/get/projects'' | Vrátí seznam všech projektů dostupných přihlášenému uživateli. | 
 +| ''api/get/projectByParts'' | Vrátí strukturu Visual tree a seznam datových bodů ve vybraném projektu. | 
 +| **Čtení dat** | | 
 +| ''api/get/values'' | Vrátí aktuální hodnoty zadaných datových bodů v reálném čase. | 
 +| ''api/v3/get/history'' | Stáhne historická trendová data jedné nebo více časových řad v jednom stránkovaném volání. | 
 +| ''api/get/history/specific'' | Vrátí konkrétní historické hodnoty vzhledem k zadanému referenčnímu času. | 
 +| **Zápis dat a provádění akcí** | | 
 +| ''api/set/values'' | Zapíše nové hodnoty do zadaných datových bodů. | 
 +| ''api/set/executeActions'' | Spustí předdefinované akce nebo tlačítka (například INIT nebo ZAP) nad datovými body. | 
 +| ''api/set/history'' | Vloží nové historické hodnoty do databáze. | 
 +| ''api/replace/history'' | Kompletně nahradí existující historická data ve zvoleném časovém rozsahu. | 
 + 
 +**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/v2/get/authenticate` a následně jej používat (`t: [token_string]`) při dalších API voláních. Tím je zajištěn optimální výkon. 
 + 
 +===== Autentizace ===== 
 + 
 +==== api/v2/get/authenticate ==== 
 +**Požadavek:** 
 +  * **URL:** ''/api/v2/get/authenticate?format=json'' 
 +  * **Metoda:** POST 
 + 
 +Standardní přihlášení: 
 +<code javascript> 
 +{"data":{"cred":{"n":"demo","p":"demo"}}} 
 +</code> 
 + 
 +Přihlášení do konkrétní domény: 
 +<code javascript> 
 +{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}} 
 +</code> 
 + 
 +**Vlastnosti odpovědi:** 
 +  * **token** (string) – autentizační token používaný při dalších API voláních. 
 +  * **tokenValidFor** (TimeSpan) – doba platnosti tokenu (např. "P1D" = 1 den). 
 +  * **changePwdBefore** (DateTime nebo null) – datum a čas, do kterého je nutné změnit aktuální heslo.
  
 <code javascript> <code javascript>
 { {
-   "cred":{ +    "data": { 
-      "t":"d1871589-c455-416a-91f3-d9cda3aa5e0f" +        "ChangePwdBefore": null, 
-   }, +        "ClientType": 2, 
-   "projId":"2e4deb05-0517-4ef7-ae7a-02e146b23a1d", +        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1", 
-   "dpId":"ffb370fc-eeb8-404f-9088-46577ea64134", +        "DomainName": "GlobalDomain", 
-   "providerId":"689E32FA-24A2-448E-9374-6158E6E6CB15", +        "FullName": "GlobalDomain\\demo", 
-   "from":"/Date(1494280800000)/", +        "Login": "demo", 
-   "to":"/Date(1494412488822)/", +        "NotifyNearingPwdExpirationIn": null, 
-   "offset":0, +        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f", 
-   "count":5000, +        "TokenValidFor": "P1D", 
-   "historyState":""+        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e", 
 +        "Username": "" 
 +    }, 
 +    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
 } }
 </code> </code>
  
-**Response**+===== Čtení dat =====
  
 +==== api/get/values ====
 +Vrací aktuální hodnoty datových bodů (vlastnost "Output") z jednoho nebo více projektů.
 +
 +**Požadavek:**
 +  * **URL:** ''/api/get/values?format=xml''
 +  * **Metoda:** POST
 +
 +<code javascript>
 +{
 + "cred": {
 +  "n": "demo",
 +  "p": "demo"
 + },
 + "propNamesToSerialize": ["Output"],
 + "offset": 0,
 + "count": 1000,
 + "serverState": null,
 + "dps": [{
 +   "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 +   "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
 +  }]
 +}
 +</code>
 +
 +**Odpověď:**
 <code xml> <code xml>
-<getHistoryResult xmlns:r="http://dev.rcware.eu/serialization/references" r:type="b133774d-21ce-42b6-add3-57c012079c55" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/history"> +<?xml version="1.0" encoding="utf-8"?> 
-  <hist projId="2e4deb05-0517-4ef7-ae7a-02e146b23a1d" dpId="ffb370fc-eeb8-404f-9088-46577ea64134" propName="Output" interval="PT5M" historyState="" nextValOfs="-1"> +<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2026-07-17T10:29:17Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints"> 
-    <errMsg/> + <vals> 
-    <vals> +  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z"> 
-      <hv ts="2017-05-08T22:26:53.32684Z" gt="2017-05-08T22:31:53.465467Z"> +   <dps> 
-        <n1:v>4.3</n1:v> +    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true"> 
-      </hv> +     <props> 
-      <hv ts="2017-05-08T22:36:53.283875Z"> +      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55"> 
-        <n1:v>4.2</n1:v> +       <n1:v>13851.42</n1:v> 
-      </hv> +      </p> 
-      <hv ts="2017-05-08T22:41:53.435042Z"> +     </props> 
-        <n1:v>4.1</n1:v> +    </d> 
-      </hv> +   </dps> 
-      <hv ts="2017-05-08T22:46:53.711496Z" gt="2017-05-08T23:36:53.776657Z"> +  </v> 
-        <n1:v>4</n1:v> + </vals> 
-      </hv>+</values> 
 +</code> 
 + 
 +==== api/v3/get/history ==== 
 +Stažení jednoho nebo více trendů jedním API voláním. 
 + 
 +**Pravidla:** 
 +  * Položky **segmentation**, **requestState** a **serverState** musí při stránkování vždy obsahovat hodnoty z poslední odpovědi serveru. Při prvním volání použijte prázdnou hodnotu **segmentation**. 
 + 
 +**Požadavek:** 
 +  * **URL:** ''/api/v3/get/history?format=json'' 
 +  * **Metoda:** POST 
 + 
 +<code javascript> 
 +{ 
 +    "credentials": { 
 +        "name": "demo", 
 +        "password": "demo" 
 +    }, 
 +    "request": { 
 +        "commonSeriesParameters": { 
 +            "from": "2026-06-20T00:00:00Z", 
 +            "to": "2026-07-17T00:00:00Z" 
 +        }, 
 +        "series": [ 
 +            { 
 +                "clientReference": "test1", 
 +                "provider": { 
 +                    "parameters": { 
 +                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
 +                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0" 
 +                    } 
 +                } 
 +            } 
 +        ] 
 +    }, 
 +    "dataSpecification": { 
 +        "limits": { "count": 1000 } 
 +    }, 
 +    "segmentation": { 
 +        "requestState": "", 
 +        "serverState": "" 
 +    } 
 +} 
 +</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> 
 +{ 
 +    "result": { "code": 0, "subCode": 0, "message": "" }, 
 +    "data": { 
 +        "count": 1, 
 +        "historyData": [ 
 +            { 
 +                "clientReference": "test1", 
 +                "provider": { 
 +                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15", 
 +                    "parameters": { 
 +                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
 +                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0" 
 +                    } 
 +                }, 
 +                "meta": { "type": "double", "unit": "h", "interval": "PT3M" }, 
 +                "values": [ 
 +                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z" } 
 +                ] 
 +            } 
 +        ] 
 +    }, 
 +    "segmentation": { "requestState": "", "serverState": "" } 
 +} 
 +</code> 
 + 
 +==== api/get/history/specific ==== 
 +**Požadavek:** 
 +  * **URL:** ''/api/get/history/specific?format=json'' 
 +  * **Metoda:** POST 
 +  * **dataSpec:** Definuje požadovaný bod historie (například 2 = první hodnota menší než referenční čas). 
 +  * **refTime:** Referenční čas použitý při vyhledávání. 
 + 
 +<code javascript> 
 +{ 
 + "cred": { 
 +  "n": "demo", 
 +  "p": "demo" 
 + }, 
 + "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
 + "offset": 0, 
 + "count": 1000, 
 + "dataSpec": 2, 
 + "refTime": "\/Date(1692788459000)\/", 
 + "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"] 
 +} 
 +</code> 
 + 
 +===== Zápis dat a provádění akcí ===== 
 + 
 +==== api/set/values ==== 
 +**Požadavek:** 
 +  * **URL:** ''/api/set/values?format=xml'' 
 +  * **Metoda:** POST 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/datapoints" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/comm-props" > 
 +   <n2:cred n="demo" p="demo"/> 
 +        <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643"> 
 +            <dps> 
 +                <d id="07d538d9-9f4b-46ca-ba4d-13b13b5302ff"> 
 +                    <props> 
 +                        <p n="Source" t="2024-02-23T09:58:00Z" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09"> 
 +                            <n1:v>23</n1:v> 
 +                        </p> 
 +                    </props> 
 +                </d> 
 +            </dps> 
 +        </values> 
 +</setValuesRequest> 
 +</code> 
 + 
 +==== api/set/executeActions ==== 
 +**Požadavek:** 
 +  * **URL:** ''/api/set/executeActions?format=xml'' 
 +  * **Metoda:** POST 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" xmlns:n2="http://dev.rcware.eu/scada/basic-props" xmlns:n1="http://dev.rcware.eu/auth" xmlns:r="http://dev.rcware.eu/serialization/references"> 
 +  <n1:cred n="demo" p="demo"/> 
 +  <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0"> 
 +    <actions> 
 +      <actionDefItem propName="INIT" dpId="afc22e18-f8e4-4e08-899c-fb9e4759df3d"> 
 +        <execParam r:type="495c9644-eed1-4b94-933b-3fae702a9aca"> 
 +          <n2:value>16</n2:value> 
 +        </execParam> 
 +      </actionDefItem> 
 +      <actionDefItem propName="ZAP" dpId="34306c80-73f1-4465-ab51-2b2c1e85ab70"> 
 +      </actionDefItem> 
 +    </actions> 
 +  </actionDefs> 
 +</executeActionsRequest> 
 +</code> 
 + 
 +==== api/set/history & api/replace/history ==== 
 +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:** ''/api/replace/history?format=xml'' 
 +  * **Metoda:** POST 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/basic-props" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="e86dba6d-1250-4e7f-aafb-84fd28324710" from="2020-03-15T11:00:00+00:00" to="2020-03-18T11:00:00+00:00"> 
 +  <n2:cred n="demo" p="demo"/> 
 +  <vals> 
 +    <hv ts="2020-03-15T11:00:00+00:00" i="P1D"> 
 +      <n1:v>2.7</n1:v> 
 +    </hv> 
 +    <hv ts="2020-03-16T11:00:00+00:00" i="P1D"> 
 +      <n1:v>3.0</n1:v> 
 +    </hv> 
 +  </vals> 
 +</replaceHistoryRequest> 
 +</code> 
 + 
 +===== Správa projektů ===== 
 + 
 +==== api/get/projects ==== 
 +**Požadavek:** 
 +  * **URL:** ''/api/get/projects?format=xml'' 
 +  * **Metoda:** POST 
 + 
 +<code javascript> 
 +{ 
 + "cred": { 
 +  "n": "demo", 
 +  "p": "demo" 
 + }, 
 + "offset": 0, 
 + "count": 250 
 +} 
 +</code> 
 + 
 +**Odpověď:** 
 +<code xml> 
 +<?xml version="1.0" encoding="utf-8"?> 
 +<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/projects"> 
 +    <projects> 
 +        <project id="2a7f1615-..." name="Weather" /> 
 +        <project id="1b2623be-eaa4-4e29-8596-c66dd85d5643" name="SIMPLE_DEMO" /> 
 +        <project id="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" name="PLYNOVA_KOTELNA" /> 
 +        <project id="b9ad5380-..." name="CVUT_HERBERTOV" /> 
 +        <project id="843855a2-..." name="PRVNI_KROKY" /> 
 +    </projects> 
 +</getProjectsResult> 
 +</code> 
 + 
 +==== api/get/projectByParts ==== 
 +Vrací strukturu Visual tree a seznam datových bodů. 
 + 
 +**Požadavek:** 
 +  * **URL:** ''/api/get/projectByParts?format=xml'' 
 +  * **Metoda:** POST 
 + 
 +<code javascript> 
 +{ 
 + "cred": { 
 +  "n": "demo", 
 +  "p": "demo" 
 + }, 
 + "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", 
 + "treeId": "Visual tree", 
 + "partType": 0, 
 + "offset": 0, 
 + "count": 250 
 +} 
 +</code> 
 + 
 +===== 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ř. ''{'guid1', 'guid2'}''), jinak pouze jeden GUID. 
 + 
 +==== ScadaClient ==== 
 +<code matlab>ScadaClient(url, username, password)</code> 
 +Konstruktor obalové třídy Mervis API. 
 + 
 +==== findAllDPsWithReqTags ==== 
 +<code matlab>findAllDPsWithReqTags(projIds, tags)</code> 
 +Vrátí seznam datových bodů podle zadaných tagů. Příklad definice tagů: ''{'label','indoor_air_temperature';'room_type','office'}'' 
 + 
 +==== getDpTags ==== 
 +<code matlab>getDpTags(projectId, DpId)</code> 
 +Vrátí tagy konkrétního datového bodu. 
 + 
 +==== getAllProjectDPs ==== 
 +<code matlab>getAllProjectDPs(projectGuid)</code> 
 +Vrátí ID a názvy projektů dostupných přihlášenému uživateli. 
 + 
 +==== getData ==== 
 +<code matlab>[data, time, dataInCell, info] = getData(projID, dpsIds, from, to, span, zone, doublesInterpolationMethod, interpolate_gaps_shorter_than)</code> 
 +Stáhne data. 
 + 
 +  * **span:** interval vzorkování v sekundách, výchozí hodnota je 300 s. 
 +  * **zone:** časové pásmo ('local' nebo 'utc') použité pro vstupní parametry i výstup, výchozí hodnota je 'local'. 
 +  * **Vrací:** ''data'' (pro chybějící hodnoty se používá NaN), ''time'', ''dataInCell'' (užitečné pro textové hodnoty) a ''info''. 
 + 
 +**Příklad stažení dat:** 
 +<code matlab> 
 +scada = ScadaClient('https://scada.mervis.info/','demo','demo'); 
 + 
 +dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'}; 
 +projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0'; 
 +chartLegend = {'Temp UT1','Temp UT1 Return','Valve Position'}; 
 +from = now - 4; 
 +to = now; 
 +timeSpan = 300; 
 + 
 +[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan); 
 + 
 +plot(time,data); 
 +legend(chartLegend); 
 +datetick; 
 +</code> 
 + 
 +==== saveData ==== 
 +<code matlab>saveData(projID, dpID, time, data)</code> 
 +Uloží data do databáze Mervis.
  
-    </vals> +==== setDataPointValue ==== 
-  </hist> +<code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code> 
-</getHistoryResult>+Nastaví hodnotu datového bodu pomocí tlačítka. Jsou podporovány pouze číselné hodnoty. Parametr ''buttonName'' není povinný. Pokud není zadán, použije se ''INIT''.
  
 +**Příklad:**
 +<code matlab>
 +dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f';
 +projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa';
 +buttonName = 'INIT';
 +newValue = 1;
  
 +scada = ScadaClient('https://scada.mervis.info/','demo','demo');
 +scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
 </code> </code>
  
 +==== deleteVariable ====
 +<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code>
  
 +**Upozornění:** Odstraní data jednoho datového bodu v zadaném intervalu ''from-to''. Pokud interval není zadán, budou odstraněna **všechna** data. Tuto operaci používejte s maximální opatrností – odstranění dat nelze vrátit zpět.
  • © Energocentrum Plus, s.r.o. 2017 - 2026