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

===== Přehled základních API metod =====

^Function^Description|

^api/checkCredentials||
^api/logout||
^api/get/projects||
^api/get/projectData||
^api/get/projectByParts||
^api/get/history||
^api/get/history/specific||
^api/set/history||
^api/get/values||
^api/get/alarms||
^api/get/alarmHistory||
^api/get/eventHistory||
^api/get/changes||
^api/set/executeActions||
^api/set/values||
^api/set/executeAlarmOps||
^api/set/projectPriorityRefresh||
^api/get/schema||
^api/get/schema/datapoints||
^api/get/schema/values||
^api/get/schema/image||
^/api/v3/get/history||


===== Příklad =====

==== api/checkCredentials ====

**Request**

   * URL: https://scada.mervis.info/api/checkCredentials?format=xml
   * Method: POST


<code javascript>
{"cred":{"n":"demo","p":"demo"}}
</code>

**Response**

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<checkCredentialsResult xmlns:r="http://dev.rcware.eu/serialization/references" d="GlobalDomain" l="demo" t="2:85be00d3-5875-4dec-a9b4-c98e2ff2acbe" xmlns="http://dev.rcware.eu/auth" />
</code>

  * Získaný token **t** je třeba použít místo dvojice jméno/heslo v následujících API voláních.





==== api/v3/get/history ====

**Request**

   * URL: /api/v3/get/history?format=json
   * Method: POST
   * Umožňuje stahovat historii pro více datových bodů
   * V ukázkách je vždy za dvěma lomítky uvedený typ property
   * V sekci credentials lze místo "token" uvést "name" a "password" - použití bez tokenu je ale výkonnostně penalizováno
   * "seriesParameters" - se uvádí jen pokud chceme rozdílné hodnoty než v "commonSeriesParameters"
   * "clientReference" - volitelné - pro dodatečnou identifikaci datového bodu klientem
   * položky "segmenation", "requestState" a "serverState" se vyplňují podle poslední odpovědi serveru. Pro první volání se tyto hodnoty neuvádějí.


<code javascript>
{
    "credentials": {
        "token":"guid" //string
    },
    "request": {
        "commonSeriesParameters": {
            "from": "2018-12-01T00:00:00Z", //UTC dateTime
            "to": "2018-12-01T10:00:00Z"//UTC dateTime
        },
        "series": [
            {
                "seriesParameters": {
                    "from": "2017-11-28T14:26:16.5029619Z",//UTC dateTime
                    "to": "2018-11-28T14:26:16.5029619Z" //UTC dateTime
                },
                "clientReference": "myId2a", //string
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //guid
                        "dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" //guid
                    }
                }
            },
            {
                "clientReference": "myId1a",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                }
            }
        ]
    },
    "dataSpecification": {
        "limits": {
            "count": 1000 //int
        }
    },
    "segmentation": {
        "requestState": ";;2;;0", //string
        "serverState": "xyz" //string
    }
}
</code>

**Response**

   * Dokud je v odpovědi v sekci "segmentation" uveden "requestState" existují v daném rozsahu další historie.
   * "requestState" a "serverState" je nutné do dalšího případného dotazu na historii předat.
   * Values
     * v - hodnota
     * ts - začátek platnosti hodnoty
     * gt - konec platnosti hodnoty
     * i - interval, pokud je jiný než uvedená hodnota u celé série
   * Meta
     * type - typ uložených hodnot - double, string, datetime
     * unit - jednotky
     * interval - informace o periodě, v jaké by měly být hodnoty v databázi uloženy. Slouží k identifikaci chybějících záznamů.

<code javascript>
{
"result": {
        "code": 0, //int
        "subCode": 0, //int
        "message": "" //string
    },
    "data": {
        "count": 3, //int
        "historyData": [
            {
                "clientReference": "myId2a", //string
                "provider": {
                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15", //guid
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //guid
                        "dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" //guid
                    }
                },
                "meta": {
                    "type": "string", //string
                    "unit": "", //string
                    "interval": "PT3M" //string - ISO8601 Timespan
                },
                "values": [
                    {
                        "v": "AUT", //string
                        "ts": "2018-11-26T12:22:15.25795Z", //dateTime
                        "gt": "2018-11-26T13:22:15.5784067Z" //dateTime
                    }
                ]
            },
            {
                "clientReference": "myId1a",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                },
                "meta": {
                    "type": "double",
                    "unit": "hod",
                    "interval": "PT3M"
                },
                "values": [
                    {
                        "v": 12939,//double
                        "ts": "2018-11-30T23:58:15.2394603Z",
                        "gt": "2018-12-01T01:37:15.4869553Z"
                    },
                    {
                        "v": 12946,
                        "ts": "2018-12-01T09:22:16.2049051Z",
                        "gt": "2018-12-01T10:37:15.4023519Z",
                        "i": "PT4M"
                    }
                ]
            }
        ]
    },
    "segmentation": {
        "requestState": "xyz", //string
        "serverState": "xyz" //string
    }
}


</code>

**Funkční demo**
<code javascript>
{
    "credentials": {
        "name": "demo",
        "password": "demo"
    },
    "request": {
        "commonSeriesParameters": {
            "from": "2018-12-01T00:00:00Z",
            "to": "2018-12-01T00:11:00Z"
        },
        "series": [
            {
                "clientReference": "myId1",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "acad79f3-3358-42dd-9b74-98733e63d771"
                    }
                }
            },
            {
                "clientReference": "myId2",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "14cf0dbb-b050-43aa-a6f0-22886c33ed8e"
                    }
                }
            }
        ]
    },
    "dataSpecification": {
        "limits": {
            "count": 1000
        }
    }
}

</code>



==== [Deprecated] api/get/history====

**Request**

   * URL: /api/get/history?format=xml
   * Method: POST

<code javascript>
{  
   "cred":{  
      "n":"demo",
      "p":"demo",
      "pe":0
   },
   "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
   "dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0",
   "from":"/Date(1541199600000)/",
   "to":"/Date(1541496190357)/",
   "offset":0,
   "count":5000,
   "historyState":""
}
</code>

**Response**

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<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">
  <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1">
    <errMsg/>
    <vals>
      <hv ts="2018-11-02T21:26:08.7936747Z" gt="2018-11-03T20:35:08.8060769Z">
        <n1:v>12754</n1:v>
      </hv>
      <hv ts="2018-11-03T20:41:09.0100479Z" gt="2018-11-05T11:35:08.7415158Z">
        <n1:v>12754</n1:v>
      </hv>
      <hv ts="2018-11-05T11:40:04.0077949Z" gt="2018-11-05T17:25:03.4285643Z">
        <n1:v>12754</n1:v>
      </hv>
      <hv ts="2018-11-05T17:28:03.4133447Z" gt="2018-11-05T19:40:03.0246122Z">
        <n1:v>12755</n1:v>
      </hv>
      <hv ts="2018-11-05T19:43:03.6499981Z" gt="2018-11-05T22:01:03.2620552Z">
        <n1:v>12756</n1:v>
      </hv>
      <hv ts="2018-11-05T22:04:03.1530787Z" gt="2018-11-06T02:37:03.454926Z">
        <n1:v>12757</n1:v>
      </hv>
      <hv ts="2018-11-06T02:40:03.61157Z" gt="2018-11-06T04:52:03.1759539Z">
        <n1:v>12758</n1:v>
      </hv>
      <hv ts="2018-11-06T04:55:03.14511Z" gt="2018-11-06T06:40:03.8621601Z">
        <n1:v>12759</n1:v>
      </hv>
      <hv ts="2018-11-06T06:43:03.2063072Z" gt="2018-11-06T08:55:03.3019409Z">
        <n1:v>12760</n1:v>
      </hv>
      <hv ts="2018-11-06T08:58:03.083875Z" gt="2018-11-06T09:10:03.0695797Z">
        <n1:v>12761</n1:v>
      </hv>
      <hv ts="2018-11-06T09:13:03.5389214Z" gt="2018-11-06T09:19:03.5238805Z">
        <n1:v>12761</n1:v>
      </hv>
      <hv ts="2018-11-06T09:22:03.9461503Z">
        <n1:v>12761</n1:v>
      </hv>
    </vals>
  </hist>
</getHistoryResult>


</code>


====api/set/history====

**Request**

   * URL: /api/set/history?format=xml
   * Method: POST
   * Content-Type: text/xml

Atribut **i** nastavuje **interval** ([[https://en.wikipedia.org/wiki/ISO_8601#Time_intervals|ISO 8601]]), v jakém by měla být uložena následující hodnota.

V **cred** lze použít i ověření pomocí jména a hesla, ale využití **tokenu** nabízí vyšší výkon.

Všechny časové údaje jsou očekávány v UTC.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<setHistoryRequest 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">
  <n2:cred t="xxxxx"/><!-- token should be used here -->
  <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>
    <hv ts="2020-03-17T11:00:00+00:00" i="P1D">
      <n1:v>2.0</n1:v>
    </hv>
    <hv ts="2020-03-18T11:00:00+00:00" i="P1D">
      <n1:v>2.3</n1:v>
    </hv>
  </vals>
</setHistoryRequest></code>

**Response**

   * 200 OK

====api/set/executeActions====

   * URL: /api/set/executeActions?format=xml
   * Method: POST
   * Content-Type: text/xml

===DoubleValue===

**Request**

<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 t="xxxxx"/> <!-- token -->
  <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>

**Response**

<code xml><?xml version="1.0" encoding="utf-8"?>
<executeActionsResponse xmlns:r="http://dev.rcware.eu/serialization/references" code="Ok" message="OK" xmlns="http://dev.rcware.eu/scada/error-reporting" /></code>

===PlanningCalendar===

   * v requestu je atribut "val" který odkazuje na index items v definici plánovacího kalendáře
   * pokud je kalendář číslený místo "val" se musí použít "dval" pro double hodnoty a "ival" pro integer hodnoty

**Request**

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" 
xmlns:n1="http://dev.rcware.eu/auth" 
xmlns:r="http://dev.rcware.eu/serialization/references">
  <n1:cred t="xxxxx"/> <!-- token -->
  <actionDefs projId="17d3ff08-40c1-41c0-ad6a-bad4489323c7">
    <actions>
      <actionDefItem propName="SET" dpId="396bcab1-1973-4dd9-91a9-284cdced00fb">
        <execParam r:type="0066EB7A-4118-4DA0-9E98-ECDE203CA945">
          <n2:value xmlns:n2="http://dev.rcware.eu/scada/basic-props">
            <n2:changes>
              <n2:layer name="Layer123">
                <n2:changes>
                  <n2:ch cmd="Create">
                    <n2:def start="2024-04-09T02:00:00.00Z" end="2024-04-09T06:00:00.00Z" state="Enabled" val="2" p="1" comment="test">
                      <n2:metadata/>
                    </n2:def>
                  </n2:ch>
                </n2:changes>
              </n2:layer>
            </n2:changes>
          </n2:value>
        </execParam>
      </actionDefItem>
    </actions>
  </actionDefs>
</executeActionsRequest></code>

**Response**

<code xml><?xml version="1.0" encoding="utf-8"?>
<executeActionsResponse xmlns:r="http://dev.rcware.eu/serialization/references" code="Ok" message="OK" xmlns="http://dev.rcware.eu/scada/error-reporting" /></code>




====api/get/values====

   * URL: /api/get/values?format=xml
   * Method: POST

===Output property===

Nejvhodnější způsob vyčtení aktuálních hodnot datových bodů (property "Output") z jednoho nebo více projektů.

**Request**

<code javascript>
{
 "cred": {
  "t": "xxxxxx" //token
 },
 "propNamesToSerialize": ["Output"],
 "offset": 0,
 "count": 1000,
 "serverState": null,
 "dps": [{
   "projId": "ba1a92f7-f213-4a72-90e4-f7142b50274b",
   "dpIds": ["e089dde2-a097-4e0d-8012-c8cf3dc62694", "1089dde2-a097-4e0d-8012-c8cf3dc62696"]
  }
 ]
}

</code>

**Response**

<code xml><?xml version="1.0" encoding="utf-8"?>
<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2020-04-07T07:46:34.850422Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
 <vals>
  <v projId="ba1a92f7-f213-4a72-90e4-f7142b50274b" dataVersion="637217783110000000" serverTime="2020-04-07T07:46:34.850422Z">
   <dps>
    <d id="e089dde2-a097-4e0d-8012-c8cf3dc62694" serAlr="true">
     <props>
      <p n="Output" t="2020-04-07T07:43:42.1000676Z" q="Bad" r:type="177e726a-3180-4152-bef2-6254e7055e1f">
       <n1:v>ON</n1:v>
      </p>
     </props>
    </d>
    <d id="1089dde2-a097-4e0d-8012-c8cf3dc62696" serAlr="true">
     <props>
      <p n="Output" t="2020-04-07T07:45:00.2408399Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
       <n1:v>0</n1:v>
      </p>
     </props>
    </d>
   </dps>
  </v>
 </vals>
</values></code>

===PlanningCalendar property===

**Request**

<code javascript>
{
 "cred": {
  "t": "xxxxxx" //token
 },
 "propNamesToSerialize": ["PlanningCalendar"],
 "offset": 0,
 "count": 1000,
 "serverState": null,
 "dps": [{
   "projId": "17d3ff08-40c1-41c0-ad6a-bad4489323c7",
   "dpIds": ["d1243034-0809-444d-a48a-d04d800b4095"]
  }
 ]
}

</code>

**Response**

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2024-04-16T09:27:44.9304393Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
  <vals>
    <v projId="17d3ff08-40c1-41c0-ad6a-bad4489323c7" dataVersion="638482651650000000" serverTime="2024-04-16T09:27:44.9304393Z">
      <dps>
        <d id="d1243034-0809-444d-a48a-d04d800b4095" serAlr="true">
          <props>
            <p n="PlanningCalendar" t="2024-04-15T11:50:38.2117669Z" q="Good" r:type="11c39f56-7d5e-489b-9615-51d2daaf25f8">
              <n1:v defaultValue="0" emailForNotifications="" type="1">
                <n1:layers>
                  <n1:l name="Decimal" type="" defaultValue="0">
                    <n1:events>
                      <n1:e rev="3">
                        <n1:def start="2024-04-11T04:00:00Z" end="2024-04-11T11:00:00Z" id="2" state="Enabled" dval="12.5" p="1" comment="test" pLayer="" lastEditedBy="admin" lastEdited="2024-04-11T13:35:01.2373164Z" />
                      </n1:e>
                      <n1:e rev="4">
                        <n1:def start="2024-04-11T22:00:00Z" end="2024-04-12T01:00:00Z" id="3" state="Enabled" dval="5.6" p="1" comment="test2" pLayer="" lastEditedBy="admin" lastEdited="2024-04-12T06:18:17.0853588Z" />
                      </n1:e>
                    </n1:events>
                    <n1:items />
                  </n1:l>
                  <n1:l name="Positive" type="" defaultValue="0">
                    <n1:events>
                      <n1:e rev="3">
                        <n1:def start="2024-04-11T10:00:00Z" end="2024-04-11T13:00:00Z" id="2" state="Enabled" ival="25" p="1" comment="test3" pLayer="" lastEditedBy="admin" lastEdited="2024-04-11T13:22:07.0652508Z" />
                      </n1:e>
                      <n1:e rev="5">
                        <n1:def start="2024-04-11T22:00:00Z" end="2024-04-12T01:00:00Z" id="5" state="Enabled" ival="30" p="1" comment="test4" pLayer="" lastEditedBy="admin" lastEdited="2024-04-12T06:18:17.0853759Z" />
                      </n1:e>
                    </n1:events>
                    <n1:items />
                  </n1:l>
                  <n1:l name="Negative" type="" defaultValue="0">
                    <n1:events>
                      <n1:e rev="6">
                        <n1:def start="2024-04-11T22:00:00Z" end="2024-04-12T01:00:00Z" id="7" state="Enabled" ival="-50" p="1" comment="test5" pLayer="" lastEditedBy="admin" lastEdited="2024-04-12T06:18:17.0854241Z" />
                      </n1:e>
                    </n1:events>
                    <n1:items />
                  </n1:l>
                </n1:layers>
              </n1:v>
            </p>
          </props>
        </d>
      </dps>
    </v>
  </vals>
</values>
</code>