Serialization of Data between Client and API Interface

Both the Comet and the REST API interfaces share the same way of communication serialization using JSON format. The only exception is calling SBA RPC methods which serve for sending and acquiring binary data from D2000 - in this case, the data is sent in a binary form. The JSON format is a universal format implemented almost in every programming language. Its advantage is not only native support in every browser but also easy readability for people since it is a text format. The disadvantage of the bigger capacity of a message in comparison with any binary format is minimalized by the use of a gzip compression implicitly supported by the REST and also the Comet API. 

Serialization of the Unival Type

The basic unit of data change between a client and the D2000 system is the Unival type - clustering basic object attributes in D2000. The following example of the unival value in the JSON format represents a value of a real number type with the Valid state.

{
  "type": "real",
  "value": 123.456,
  "status": ["Valid"]
}

Every Unival value has a clearly defined type with the use of the type attribute. In the case of sending Unival values into the D2000 system, the type attribute has to be always defined. The only exception is the possibility when we send instead of an object log of the Unival type the value directly, in our case 123,456. This value is automatically converted to the "real", type by the SmartWeb server since it is a value with a decimal point (in the case of sending a string, the type would be automatically set to the "text" value and in the case of sending an integer to the "int" value. 

123.456

The answer from the SmartWeb server never comes in this shortened log but in the "object" log with a defined type (type attribute) and a value (value attribute) if it is valid.

The type attribute may gain the following values:

The list of all attributes of the Unival object is in the following table:  

Implicitná konverzia jednoduchých JSON typov na Unival hodnotu

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.

Definovanie vrátených hodnôt z RPC metód

Atribút returnFields definuje logický názov výstupného parametra požadovaného klientom od servera.

 Na obrázku je znázornený príklad volania metódy SimpleSum klientom. Prvé dva parametre sú jednoduché JSON typy ktoré su implicitne konvertované na správne Unival hodnoty. Tretí parameter je výstupný a klient definuje v atribúte returnAs, logický názov pod ktorým mu bude výstupná unival hodnota vrátená, v tomto prípade je to logický názov "vysledok".

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.

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

{
  "type": "record",
  "structType": "SD.Arr_Real_Text",
  "value": [[1, "One"], [2, "Two"], [3, "Three"]]
}

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

{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "lttb",
    "threshold": 100
  }
}

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

{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "ohlc",
    "step": 86400,
    "discrete": true,
    "timestampPlacement": "Start"
  }
}