Porovnávané verzie

Kľúč

  • Tento riadok sa pridal
  • Riadok je odstránený.
  • Formátovanie sa zmenilo.

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

Použiteľnosť jednotlivých API rozhraní

Na otázku prečo Smart Web SmartWeb implementuje dve a nie iba jedno API rozhranie, treba hľadať odpoveď vo vhodnosti použitia jednotlivých API pre rôzne situácie.

D2000 je realtime SCADA systém, ktorý je schopný zaznamenávať zmeny veľkého počtu napr. meraných bodov. Na to aby o týchto zmenách bola notifikovaná aj webová, prípadne iná aplikácia, je potrebné implementovať komunikačnú technológiu typu server-push, kedy server sám notifikuje klienta o zmene hodnoty objektu. V opačnom prípade je nevyhnutné, aby sa klient periodicky v nejakom časovom intervale pýtal servera či nenastali zmeny hodnôt ním sledovaných objektov. Tento spôsob komunikácie je ale veľmi nevýhodný. Pri dlhšom časovom intervale môže nastať situácia, že hodnota objektu sa zmení tesne po odpovedi servera a klient nie je informovaný o tejto hodnote, až kým znova neskontroluje server. Na druhej strane ak je časový interval príliš krátky a hodnota sa mení sporadicky, môže dochádzať úplne zbytočne k značnému plytvaniu komunikačných prostriedkov. Z týchto dôvodov sú situácie kedy komunikačnú technológiu podporujúcu server-push naozaj využijeme. Spôsob server–push komunikácie ale nie je štandardizovaný, a preto bolo potrebné vybrať jednu z existujúcich technológií, ktoré boli k dispozícii. Ideálne takú ktorá bude podporovať robusnú server-push komunikáciu medzi webovou aplikáciou v prehliadači a serverom. Po analýze možností bola vybraná technológia postavená na komunikačnom koncepte Comet implementovanom v robusnej java knižnici Cometd, s dlhou produkčnou históriou a použitím v cloudovom riešení s viac ako 150 000 klientmi.

Smart Web SmartWeb implementuje komunikačný koncept Comet predovšetkým kvôli získavaniu aktuálnych hodnôt a možnosti volať z D2000 aj vzdialené RPC metódy zaregistrované a vykonávané na klientovi. Keďže tieto prípady použitia nie sú vždy pre aplikáciu požadované, je možné použiť implementačne jednoduchšie a štandardizované rozhranie REST API, ktoré je podmnožinou Comet API.

...

Ako už bolo spomenuté v kapitole Ďalšie funkcie Smart Web SmartWeb platformy, spôsob autentifikácie jednotlivých rozhraní je rozdielny. REST API so svojou HTTP-BASIC autentifikáciou je skôr určené na komunikáciu pre ne-webových klientov, Comet API neautentifikovaného používateľa presmeruje na prihlasovací formulár (FORM autentifikácia) a preto je toto rozhranie momentálne prirodzene vhodné na komunikáciu webových aplikácii so serverom.

Info

V prípade potreby, vie cez Comet API komunikovať aj iný klient ako web aplikácia. Jedinou požiadavkou je aby bol schopný sa autentifikovať cez poslanie špeciálnej HTTP požiadavky emulujúcej prihlásenie cez prihlasovací formulár. Alternatívnou ale komplikovanejšou možnosťou je zobraziť priamo prihlasovací formulár používateľovi v špeciálnom okne s vnoreným prehliadačom a po úspešnom prihlásení extrahovať autentifikačné cookie pre ďalšie použitie v Comet API.

Serializácia dát medzi klientom a API rozhraniami

...

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.

Blok kódu
languagejs
titlePríklad zápisu Unival hodnoty
{
  "type": "real",
  "value": 123.456,
  "status": ["Valid"]
}

...

.

...

Blok kódu
languagejs
titleSkrátený zápis Unival hodnoty
123.456

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 returnAs (popísaný nižšie). 

Atribút type môže nadobúdať nasledovné hodnoty:

...

Zoznam všetkých atribútov Unival objektu je vypísaný v nasledujúcej tabuľke:

...

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

...

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.

...

Unival typu štruktúra ("record")

Hodnota typu štruktúra má svoje hodnoty a atribúty uložené ako dvojrozmerné pole (riadok, stĺpec). Hodnoty nadobúrajú typ podľa definície štruktúry v systéme D2000. Nepoužíva rozširujúce atribúty alarmTime, flags, limitStatus, processAlarmStatus, status a valueTime. Namiesto nich používa atribúty alarmTimes, flagsSets, limitStatuses, processAlarmStatuses, statusSets, valueTimes, ktoré sú dvojrozmerným poľom a prvky majú rovnaký typ ako pôvodné atribúty. Ďalšími atribútmi používanými len pri štruktúrach sú definition structType. Atribút definition (objekt D2RecordDefinition) je vždy automaticky nastavený na všetkých štruktúrovaných hodnotách, ktoré vystupujú zo systému D2000. Tento atribút popisuje názvy stĺpcov a ich typy v štrukturovanej premennej. Typy stĺpcov v štruktúre sú zjednodušenou verziou typov Unival.

...

Atribút structType je textový a určuje meno objektu D2000 typu definícia štruktúry. Je povinné ho nastaviť pre každú štrukturovanú hodnotu, ktorá vstupuje do systému D2000.

Blok kódu
languagejs
titlePríklad posielanéj hodnoty typu štruktúra - definícia SD.ArrReal_Text, 2 stĺpce (int, text), 3 riadky:
{
  "type": "record",
  "structType": "SD.Arr_Real_Text",
  "value": [[1, "One"], [2, "Two"], [3, "Three"]]
}
Blok kódu
languagejs
titlePríklad vracanej hodnoty typu štruktúra - definícia SD.ArrReal_Text, 2 stĺpce (int, text), 3 riadky:
{
  "type": "record",
  "definition": {
    "columnTypes": ["integer", "text"],
    "columnNames": ["digit", "name"]
  },
  "value": [[1, "One"], [2, "Two"], [3, "Three"]]
}

Transformácie časových radov

Pod časovým radom sa rozumie jednostĺpcová štruktúra, kde hodnoty sú reálne čísla a majú nastavené rastúce časové značky. Pri zobrazení časových radov často nie sú potrebné alebo žiadané (najmä kvôli výkonu) všetky hodnoty z požadovaného intervalu. Pre takéto potreby sú implementované transformácie časových radov, ktoré zmenšujú počet prenášaných dát. Transformáciu je možné vyžiadať nastavením atribútu transformation na výstupnej štrukturovanej hodnote.

Downsampling

Downsampling je zredukovanie počtu hodnôt podľa daného kroku alebo na daný počet hodnôt. Použitý algoritmus sa snaží čo najviac zachovať priebeh krivky pôvodného časového radu a nevyhladzuje výslednú krivku ako bežné prevzorkovanie používajúce priemerovanie.

Blok kódu
languagejs
titleVyžiadané zredukovanie algoritmom Largest Triangle Three Buckets na 100 hodnôt
{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "lttb",
    "threshold": 100
  }
}
Blok kódu
languagejs
titleVyžiadané zredukovanie algoritmom Largest Triangle Three Buckets s krokom 86400 sekúnd (1 deň)
{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "lttb",
    "step": 86400
  }
}

OHLC

OHLC (Open-High-Low-Close) algoritmus transformuje výstupný časový rad tak, že pre každý interval nájde prvú, maximálnu, minimálnu a poslednú hodnotu. Voliteľne pri tomto algoritme je možné nastaviť či majú byť intervaly spojité (po sebe nasledujúce intervaly majú spoločnú poslednú a prvú hodnota - predvolene) alebo diskrétne - atribút discrete a kde má byť umiestnená časová značka hodnoty reprezentujúcej celý interval (začiatok "Start" alebo stred "Midpoint" - predvolene) - atribút timestampPlacement.

Blok kódu
languagejs
titleVyžiadané OHLC transformácie s krokom 86400 sekúnd (1 deň) s diskrétnymi intervalmi a časovými značkami na začiatku intervalu
{ "type": "record", "structType": "SD.Arr_Real", "returnTransformation": { "type": "ohlc", "step": 86400, "discrete": true, "timestampPlacement": "Start" } }