REST API rozhranie implementované Smart Web SmartWeb platformou môžeme rozdeliť na nasledovné časti:
- rozhranie na autentifikáciu
- rozhranie na prístup k dátam a službám D2000 systému
- administrátorské rozhranie na monitorovanie volaní do D2000 a stavu Smart Web SmartWeb servera
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 Smart Web 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 Smart Web 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 Smart Web 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 https://<doména.sk>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ý:
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ý:
beginTime
endTime
oversampleSeconds
limitDataLength
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 prevzorkovanie 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 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
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 adresu:
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 adresy:
POST https://<doména.sk>POST https://<doména.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.SmartWeb_DemoSmartWebApiTutorial
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.
POST http://localhost/smartWeb/api/rest/v0/d2/rpc/E.E.SmartWeb_DemoSmartWebApiTutorial/TestInOut
Blok kódu | ||||
---|---|---|---|---|
| ||||
[ { "type": "bool", "value": "vTrue", "returnAs": "boolParam" // výstupná hodnota bude pod názvom boolParam }, 123, { "type": "real", "value": 10.9, "returnAs": "realParam", // výstupná hodnota bude pod názvom realParam "returnFields": ["ValueTime", "Status"] // k výstupnej hodnote sú požadované aj atribúty ValueTime a Status }, { "type": "time", "returnAs": "timeParam" // výstupná hodnota bude pod názvom timeParam }, "hello D2000" ] |
...
Parametre dotazu (časť za otáznikom) sú automaticky preposlané do SBA metódy tak, ako boli zadané do adresy. Jediný preddefinovaný parameter je fileName, ktorý hovorí, ako sa bude sťahovaný súbor volať (kvoli downloadovaniu z prehliadača)tak, ako boli zadané do adresy. Parameter fileName definuje meno sťahovaného súboru pod ktorým webový prehliadač uloží súbor na disk. Ak sa tento parameter nenastaví, tak názov downloadovaného súboru bude implicitne "file.dat". Okrem toho Smart Web server pridáva pre SBA RPC ešte parameter sessionUserName, kvoli identifikácii používateľa ktorý SBA RPC volá. Ostatné parametre závisia od konkrétnej implementácie volania SBA RPC metódy. SBA RPC metóda všetky zadané parametre dostane vo vstupnom poli bajtov (byte[])
.
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.SmartWeb_DemoE.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.SmartWeb_DemoSmartWebApiTutorial/reportContract_PDF?fileName=report.pdf&id=10
...
Blok kódu | ||
---|---|---|
| ||
package app.runnables; import app.wrappers.E$E.E$SmartWebSmartWebApiTutorial_Demo__$WRAPPER$__; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.Arrays; import java.util.HashMap; import java.util.List; public class E$SmartWeb_DemoE$E.SmartWebApiTutorial extends E$SmartWeb_DemoE$E.SmartWebApiTutorial__$WRAPPER$__ { public byte[] reportContract_PDF(byte[] urlParamsBytes) throws IOException { // naparsovanie poslaných URL paramatrov do hash-mapy final HashMap<String, String> parameters = getParametersFromUrlQueryString(urlParamsBytes); // Vyparsovanie parametra id do premennej final long contractId = Long.parseLong(parameters.get("id")); // Získanie mena aktuálneho používateľa volajúceho SBA RPC final longString contractIduserName = Long.parseLong(parameters.get("idsessionUserName")); System.out.println("DEBUG: Downloading contract with id " + contractId); // Vyrobenie cesty k súboru s daným reportom Path path = Paths.get("D:/D2000/Contract" + contractId + ".pdf"); // Načítanie obsahu súboru a jeho vrátenie ako pole bajtov return Files.readAllBytes(path); } /** * Utility metóda, vráti naparsované URL parametre z vstupného poľa byte[] **/ private HashMap<String, String> getParametersFromUrlQueryString(byte[] urlQueryStringBytes) throws UnsupportedEncodingException { final String urlParamsString = new String(urlQueryStringBytes, "UTF-8"); final List<String> paramPartsList = Arrays.asList(urlParamsString.split("&")); final HashMap<String, String> parameters = new HashMap<String, String>(); for (String paramPartsString : paramPartsList) { final String[] paramParts = paramPartsString.split("="); final String paramName = paramParts[0]; final String paramValue = paramParts.length > 1 ? paramParts[1] : null; parameters.put(paramName, paramValue); } return parameters; } }; |
...
Posielanie binárnych dát do D2000 je možné cez HTTP POST metódu na identickú url linku pri sťahovaní binárnych dát, s tou istou HTTP hlavičkou Content-Type: application/octet-stream.
POST https://<doména<doména.sk>sk>/<názov aplikácie>/api/rest/v0/d2/sba/<meno eventu>/<meno SBA RPC metódy>
...
Ako alternatíva k predchádzajúcej možnosti kódovania vstupných parametrov spolu s obsahom na strane klienta je volanie SBA RPC metódy cez HTTP POST s inou hodnotou HTTP hlavičky: Content-Type:
multipart/form-data.
V tomto prípade sa v telo POST volania kóduje podľa definovaného štandardu na posielanie uploadovanie obsahu formulárov aj s binárnymi súbormi z prehliadača. Smart Web SmartWeb podporuje aj tento formát na volanie SBA RPC metód. Vstupný parameter pri volani SBA RPC metódy bude v tomto prípade obsahovať obsah jhodnôt ednotlivých hodnôt jednotlivých polí formulára zazipovaný spôsobom ako bol popísaný v predchádzajúcej kapitole. T.j. na rozkódovanie parametrov je možné využiť už uvedenú Java metódu loadParameters
.
Info |
---|
Smart Web server v tomto prípade tak isto ako pri stiahnutí binárnych dát z D2000 cez HTTP GET, automatický pridáva pre SBA RPC aj parameter sessionUserName, kvoli identifikácii používateľa ktorý SBA RPC volá. |