====== Mervis SCADA API ======

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]].

**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.

===== Podporované API metody =====

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.

^ Funkce ^ Popis |
| **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>
{
    "data": {
        "ChangePwdBefore": null,
        "ClientType": 2,
        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1",
        "DomainName": "GlobalDomain",
        "FullName": "GlobalDomain\\demo",
        "Login": "demo",
        "NotifyNearingPwdExpirationIn": null,
        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f",
        "TokenValidFor": "P1D",
        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e",
        "Username": ""
    },
    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
}
</code>

===== Č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>
<?xml version="1.0" encoding="utf-8"?>
<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">
 <vals>
  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z">
   <dps>
    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true">
     <props>
      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
       <n1:v>13851.42</n1:v>
      </p>
     </props>
    </d>
   </dps>
  </v>
 </vals>
</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.

==== setDataPointValue ====
<code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code>
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>

==== 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.