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.
Other attributes are not implicitly returned in the answer form the SmartWeb server because of optimization but a client can ask for them through a special attribute returnAs
(below described).
The type
attribute may gain the following values:
Value of the type attribute | Description of the value type |
---|---|
"nan" | none |
"bool" | VBool type |
"int" | integer |
"real" | real number |
"station" | VStation type |
"alarm" | VAlarm type |
"process" | VProcess type |
"time" | integer (number of milliseconds from epoch) |
"timespan" | real number (number of seconds) |
"text" | text |
"array" | field of objects D2ApiValue |
"qval" | VQval type |
"record" | two-dimensional field (row, column) of values |
The list of all attributes of the Unival object is in the following table:
Attribute | Value type | Mandatory | Default value | Note |
---|---|---|---|---|
type | text | yes | ||
value | according to the type | no | unset attributes automatically mean invalid value, set attributes mean valid value (it the attribute is not overloaded in the status attribute) | |
valueTime | integer (number of milliseconds from epoch) | no | current time | time stamp |
valueTimes | two-dimensional field (row, column) of integers (number of milliseconds from epoch) | no | current time | time stamps of values in a structure, only for the "record" type |
alarmTime | integer (number of milliseconds from epoch) | no | time stamp of an alarm | |
alarmTimes | two-dimensional field (row, column) of integers (number of milliseconds from epoch) | no | time stamps of alarms in a structure, only for the "record" type | |
flags | field of texts (listed Flag type) | no | no flags | field of user flags, possible values are from "A" to "P" |
flagsSets | two-dimensional field (row, column) of text fields (listed Flag type) | no | no flags | two-dimensional field of fields of user flags of structure values, only for the "record" type |
limitStatus | text (listed LimitStatus type) | no | "InLimit" | limited state, possible values are: "InLimit", "VeryLow", "Low", "High", "VeryHigh", "LimitsProblem" |
limitStatuses | two-dimensional field (row, column) of text fields (listed LimitStatus type) | no | "InLimit" | two-dimensional field of limited statuses of structure values, only for the "record" type |
processAlarmStatus | text (listed ProcessAlarmStatus type) | no | "NoAlarm" | status of a process alarm, possible values are: "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 | two-dimensional field (row, column) of text fields (listed ProcessAlarmStatus type) | no | "NoAlarm" | two-dimensional field of statuses of process alarms ina structure, only for the "record" type |
status | text fields (listed Status type) | no | "Valid" | status fields, possible values are: "Valid", "ProcAlarm", "NoAckPAlarm", "PrAlSilent", "Weak", "NoAckValue", "Transient", "Default", "Manual", "AlCrit", "Unknown" |
statusSets | two-dimensional field (row, column) of text fields (listed Status type) | no | "Valid" | two-dimensional field of statuses of structure values, only for the "record" type |
formattedValue | text | no | in the attribute, the formatted value of D2000 object returns in the answer from the server, unnecessary when calling RPC methods | |
structType | text | yes | structure name, only for the "record" type, mandatory on every "record" type sent to D2000 | |
definition | D2RecordDefinition object | - | structure definition, only for the "record" type, set on every value with the "record" type returned from D2000 | |
returnAs | text | no | have sense only when calling RPC methods with output parameters, defines logical name which will have the returned output value | |
returnFields | text fields | no | empty field | a special attribute defines additional returning attributes required by a client from the server |
returnTransformation | ReturnTransformation object | no | null | only for the "record" type with one numerical column and growing time stamps of values, it contains the configuration of processing (downscaling) of a numerical column performed on a server before sending answers to a client, because of the big data range, values are described below |
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.
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" |
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.
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 |
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.
Typ stĺpca | Typ hodnoty |
---|---|
"bool" | typ VBool |
"integer" | celé číslo |
"real" | reálne číslo |
"time" | celé číslo (počet milisekúnd od epochy) |
"timespan" | reálne číslo (počet sekúnd) |
"text" | text |
"object" | podľa typu referencovaného D2000 objektu |
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" } }