| Obsah |
|---|
Koncept univerzálneho API bol predstavený v kapitole Univerzálne API pre prístup do D2000. Skôr než budú popísané jednotlivé rozhrania REST a Comet API je potrebné v nasledujúcej kapitole popísať spôsob serializácie hodnôt a parametrov, ktorý je pri oboch rozhraniach totožný.
...
Obe rozhrania Comet aj REST API zdieľajú ten istý spôsob serializácie komunikácie prostredníctvom JSON formátu. Výnimku tvorí len volanie SBA RPC metód, ktoré slúžia na posielanie a získavanie binárnych dát z D2000 - v tomto prípade sa dáta posielajú v binárnej forme. JSON formát je univerzálnym formátom implementovaným snáď v každom programovacom jazyku. Jeho výhodou je nielen natívna podpora v každom prehliadači ale aj jednoduchá čitateľnosť človekom, pretože sa jedná o textový formát. Nevýhoda väčšieho objemu správy oproti akémukoľvek binárnemu formátu je minimalizovaná použitím gzip kompresie implicitne podporovanej ako v REST tak aj v Comet API.
Serializácia typu Unival
Základnou jednotkou výmeny dát medzi klientom aj D2000 systémom je typ Unival - zoskupujúci základné atribúty objektov v D2000. Nasledujúci príklad unival hodnoty v JSON formáte, reprezentuje hodnotu typu reálne číslo so stavom Valid.
...
Odpoveď zo Smart Web servera, nikdy nechodí v tomto skrátenom zápise, ale v "objektovom" zápise s definovaným typom (atribút type) a hodnotou (atribút value) ak je platná.
| Info |
|---|
Ostatné atribúty nie sú v odpovedi zo Smart Web servera implicitne vrátené kvôli optimalizácii, ale klient si ich vie vyžiadať cez špeciálny |
...
atribút |
Atribút type môže nadobúdať nasledovné hodnoty:
...
| Atribút | Typ hodnoty | Povinný | Predvolená hodnota | Poznámka |
|---|---|---|---|---|
| type | text | áno | ||
| value | podľa typu | nie | nenastavený atribút automaticky znamená neplatnú hodnotu, nastavený platnú (ak príznak nie je preťažený v atribúte status) | |
| valueTime | celé číslo (počet milisekúnd od epochy) | nie | aktuálny čas | časová značka |
| valueTimes | dvojrozmerné pole (riadok, stĺpec) celých čísel (počet milisekúnd od epochy) | nie | aktuálny čas | časové značky hodnôt v štruktúre, len pre typ "record" |
| alarmTime | celé číslo (počet milisekúnd od epochy) | nie | časová značka alarmu | |
| alarmTimes | dvojrozmerné pole (riadok, stĺpec) celých čísel (počet milisekúnd od epochy) | nie | časové značky alarmov v štruktúre, len pre typ "record" | |
| flags | pole textov (vymenovaný typ Flag) | nie | žiadny príznak | pole uživateľských príznakov, možné hodnoty sú "A" až "P" |
| flagsSets | dvojrozmerné pole (riadok, stĺpec) polí textov (vymenovaný typ Flag) | nie | žiadny príznak | dvojrozmerné pole polí uživateľských príznakov hodnôt štruktúry, len pre typ "record" |
| limitStatus | pole textov text (vymenovaný typ LimitStatus) | nie | "InLimit" | limitný stav, možné hodnoty sú: "InLimit", "VeryLow", "Low", "High", "VeryHigh", "LimitsProblem" |
| limitStatuses | dvojrozmerné pole (riadok, stĺpec) polí textov (vymenovaný typ LimitStatus) | nie | "InLimit" | dvojrozmerné pole limitných stavov hodnôt štruktúry, len pre typ "record" |
| processAlarmStatus | pole textov texto (vymenovaný typ ProcessAlarmStatus) | nie | "NoAlarm" | stav alarmu procesu, možné hodnoty sú: "NoAlarm", "ToOn", "ToOff", "On", "Off", "Err", "Oscillate", "ErrCmdOn", "ErrCmdOff", "SwToTrans", "SwToOff", "SwToOn", "SwToErr", "SwTrans", "SwOff", "SwOn", "SwErr", "ErrZalCmdOff", "HL", "VHL", "LL", "VLL", "ToHL", "ToVHL", "ToLL", "ToVLL", "ErrWriteCmd", "Change", "A29", "A30", "A31", "SysPrAl" |
| processAlarmStatuses | dvojrozmerné pole (riadok, stĺpec) polí textov (vymenovaný typ ProcessAlarmStatus) | nie | "NoAlarm" | dvojrozmerné pole stavov alarmu procesov v štruktúre, len pre typ "record" |
| status | pole textov (vymenovaný typ Status) | nie | príznak "Valid" | pole stavov, možné hodnoty sú: "Valid", "ProcAlarm", "NoAckPAlarm", "PrAlSilent", "Weak", "NoAckValue", "Transient", "Default", "Manual", "AlCrit", "Unknown" |
| statusSets | dvojrozmerné pole (riadok, stĺpec) polí textov (vymenovaný typ Status) | nie | príznak "Valid" | dvojrozmerné pole stavov hodnôt štruktúry, len pre typ "record" |
| formattedValue | text | nie | v atribúte sa vracia v odpovedi zo servera formátovaná hodnota objektu D2000 zo servera, nemá význam pri volaniach RPC metód | |
| structType | text | áno | meno štruktúry, len pre typ "record", povinný na každom type "record" vstupujúcom posielanom do D2000 | |
| definition | objekt D2RecordDefinition | - | definícia Štruktúry, len pre typ "record", nastavený na každom type každej hodnote s typom "record" vystupujúcom vracanej z D2000 | |
| returnFields | pole textov | nie | prázdne pole | špeciálny atribút definuje dodatočné návratové atribúty požadované klientom od servera, hodnoty sú popísané nižšie |
| returnTransformation | objekt ReturnTransformation | nie | null | len pre typ "record" s jedným číselnym stĺpcom a rastúcimi časovými značkami hodnôt, obsahuje konfiguráciu spracovania (downscalingu) časového radu, vykonávanom na serveri pred posielaním odpovede klientovi, kvôli veľkému rozsahu dát, hodnoty sú popísané nižšie |
Optimalizácia obsahu vrátenej hodnoty Unival
Kvôli minimalizácii prenášaných dát Unival objekty štandardne na výstupe z D2000 obsahujú len atribút type a value (ak je hodnota platná). V prípade potreby ostatných rozširujúcich atribútov hodnoty, ktoré poskytuje systém D2000, je možné pri volaní nastaviť atribút returnFields a v ňom vymenovať požadované atribúty. Hodnota atribútu returnFields má formát poľa textov. Prípustné hodnoty sú v nasledujúcej tabuľke.
| Hodnota v poli returnFields | Vypĺňané atribúty v odpovedi zo servera |
|---|---|
| "AlarmTime" | alarmTime, alarmTimes |
| "Flags" | flags, flagsSets |
| "LimitStatus" | limitStatus, limitStatuses |
| "ProcessAlarmStatus" | processAlarmStatus, processAlarmStatuses |
| "Status" | status, statusSets |
| "ValueTime" | valueTime, valueTimes |
| "FormattedValue" | formattedValue |
Implicitná konverzia jednoduchých JSON typov na D2ApiValue
Pre zjednodušenie práce cez API rozhrania je možné ako vstupné hodnoty do systému D2000 používať aj jednoduché typy namiesto objektov typu Unival. Takéto hodnoty majú automaticky nastavený príznak platnosti, čas vzniku na aktuálny čas a ostatné príznaky nadobúdajú ich predvolenú hodnotu.
| Typ formátu JSON | Zodpovedajúci typ Unival | Poznámka |
|---|---|---|
| boolean | "bool" | |
| number | "bool" | Ak je cieľový typ v D2000 BOOL. Čísla sú interpretované podľa poradia v type VBool. |
| number | "int" | Ak je cieľový typ v D2000 INT. Ak bolo zadané reálne číslo, tak bude zaokrúhlené na celé. |
| number | "real" | Ak je cieľový typ v D2000 REAL. |
| number | "time" | Ak je cieľový typ v D2000 TIME. Pozor: Číslo je interpretované ako počet sekúnd od 1972-01-01 00:00:00 UTC, nie ako počet milisekúnd od epochy. |
| string | "text" |