Nastavenie Web API

Konfigurácia Web API spočíva v úpravách súboru APIServer.yaml. Popis jednotlivých parametrov, ktoré sú k dispozícii, nájdete v sekcii Konfigurácia WebAPI. Okrem toho môže byť pre prevádzku Web API potrebné upraviť tiež nastavenie prostredia na úrovni operačného systému. V prípade potreby môžete zapnúť a nakonfigurovať logovanie. K dispozícii je i tip, ako otestovať funkčnosť. Venujte tiež, prosím, pozornosť pokynom v sekciách Upozornenie, hlavne, ak prechádzate zo starších verzií.

V hostiteľskom OS je nutné nastaviť bránu firewall tak, aby bol voľný port, na ktorom Web API server počúva, viď ďalej konfigurácia Web API.

Ďalej, rovnako ako pre pracovné stanice je potrebné, aby mal server, kde beží služba Web API (resp. užívateľ, pod ktorým služba beží) nainštalované české prostredie. To je nutné hlavne z dôvodu správneho fungovania všetkých Quick report funkcií a správnosti navrátených výsledkov. Detailný popis nastavenia českého prostredia nájdete tu.

V koreňovej inštalačnej zložke ABRA Gen nájdeme šablónu konfiguračného súboru. Šablónu si zazálohujeme a premenujeme (odstraníme príponu .tmpl):

APIServer.yaml.tmpl → APIServer.yaml

Web API je možné spustiť i bez tohto kroku, potom pobeží s defaultným nastavením (ktoré zodpovedá obsahu šablóny), ale bez konfiguračného súboru nebudete mať možnosť nastavenie zmeniť.

Znak # bude pred riadkovým komentárom. Pokiaľ riadok začína týmto znakom, hodnota uvedená v riadku sa pri spracovaní konfiguračného súboru ignoruje a Web API použije hodnotu východiskovú.

Vo formáte yaml sú signifikantné medzery, konkrétne úroveň odsadenia určuje príslušnosť položky do určitého bloku. Z tohto dôvodu je dôležité na začiatku riadkov s parametrami nejaké medzery ponechať, aby bolo zrejmé, do ktorého bloku patria. Pokiaľ nastavujete hodnotu parametra, odmažte len samotný znak # a nechajte riadok pred dvojicou medzier.

Konfiguračný súbor obsahuje niekoľko sekcií s parametrami, ktoré si v ďalšom texte preberieme.

Adresa, na ktorej Web API počúva. Súvisiaci parameter: port

Východisková hodnota: 0.0.0.0

Východisková hodnota "0.0.0.0" znamená, že aplikácia bude dostupná na ľubovoľnej IPv4 adrese, ktorú má daný počítač pridelenú.

Pokiaľ používate webovú aplikáciu Úlohy a ponecháte parametre host a port vo východiskovom nastavení, adresa 0.0.0.0 môže spôsobiť, že sa "autokonfiguračnému mechanizmu" nepodarí naviazať spojenie. Viď Poznámky k umiestneniu aplikácie a pripojenie k dátam v popise webovej aplikácie Úlohy. V takom prípade je potrebné si vynútiť preťaženie hodnoty parametrov host a port špecifikovaných v súbore APIServer.yaml nastavením parametra URL v sekcii Tasks v súbore Nexus.cfg.

Port, na ktorom Web API počúva. Súvisiaci parameter: host

Východisková hodnota: 80

Pokiaľ používate webovú aplikáciu Úlohy a ponecháte parametre host a port vo východiskovom nastavení, adresa 0.0.0.0 môže spôsobiť, že sa "autokonfiguračnému mechanizmu" nepodarí naviazať spojenie. Viď Poznámky k umiestneniu aplikácie a pripojenie k dátam v popise webovej aplikácie Úlohy. V takom prípade je potrebné si vynútiť preťaženie hodnoty parametrov host a port špecifikovaných v súbore APIServer.yaml nastavením parametra URL v sekcii Tasks v súbore Nexus.cfg.

Cesta k súboru ApiLib.dll.

Východisková hodnota: null

Východisková hodnota null predpokladá, že sa súbory APIServer.jar a ApiLib.dll nachádzajú v rovnakej zložke. Pokiaľ tomu tak nie je, je potrebné týmto parametrom špecifikovať cestu k súboru ApiLib.dll, aby API server knižnicu našiel.

Minimálny počet súčasných pripojení k serveru (vláken).

Východisková hodnota: 16

Maximálny počet súčasných pripojení k serveru (vláken).

Východisková hodnota: 250

Určuje maximálnu veľkosť requestu v bytoch (B).

Východisková hodnota: 10000000 B (10 MB).

Cesta k certifikátu vo formáte PKCS #12 (typicky súbor s príponou .pfx) alebo do Java keystore. Súvisiaci parameter: certPassword

Východisková hodnota: ""

Príklad nastavenia:

server:
	certPfx: "C:\\mnt\\datashareone\\abra\\tslssl\\cert\\MyPKCS12Certificate.pkcs12"
	certPassword: "fk45235#!@41324zfaABCD"

Pokiaľ nie je certifikát zadaný, server komunikuje prostredníctvom http.

Pokiaľ je cesta k certifikátu neplatná alebo nesúhlasí heslo, server sa nespustí.

Pokiaľ sú oba parametre zadané správne, server komunikuje prostredníctvom https.

Pokiaľ máte certifikát vo formáte PEM a súkromný kľúč v samostatnom súbore, môžete ich "skombinovať" do certifikátu vo formáte PKCS #12 pomocou nástroja OpenSSL:

openssl pkcs12 -inkey MyPrivateKey.key -in MyPEMCertificate.crt -export -out MyPKCS12Certificate.pkcs12

Pri prevode je nutné poznať heslo k súkromnému kľúču MyPrivateKey.key, rovnako je možné zadať heslo k vytváranému MyPKCS12Certificate.pkcs12. Toto heslo následne nastavíte ako hodnotu parametra certPassword.

V niektorých prípadoch je nutné, aby certifikát obsahoval i takzvané Medziľahlé (sprostredkujúce) certifikačné autority. V opačnom prípade nie je certifikát úplný, čo následne vedie k problémom so spúšťaním niektorých služieb.

Heslo k certifikátu vo formáte PKCS #12 (typicky súbor s príponou .pfx) alebo do Java keystore. Súvisiaci parameter: certPfx

Východisková hodnota: ""

Viď popis pri parametri certPfx.

V prehliadači Google Chrome povoľuje API dopyt z verejnej siete do siete privátnej. Defaultnou hodnotou je true. Pokiaľ je hodnota false, komunikácia nebude možná.

Nepovinná sekcia. Sekcia slúži hlavne pre zadávanie viacerých IP adries protokolov IPv4 alebo IPv6, na ktorých bude server počúvať. Pokiaľ nie je sekcia uvedená, správa sa nastavenie bežným spôsobom. Pokiaľ sa sekcia uvedie, tak sa pri štarte servera vytvoria konektory pre každú položku tu uvedenú namiesto jediného podľa sekcie server.

Subsekce Connector může obsahovat položky Host, Port, Cert_pfx, Cert_password. Pokud nějaká není uvedená nebo je prázdná nebo nula (v případě portu), tak se hodnota vezme ze stejnojmenné položky v sekci Server.

Podle yaml specifikace hyphen (-) znamená položku seznamu. Subsekce Connectors musí být na stejné úrovni jako ostatní položky v sekci server.

Příklad použití subsekce Connectors

Zapnutie (true) alebo vypnutie (false) zohľadňovania všeobecnej ochrany dát.

Východisková hodnota: false

Kombinuje sa s nastavením položky Obísť ochranu dát vo vlastnostiach užívateľa, ktorý sa pre prístup k API využíva. Východisková hodnota je false.

APIServer.yaml, parameter dataProtection Agenda Užívatelia, položka Obísť ochranu dát Web API zohľadňuje ochranu dát

-

nie
false nie
true áno
-
nie
false nie
true nie

Zohľadňovanie ochrany dát môže mať (v závislosti na konkrétnej implementácii) výrazný negatívny dopad na výkon - pred nastavením tohto parametra na hodnotu true v produkčnom prostredí je potrebné prevádzku aplikácií využívajúcich Web API dôkladne otestovať.

Maximálny počet vláken, ktoré môžu súbežne spracovávať požiadavky.

Východisková hodnota: 64

Doba, po ktorej sú vlákna určené na spracovanie požiadaviek ukončené.

Východisková hodnota: 3600000

Ide o vlákna, ktorých maximálny počet je určený vyššie uvedeným parametrom threadPoolSize. V prípade potreby sú operatívne vytvárané vlákna nové.

Doba (v milisekundách), po ktorej je vlákno ukončené, pokiaľ sa počas nej požiadavku nepodarí spracovať (vybaviť). Počíta sa len doba samotného spracovania požiadavky, nie čas, kedy požiadavka čaká v rade. Po ukončení vlákna vráti server chybu 408 Request Timeout.

Východisková hodnota: 600000

Požiadavky sú zaraďované do radu v prípade, kedy je vyčerpaný maximálny počet aktívnych vláken daný hodnotou parametra threadPoolSize.

Doba (v milisekundách), počas ktorej požiadavka čaká v rade, než sa uvoľní vlákno, ktoré by ho mohlo začať spracovávať. Po uplynutí tejto doby vráti server chybu 503 Service Unavailable, požiadavka je z radu vyradená a je nutné ju zaslať znovu.

Východisková hodnota: 30000

Parameter bol vo verzii 21.3.5 odstránený.

Parameter ovplyvňoval, či sa má s každou požiadavkou realizovať nové prihlásenie.

V súčasnej dobe je každá požiadavka autorizovaná novým prihlásením automaticky. Pokiaľ je užívateľ s rovnakými prihlasovacími údajmi uložený v cache, vykoná sa prihlásenie len v prípade, pokiaľ medzitým došlo ku zmene (napr. nastavenie nového hesla).

Vďaka tomuto správaniu sa zmena prihlasovacích údajov užívateľa realizujúceho požiadavky prejaví okamžite. Zmenami sa môže rozumieť:

Ak prechádzate na verziu 21.3.5 z predchádzajúcej verzie 21.3.2, skontrolujte, či váš konfiguračný súbor APIServer.yaml neobsahuje už nepodporovaný parameter authorizeEachRequest, prípadne ho odstráňte.

Pokiaľ konfiguračný server obsahuje nepodporované parametre, Web API server sa nespustí. Toto správanie bude v budúcich verziách systému upravené.

V klauzuli Select se pro řetězení (konkatenaci) aktuálně používá operátor "||". Pokud je potřeba vrátit původní chování a pro řetězení použít operátor "+", je potřeba parametr nastavit na hodnotu True.

Východisková hodnota: False.

V případě práce s časem je nutné, pokud je hodnota nastavena na True, použít před uvedením času klíčové slovo timestamp.

Primárně je vykonání v EXE určeno pro požadavky, u kterých jsou problémy s během v threadu. Jedná se hlavně o tisky, skripting a v cokoliv, co vytváří vizuální prvky(i když se nakonec samozřejmě nezobrazují). Parametr není v konfiguraci předvyplněn, je potřeba jej v případě přepnutí na jiné než defaultní chování doplnit ručně.

Parametr defaultExecutor má dvě hodnoty:

  • inprocess - vykonání ve vláknu (threadu) - Výchozí hodnota.
  • outprocess - vykonání v externím EXE (použití této volby s sebou nese využití více paměti systému).

Počet vláken v Connection poolu pro neověřená (nepřihlášená) volání.

Doba v milisekundách, která určuje, jak dlouho se čeká na přidělení vlákna Connection poolu pro zpracování požadavku.

Doba v milisekundách, která určuje, jak dlouho je možné zpracovávat požadavek v rámci Connection poolu.

Parametr definuje maximální počet vláken dostupných v dedikovaném poolu pro uživatelské relace v endpointu /serverstate. Každé vlákno je vyhrazeno jednomu uživateli a spravuje jeho dočasnou mezipaměť, která slouží ke zpracování požadavků na business objekty (BO). Požadavky od stejného uživatele jsou zpracovávány serializovaně (v pořadí, v jakém přicházejí), aby se zabránilo kolizím v rámci relace.

Vlákna tohoto poolu jsou oddělená od standardních požadavků, což zajišťuje lepší správu výkonu a izolaci operací spojených s mezipamětí.

Východisková hodnota: 128

Parametr se týká nastavení Zpracování požadavků v mezipaměti.

Parametr určuje maximální dobu nečinnosti (v milisekundách) pro každé vlákno uživatelské relace v endpointu /serverstate. Pokud od posledního požadavku uplyne zadaná doba, je relace automaticky ukončena, vlákno uvolněno zpět do poolu a všechny mezipaměti přidružené k relaci jsou odstraněny. Toto nastavení umožňuje optimalizaci paměťových zdrojů a zabraňuje neomezenému hromadění neaktivních relací.

Východisková hodnota: 14400000

Parametr se týká nastavení Zpracování požadavků v mezipaměti..

Po přepnuti na true je do query podmínek where na položku odkazující na firmu doplněna podmínka i za předchůdce.

Parametr je důležitý při profilování API. Zde je třeba zadat cestu, do které se budou zapisovat profilovací data. Lze je načíst v aplikaci Profiler. Více viz postup Jak profilovat Web API.

profilePath: c:\ABRA\Logs\Profiler\

Parametr slouží k zapnutí autorizace nad kořenovým endpointem /. .

Výchozí hodnota: false

Navazuje na předchozí parametr. Pokud je zadána v předchozím parametru rootAuth: true, tak v tomto se zadává heslo pro autorizaci (zadává se v nezaheslované podobě). Přístup lze pak získat standardně, buď pomocí hlavičky authorization, metodou basic nebo pomocí query parametru auth. Query string je třeba sestavit zakódováním Base64url, viz kapitola Autentizace a autorizace.

Výchozí hodnota: bez hesla 

http://localhost:80?auth=Omhlc2xv

Parametr ovlivní dobu za kterou proběhne nová kontrola změny práv uživatele. Nastavením menšího timeoutu se nová práva projeví dřív, ale znamená to vyšší frekvenci dotazů na appserver(před spuštěním každého požadavku jsou to dotazy za všechny nakešované vlákna, které aktuálně nic neprovádějí). Záleží tedy na konkrétní zátěži apiserveru a potřebách klienta.

Nastavením na 0 se změny projeví okamžitě - to je výhodné zejména pro testování.

Východisková hodnota: 30 s. 

securityRightsCheckTimeoutMs: 30000

Parametr ovlivní, co bude vracet API dotaz bez definovaného parametru select nebo selectschema. Parametr má dvě hodnoty.

Ano - Znamená, že dotazy bez definovaného parametru select nebo selectschema budou na výstup vracet pouze ID dotazovaného objektu.

Ne - Výchozí hodnota. Při neuvedeném parametru select nebo selectschema vrací buď všechna pole v první úrovni (v případě, kdy se dotazujeme na seznam objektů), nebo všechna pole včetně rozvinutých vlastněných referencí a kolekcí (v případě, kdy se dotazujeme pouze na jeden objekt).

Od verze ABRA Gen 25.4 bude výchozí hodnota nastavena na Ano, to znamená, že dotazy bez uvedených parametrů budou vracet jen ID. I po této změně bude možné vrátit původní chování přepnutím na hodnotu Ne.

minimalSelectSchema: false

Adresárová cesta, do ktorej sú logy ukladané. Viac informácií viď popis v sekcii Konfigurácia logovania.

Východisková hodnota: ""

Úroveň podrobnosti logovania (čím vyššie číslo, tým detailnejšie logovanie). Viac informácií viď popis v sekcii Konfigurácia logovania.

Východisková hodnota: 1

Aktivuje logovanie. Pokiaľ chcete logovanie používať, zmeňte východiskovú hodnotu false na hodnotu true.

Východisková hodnota: false

Maximálna veľkosť logu v bajtoch. Východisková hodnota 0 znamená, že je veľkosť logu neobmedzená

Východisková hodnota: 0

Počet logov zaradených do rotácie. Viac informácií viď popis v sekcii Konfigurácia logovania.

Východisková hodnota: 1

Logovanie Web API má dve "úrovne".

Úpravami sekcie logs v konfiguračnom súbore APIServer.yaml je možné ovplyvňovať logovanie činnosti samotného Web API servera (APIServer.jar). Pokiaľ chcete zmeniť východiskovú hodnotu niektorého z parametrov, odstráňte znak # na začiatku príslušného riadka (dvojicu medzier za znakom # ponechajte).

# log configuration
logs:
#  path where logs are stored, when empty then it is a directory where API server is
#  path: ""
#
#  number of details increase with this number(max. level is 6) 
#  level: 1
										
#  enable/disable log
#  enabled: false
										
#  max size of log in bytes (0 is unlimited)
#  maxsize: 0
										
#  number of rotated logs when maxsize is set
#  maxcount: 1

Prostredníctvom súboru APIServer.yaml je možné konfigurovať nasledujúce parametre týkajúce sa logovania:

Adresárová cesta, do ktorej sú logy ukladané.

Východisková hodnota: ""

Východiskovou hodnotou je prázdny reťazec; pokiaľ túto východiskovú hodnotu nezmeníte, budú sa logy ukladať do rovnakej zložky, v ktorej sa nachádza Web API server (soubor APIServer.jar).

Pokiaľ v ceste používate spätné lomky a zároveň cestu uzavriete do úvodzoviek, z technických dôvodov musíte každú lomku uvodiť ďalšou spätnou lomkou, teda zdvojiť:

  • path: C:\AbraGen\Logs - správne
  • path: C:/AbraGen/Logs - tiež správne; štandardné lomky je možné použiť i na platforme Windows

  • path: "C:\AbraGen\Logs" - nie je možné použiť, pokus o spustenie Web API skončí chybou:

    Exception in thread "main" java.lang.RuntimeException: unable to read configuration file APIServer.yaml
  • path: "C:\\AbraGen\\Logs" - správne

Najjednoduchším riešením je cesty do úvodzoviek neuzatvárať - v skutočnosti úvodzovky nie sú potrebné, a to ani v prípade, kedy cesta obsahuje medzery.

Určuje, jaké informace a v jaké podrobnosti se do logu zapisují. Čím vyššie číslo, tým detailnejšie logovanie.

Možnosti:

    • 0 (severe) - do logu sa zapisujú len nasledujúce udalosti:

      • chyby, kvôli ktorým sa Web API server nepodarilo inicializovať/spustiť

    • 1 (warning) - Východisková hodnota. Udalosti úrovne 0 + naviac:

      • chyby pri inicializácii logovania

    • 2 (info) - Udalosti úrovní 0 a 1 + naviac:

      • informácia o (úspešnom) spustení Web API servera
      • informácia o aktuálnej konfigurácii
      • Informácia o adrese a porte, na ktorých počúva Javalin
    • 3 (config) - v súčasnej dobe sa nevyužíva

    • 4 (fine) - Udalosti úrovní 0, 1, 2 a 3 + naviac:

      • použitá cesta k ApiLib.dll
      • všetky zasielané požiadavky (len metóda a URL)
      • všetky doručené odpovede (len metóda a URL)

    • 5 (finer) - Udalosti úrovní 0, 1, 2, 3 a 4 + naviac:

      • všetky zasielané požiadavky (vrátane hlavičky a tela)
      • všetky doručené odpovede (vrátane hlavičky a tela)

    • 6 (finest) - v súčasnej dobe sa nevyužíva

Aktivuje logovanie. Pokiaľ chcete logovanie používať, zmeňte východiskovú hodnotu false na hodnotu true.

Maximálna veľkosť logu v bajtoch. Východisková hodnota 0 znamená, že je veľkosť logu neobmedzená (do logu sa zapisuje, pokiaľ sa nezaplní disk). Východiskovú hodnotu je vhodné zmeniť.

Skutočná veľkosť logu môže byť nepatrne vyššia o dĺžku jedného záznamu. Hodnota parametra sa kontroluje pred zápisom - pokiaľ je log menší ako maxsize, pridá sa do neho ďalší záznam (bez ohľadu na dĺžku záznamu), v opačnom prípade sa log uzavrie a založí sa nový.

Počet logov zaradených do rotácie.

Web API server vždy aktuálně zapisuje do logu "0".

Pokiaľ je potrebné do logu zapísať niečo ďalšie a veľkosť logu "0" presiahla nastavenú veľkosť maxsize, log "0" sa uzavrie, premenuje sa na "1", založí sa nový prázdny log "0" a nové záznamy sa zapisujú do neho. Pokiaľ sa opäť zaplní, log "1" sa premenuje na "2", log "0" sa uzavrie a premenuje na "1" a založí sa nový prázdny log "0".

Toto pokračuje, pokiaľ sa nedosiahne maximálneho počtu logov (maxcount). Pokiaľ je napr. maxcount: 5 a už existujú logy "0", "1", "2", "3" a "4", pri zaplnení logu "0" sa log "4" zmaže, "3" sa premenuje na "4", "2" sa premenuje na "3", "1" sa premenuje na "2", "0" sa uzavrie a premenuje na "1" a založí sa nový prázdny log "0".

Východiskovú hodnotu 1 je vhodné zmeniť hlavne v prípade, že máte nastavenú nenulovú hodnotu parametra maxsize. Pokiaľ si napr. nastavíte maxsize na 10485760 a maxcount ponecháte na východiskovej hodnote 1, hneď ako dosiahne veľkosť logu 10 MB (1024 x 1024 x 10), celý log sa zmaže a začne sa vytvárať nový a v tú chvíľu máte v logu len jeden záznam z poslednej logovanej akcie, všetky predchádzajúce záznamy sú stratené.

Logovanie spracovania požiadaviek Web API (na úrovni business logiky - tzn. čo sa deje následne potom, čo Web API server odovzdá požiadavku knižnici ApiLib.dll) sa konfiguruje ako akékoľvek iné logovanie činnosti ABRA Gen.

Podrobnejšie informácie o logovaní nájdete v samostatnej kapitole Logovanie Web API.

Pre zapnutie HTTPS je potrebné do konfiguračného súboru zadať hodnoty parametrov cert_pfx a cert_password. Protokol HTTPS sa začne používať automaticky.

Zabezpečená komunikácia vyžaduje použitie protokolu TLS 1.2.

Či sú všetky komponenty Web API správne nastavené a funkčné, je možné jednoducho vyskúšať zadaním nastavenej adresy a portu do internetového prehliadača, napr.

http://localhost:80/

V prípade úspechu sa zobrazí HTML tabuľka obsahujúca informácie o verzii, zoznam databázových spojení a odkaz na online nápovedu k systému AbraGen. Viď tiež príklad Základný zdroj (informácie o systéme) v kapitole Štruktúra URI.

 

Informace platná jen do verze 22.0. Od verze 22.1 využívá ABRA Gen znakovou sadu Unicode.

Pri práci s dátami prostredníctvom rozhrania Web API je nutné pamätať na skutočnosť, že všetky systémové položky sú v databáze systému ABRA Gen uložené v znakovej sade Windows-1250. Pri vytváraní požiadaviek a spracovaní odpovedí na nich preto používajte uvedenú znakovú sadu (kódovú stránku). Podrobnejšie viď poznámka Podporované znakové sady v kapitole Charakteristika systému ABRA Gen, produkty, podporované databázové servery.