História stránky

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

Both the Comet and the REST API interfaces share the same way of communication serialization using the 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 stateZá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.

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

Každý Unival hodnota má jasne definovaný typ pomocou atribútu type. V prípade posielania Unival hodnôt do D2000 systému atribút type musí byť vždy definovaný. Výnimku tvorí iba možnosť keď namiesto objektového zápisu Unival typu, pošleme priamo hodnotu, v našom prípade 123,456. Tá je SmartWeb serverom automaticky konvertovaná na typ "real", keďže sa jedná o hodnotu s desatinnou čiarkou (v prípade poslania reťazca by bol typ nastavený automaticky na hodnotu "text" a celého čísla na hodnotu "int").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

Odpoveď zo SmartWeb 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á.

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

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:

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

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

Kotva
implicitConversion implicitConversion

...

Implicit Conversion of Simple JSON Types to Unival Value

To simplify working through the API interface, it is possible to use simple types instead of Unival type objects as input values to the D2000 system. Such values have the validity attribute, the time of origin to the current time automatically set and other attributes gain their default value.

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.

Kotva
returnAs returnAs

...

Defining of Returned Values from RPC Methods

The attribute returnFields defines the logical name of an output parameter required by a client from the server. 

Image Added

In the figure, there is represented an example of the SimpleSum method calling by a client. The first two parameters are simple JSON types that are implicitly converted to right Unival values. The third parameter is an output one and the client defines in the returnAs attribute the logical name under which will be the output Unival value returned; in this case, it is the logical name 

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

Image Removed

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

Kotva
returnFields returnFields

...

Optimization of the Content of the Returned Unival Value

Because of the minimization of transmitted data, the Unival objects standardly contain on the output from D2000 only type and value attribute (if the value is valid). In the case of need of other extended value attributes, which are provided by the D2000 system, it is possible to set the returnFields attribute when calling and name required attributes in it.  The value of the returnFields attribute has a format of a text field. Allowed values are in the following table.

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

...

type Structure ("record")

...

The value of the structure type has its values and attributes stored as a two-dimensional field (row, column). Values gain the type according to the definition of structure in the D2000 system. It does not use extended attributesHodnota 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 Instead of them, it uses attributes 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.which are a two-dimensional field and components have the same type as the original attributes. Other attributes used only in structures are definition and structType. The definition attribute (D2RecordDefinition object) is always automatically set on all structural values that come from the D2000 system. This attribute describes columns' names and their types in a structured variable. Columns' types in a structure are a simplified version of Unival types.

The structType attribute is a text attribute and defines the name of the D2000 object of the structure definition type. It is mandatory to set it for every structured value that is inputted into the D2000 systemAtribú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

Transformations of Time Rows

Time row is a one-column structure in which values are real numbers and have increasing time stamps set. When displaying time rows, all values from requested interval are often not necessary or required (especially because of performance).  For such needs, transformations of time rows are implemented which decrease the number of transmitted data. It is possible to request the transformation by setting the transformation attribute on the output structured value.

Downsampling

Downsampling is reducing the number of values according to the given step or to the given number of values. The used algorithm tries as much as possible to keep the course of the curve of the original time row and does not smooth the final curve as the common resampling using averaging.  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

The 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.algorithm transforms the output time row in a way that for every interval it finds first, maximal, minimal and last value. Optionally when using this algorithm, it is possible to set whether the intervals should be continuous (successive intervals have the first and the last value common - by default) or discrete - the discrete attribute and where should be the time stamp of the value representing the whole interval placed (the beginning "Start" or in the middle "Midpoint" - by default) - the timestampPlacement attribute. 

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

...