...
Tieto oblasti REST API rozhrania sú popísané v nasledujúcich kapitolách.
Obsah |
---|
Autentifikácia
Ako už bolo spomenuté v kapitole Ďalšie funkcie SmartWeb platformy, podporovaný spôsob Podporované spôsoby autentifikácie pre REST API je sú HTTP-BASIC a Api Keys.
Pre HTTP-BASIC . Tento typ autentifikácie sa posiela používateľské meno a heslo priamo v hlavičke každej HTTP požiadavky. To znamená že každý REST API request automaticky aj autentifikuje používateľa. V prípade neúspešnej autentifikácie server vracia v hlavičke odpovede HTTP status 404. Z tohto dôvodu nie je potrebné mať explicitné prihlasovanie do REST API rozhrania cez špeciálnu URL. Napriek tomu je optimálne tú funkciu extrahovať, kvôli aplikáciám v ktorých sa používatelia explicitne prihlasujú a teda aplikácia potrebuje overiť zadané overiť zadané meno a heslo.
Overenie úspešnosti autentifikácie je teda možné odoslaním prázdnej GET požiadavky s HTTP-BASIC autentifikáciou na adresu:
GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/auth/login
Odhlásenie sa realizuje odoslaním prázdnej GET požiadavky s HTTP-BASIC autentifikáciou na adresu:
GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/auth/logout
Info |
---|
Volanie explicitného odhlásenie je odporúčané z dôvodov že SmartWeb server udržuje session prihláseného používateľa REST služby (identifikovaného jeho prihlasovacím menom) až do expirácie sedenia konfigurovateľnej v autentifikačnej časti konfigurácie SmartWeb Platformy. |
Načítavanie hodnôt z archívu
Načítavanie hodnôt z archívu je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json
na adresu:
Pre Api Keys typ autentifikácie sa v HTTP hlavičke "X-API-Key" posiela aplikačný kľuč - vygenerovaný náhodný reťazec, prostredníctvom ktorého je možné sa autentifikovať. Vyhodou tohto spôsobu autentifikácie je, že sa neposiela meno a heslo do D2000 priamo v requeste. Smart Web aplikácia má tento reťazec vo svojej konfigurácii spárovaný s použivateľskym menom a heslom do D2000. Prihlasovacie údaje ako aj aplikačný kľuč sú bezpečne uložené v špeciálnom keystore na disku, vedľa konfiguračného súboru smartweb.json. Správu týchto kľučov je možné editovať cez Smart Web admin konzolu (web aplikáciu) dostupnú na URL: https://<doména.sk>/<názov aplikácie>/admin.
Overenie úspešnosti autentifikácie je možné spraviť aj samostatne odoslaním prázdnej GET požiadavky s HTTP-BASIC alebo Api Keys autentifikáciou na adresu:
GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/auth/login
Taktiež odhlásenie je možné realizovať odoslaním prázdnej GET požiadavky s HTTP-BASIC autentifikáciou na adresu:
GET POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/archive/<meno archívneho objektu>?beginTime=<celé číslo>&endTime=<celé číslo>&oversampleSeconds=<celé číslo>&limitDataLength=<celé číslo>returnFields=<text>
Význam jednotlivých parametrov je nasledovný:
...
text (definované Unival atribúty oddelené čiarkou )
...
auth/logout
Info |
---|
Volanie explicitného prihlásenia a odhlásenia nie je nevyhnutné, pretože autentifikačné údaje (HTTP BASIC alebo Api Keys) sa aj tak posielajú s každou požiadavkou v HTTP hlavičkách. A odhlásenie prebehne aj automaticky v prípade automatickej expirácie session do D2000 konfigurovateľnej v autentifikačnej časti konfigurácie SmartWeb Platformy. Niekedy je ale výhodné používať explicitné prihlásenie a odhlásenie v prípadoch keď toto API je využívané napr. z mobilnej aplikácie veľkým počtom používateľov. |
Načítavanie hodnôt z archívu
Načítavanie hodnôt z archívu je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json
na adresu:
GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/archive/<meno archívneho objektu>?beginTime=<celé číslo>&endTime=<celé číslo>&oversampleSeconds=<celé číslo>&limitDataLength=<celé číslo>returnFields=<text>
Význam jednotlivých parametrov je nasledovný:
Meno parametra | Typ | Povinný | Popis |
---|---|---|---|
beginTime | celé číslo (počet milisekúnd od epochy) | áno | začiatok časového intervalu vyžiadaných hodnôt archívu |
endTime | celé číslo (počet milisekúnd od epochy) | áno | koniec časového intervalu vyžiadaných hodnôt archívu |
oversampleSeconds | celé číslo (počet sekúnd) | nie | dĺžka intervalu v sekundách pre oversampling dát, ak nie je definovaný vrátia sa originálne dáta |
limitDataLength | celé číslo (počet hodnôt) | nie | maximálny počet vrátených hodnôt, ak nie je definovaný vrátia sa všetky hodnoty z intervalu |
returnFields | text (definované Unival atribúty oddelené čiarkou ) | nie | vyžiadané Unival atribúty, ktoré budú vrátené spolu s časovou známkou a hodnotou. Napr: "Status,Flags" |
Napríklad Napríklad pre nasledujúce HTTP GET volanie:
...
Každá archívna hodnota je reprezentovaná kvôli veľkosti prenášanej správy samostatným poľom, pričom prvý prvok poľa je vždy časová známka a druhý samotná hodnota. V prípade definovania ďalších návratových polí parametrom returnFields
sú tieto parametre vrátené v ďalších prvkoch poľa podľa poradia ako boli definované.
Volanie D2000 RPC metód
Načítavanie hodnôt EDA vektora
V prípade ak je nakonfigurované spojenie na EDA server, dá sa realizovať načitavanie a zápis hodnôt do EDA vektorov.
Načítavanie hodnôt EDA vektora je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json
na adresu:
GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/eda/<kód eda vektora>?beginTime=<celé číslo>&endTime=<celé číslo>&period=<text>
Význam jednotlivých parametrov je nasledovný:
Meno parametra | Typ | Povinný | Popis |
---|---|---|---|
beginTime | celé číslo (počet milisekúnd od epochy) | áno | začiatok časového intervalu vyžiadaných hodnôt archívu |
endTime | celé číslo (počet milisekúnd od epochy) | áno | koniec časového intervalu vyžiadaných hodnôt archívu |
period | reťazec alebo číslo identifikujúci prevzorkovaciu periódu | nie | dĺžka intervalu v sekundách pre oversampling dát, ak nie je definovaný vrátia sa originálne dáta |
Napríklad pre nasledujúce HTTP GET volanie:
dostaneme zo servera odpoveď s poľom archívnych hodnôt:
Blok kódu | ||
---|---|---|
| ||
{
"errorCode": "SUCCESS",
"profilingInfo": {
"numDbTaskRequests": 1,
"numDbAccesses": 3
},
"values": [
{
"status": [
"Valid"
],
"value": 999.9,
"time": 1633338999000
},
{
"status": [
"Valid"
],
"value": 100.1,
"time": 1633339000000
}
]
} |
Atribút errorCode identifikuje stav odpovede z EDA servera. Možné hodnoty sú SUCCESS alebo chybové stavy EDA servera: ERR_INTERNAL_ERROR, ERR_INVALID_PARAM_TYPE, ERR_TIMESTEP, ERR_INVALID_VALUE_TYPE, ERR_DB_ERROR, ERR_VECTOR_NOT_EXIST, ERR_INVALID_VECTOR_TYPE, ERR_LOGON, ERR_VECTOR_NAME, ERR_CONVERT_ERROR, ERR_NOT_IMPLEMENTED, ERR_RANGE_ERROR, ERR_VALUE_STATUS, ERR_END_WITHOUT_RETURN, ERR_SYNTAX_ERROR, ERR_EMPTY_SET_OF_VECTORS, ERR_CACHE_NOT_FOUND, ERR_CACHE_READ_CHANGED, ERR_CACHE_TOO_MANY_READS, ERR_CACHE_READ_WRITE_MISMATCH, ERR_CACHE_RECURSIVE_VECTOR_DEFINITION, ERR_CACHE_NO_MEMORY, ERR_TBLSPACE_NOT_EXIST, ERR_TIMESTEP_FOR_TBLSPACE, ERR_TBLSPACE_ALLREADY_EXIST, ERR_INSUFFICIENT_RIGHTS, ERR_CANCELED, ERR_VERSION_DOESNT_EXIST, ERR_NOT_ARCHIVED, ERR_ARCHIVE_ERROR, ERR_VECTOR_ALREADY_EXISTS, ERR_VERSION_ALREADY_EXISTS, ERR_ENV_DOESNT_EXIST, ERR_BATCH_DOESNT_EXIST, ERR_BATCH_ALREADY_RUNNING, ERR_BATCH_TOO_MANY_BATCHES, ERR_OUT_OF_MEMORY, ERR_PARAM_BLOCK_DOESNT_EXIST, ERR_PARAM_BLOCK_TOO_MANY, ERR_VALIDATION_FAILED.
Atribút profilingInfo uvádza profilovacie informácie o obsluhe požiadavky. V atribúte values sa nachádzajú hodnoty EDA vektora za daný interval.
Atribút status identifikuje priznaky danej hodnoty EDA vektora tak ako sú uložené v EDA databáze. Status môže nadobúdať nasledovné hodnoty: NotAvailable, Valid, Manual, Weak, FlagA, FlagB, FlagC, FlagD, Locked.
Zápis hodnôt do EDA vektora
Zápis hodnôt EDA vektora je možné realizovať cez POST požiadavku s HTTP hlavičkou Content-Type: application/json
na adresu:
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/eda/<kód eda vektora>
Napríklad pre nasledujúce HTTP POST volanie s nasledujúcim obsahom POST requestu, zapíšeme hodnoty do EDA vektora:
POST http://localhost/smartWeb/api/rest/v0/d2/eda/testvektor
Blok kódu | ||||
---|---|---|---|---|
| ||||
{
"values":[
{
"value":999.9,
"time":1633338999000,
"status":["Valid"]
},
... <dalsie hodnoty>
]
} |
odpoveď na zápis môže byť nasledovná
Blok kódu | ||
---|---|---|
| ||
{
"errorCode": "SUCCESS",
"profilingInfo": {
"numDbTaskRequests": 2,
"numDbAccesses": 12
}
} |
Atribút errorCode identifikuje stav odpovede z EDA servera. Možné hodnoty sú uvedené v predchádzajúcej podkapitole.
Volanie D2000 RPC metód
Cez REST rozhranie je možné volať D2000 RPC procedúry napísané v ESL aj v Jave. Volanie ESL RPC procedúr prebieha odoslaním POST požiadavky s HTTP hlavičkou Content-Type: application/json
na jednu z adries:
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/<meno eventu>/<meno RPC metódy>
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/interface/<meno eventu>/<meno interfacu>/<meno RPC metódy>
v prípade volania Java RPC su URL nasledovné:
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/java/<meno eventu>/<meno RPC metódy>
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/java/interface/<meno eventu>/<meno interfacu>/<meno RPC metódy>
Ak chceme volat RPC metodu smeno procesu namiesto mena eventu je možné použiť nasledovné URL adresyCez REST rozhranie je možné volať D2000 RPC procedúry napísané v ESL aj v Jave. Volanie ESL RPC procedúr prebieha odoslaním POST požiadavky s HTTP hlavičkou Content-Type: application/json
na adresu:
POST https://<doména<doména.sk>sk>/<názov aplikácie>/api/rest/v0/d2/rpc/japi/<meno eventu>procesu>/<meno RPC metódy>
v prípade volania Java RPC je URL nasledovná:
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/java/japi/interface/<meno procesu>/<meno eventu>interfacu>/<meno RPC metódy>
Telo odosielanej správy je JSON pole s parametrami volanej RPC. Výstupom takejto požiadavky sú hodnoty výstupných parametrov RPC uložené v JSON objekte, ktorého atribúty sú požadované názvy výstupných parametrov definované atribútmi returnAs
. Detaily serializácie parametrov RPC metód boli popísaná v predchádzajúcej kapitole. Príklad volania RPC s názvom TestInOut
na evente
E.E.SmartWebApiTutorial
s 5 parametrami, pričom prvý, tretí a štvrtý parameter sú vstupno-výstupné a definujú logický názov pre vracané hodnoty parametrov. Vstupné parametre (druhý a piaty) zároveň využívajú implicitnú konverziu na Unival objekt z jednoduchých JSON typov.
...
Nasledujúci príklad ilustruje volanie a implementaciu SBA RPC metódy pre stahovanie konkrétneho súboru pdf reportu z lokálneho súborového systému. Pozor uvedený príklad nie je vôbec vhodný pre reálne použítie a je uvedený iba pre ilustráciu použitia volania SBA RPC. Volanie SBA RPC metódy reportContract_PDF
v evente E.E.SmartWebApiTutorial
s parametrom id
ktorý identifikuje číslo reportu a tým pádom sťahovaného súboru.
GET
http://localhost/smartWebsmartweb/api/rest/v0/d2/sba/E.E.SmartWebApiTutorial/reportContract_PDF?fileName=report.pdf&id=10
...