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

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.

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.

Požadavek:

• URL: /api/v2/get/authenticate?format=json
• Metoda: POST

Standardní přihlášení:

{"data":{"cred":{"n":"demo","p":"demo"}}}

Přihlášení do konkrétní domény:

{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}}

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.

{
    "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 }
}

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

{
 "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"]
  }]
}

Odpověď:

<?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>

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

{
    "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": ""
    }
}

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.

{
    "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": "" }
}

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

{
 "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"]
}

Požadavek:

• URL: /api/set/values?format=xml
• Metoda: POST

<?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>

Požadavek:

• URL: /api/set/executeActions?format=xml
• Metoda: POST

<?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>

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

<?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>

Požadavek:

• URL: /api/get/projects?format=xml
• Metoda: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "offset": 0,
 "count": 250
}

Odpověď:

<?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>

Vrací strukturu Visual tree a seznam datových bodů.

Požadavek:

• URL: /api/get/projectByParts?format=xml
• Metoda: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 "treeId": "Visual tree",
 "partType": 0,
 "offset": 0,
 "count": 250
}

• 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(url, username, password)

Konstruktor obalové třídy Mervis API.

findAllDPsWithReqTags(projIds, tags)

Vrátí seznam datových bodů podle zadaných tagů. Příklad definice tagů: {'label','indoor_air_temperature';'room_type','office'}

getDpTags(projectId, DpId)

Vrátí tagy konkrétního datového bodu.

getAllProjectDPs(projectGuid)

Vrátí ID a názvy projektů dostupných přihlášenému uživateli.

[data, time, dataInCell, info] = getData(projID, dpsIds, from, to, span, zone, doublesInterpolationMethod, interpolate_gaps_shorter_than)

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:

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;

saveData(projID, dpID, time, data)

Uloží data do databáze Mervis.

setDataPointValue(projGuid, dpGuid, value, buttonName)

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:

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)

deleteVariable(projGuid, dpGuid, from, to)

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.