Nastavení Web API

Konfigurace Web API spočívá v úpravách souboru APIServer.yaml. Popis jednotlivyých parametrů, které jsou k dispozici, naleznete v sekci Konfigurace WebAPI. Kromě toho může být pro provoz Web API zapotřebí upravit také nastavení prostředí na úrovni operačního systému. V případě potřeby můžete zapnout a nakonfigurovat logování. K dispozici je i tip, jak otestovat funkčnost. Věnujte též, prosím, pozornost pokynům v sekcích Upozornění, zejména, pokud přecházíte ze starších verzí.

V hostitelském OS je nutno nastavit bránu firewall tak, aby byl volný port, na kterém Web API server naslouchá, viz dále konfigurace Web API.

Dále, stejně jako pro pracovní stanice je potřeba, aby měl server, kde běží služba Web API (resp. uživatel, pod kterým služba běží) nainstalováno české prostředí. To je nutné zejména z důvodu správného fungování všech Quick report funkcí a správnosti navrácených výsledků. Detailní popis nastavení českého prostředí najdete zde.

V kořenové instalační složce ABRA Gen nalezneme šablonu konfiguračního souboru. Šablonu si zazálohujeme a přejmenujeme (odstraníme příponu .tmpl):

APIServer.yaml.tmpl → APIServer.yaml

Web API je možné spustit i bez tohoto kroku, pak poběží s defaultním nastavením (které odpovídá obsahu šablony), ale bez konfiguračního souboru nebudete mít možnost nastavení změnit.

Znak # uvozuje řádkový komentář. Pokud řádek začíná tímto znakem, hodnota uvedená v řádku se při zpracování konfiguračního souboru ignoruje a Web API použije hodnotu výchozí.

Ve formátu yaml jsou signifikantní mezery, konkrétně úroveň odsazení určuje příslušnost položky do určitého bloku. Z tohoto důvodu je důležité na začátku řádků s parametry nějaké mezery ponechat, aby bylo zřejmé, do kterého bloku patří. Pokud nastavujete hodnotu parametru, odmažte pouze samotný znak # a nechte řádek uvozený dvojicí mezer.

Konfigurační soubor obsahuje několik sekcí s parametry, které si v dalším textu probereme.

Adresa, na které Web API naslouchá. Související parametr: port

Výchozí hodnota: 0.0.0.0

Výchozí hodnota "0.0.0.0" znamená, že aplikace bude dostupná na libovolné IPv4 adrese, kterou má daný počítač přidělenou.

Pokud používáte webovou aplikaci Úkoly a ponecháte parametry host a port ve výchozím nastavení, adresa 0.0.0.0 může způsobit, že se "autokonfiguračnímu mechanismu" nepodaří navázat spojení. Viz Poznámky k umístění aplikace a připojení k datům v popisu webové aplikace Úkoly. V takovém případě si je zapotřebí vynutit přetížení hodnoty parametrů host a port specifikovaných v souboru APIServer.yaml nastavením parametru URL v sekci Tasks v souboru Nexus.cfg.

Port, na kterém Web API naslouchá. Související parametr: host

Výchozí hodnota: 80

Pokud používáte webovou aplikaci Úkoly a ponecháte parametry host a port ve výchozím nastavení, adresa 0.0.0.0 může způsobit, že se "autokonfiguračnímu mechanismu" nepodaří navázat spojení. Viz Poznámky k umístění aplikace a připojení k datům v popisu webové aplikace Úkoly. V takovém případě si je zapotřebí vynutit přetížení hodnoty parametrů host a port specifikovaných v souboru APIServer.yaml nastavením parametru URL v sekci Tasks v souboru Nexus.cfg.

Cesta k souboru ApiLib.dll.

Výchozí hodnota: null

Výchozí hodnota null předpokládá, že se soubory APIServer.jar a ApiLib.dll nacházejí ve stejné složce. Pokud tomu tak není, je zapotřebí tímto parametrem specifikovat cestu k souboru ApiLib.dll, aby API server knihovnu nalezl.

Minimální počet současných připojení k serveru (vláken).

Výchozí hodnota: 16

Maximální počet současných připojení k serveru (vláken).

Výchozí hodnota: 250

Určuje maximální velikost requestu v bytech (B).

Výchozí hodnota: 10000000 B (10 MB).

Cesta k certifikátu ve formátu PKCS #12 (typicky soubor s příponou .pfx) nebo do Java keystore. Související parametr: certPassword

Výchozí hodnota: ""

Příklad nastavení:

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

Pokud není certifikát zadaný, server komunikuje přes http.

Pokud je cesta k certifikátu neplatná nebo nesouhlasí heslo, server se nespustí.

Pokud jsou oba parametry zadané správně, server komunikuje přes https.

Pokud máte certifikát ve formátu PEM a soukromý klíč v samostatném souboru, můžete je "zkombinovat" do certifikátu ve formátu PKCS #12 pomocí nástroje OpenSSL:

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

Při převodu je nutné znát heslo k soukromému klíči MyPrivateKey.key, rovněž je možné zadat heslo k vytvářenému MyPKCS12Certificate.pkcs12. Toto heslo následně nastavíte jako hodnotu parametru certPassword.

Heslo k certifikátu ve formátu PKCS #12 (typicky soubor s příponou .pfx) nebo do Java keystore. Související parametr: certPfx

Výchozí hodnota: ""

Viz popis u parametru certPfx.

V prohlížeči Google Chrome povoluje API dotaz z veřejné sítě do sítě privátní. Defaultní hodnotou je true. Pokud je hodnota false, komunikace nebude možná.

Nepovinná sekce. Sekce slouží zejména pro zadávání více IP adres protokolů IPv4 nebo IPv6 na kterých bude server poslouchat. Pokud není sekce uvedena, chová se nastavení běžným způsobem. Pokud se sekce uvede, tak se při startu serveru vytvoří konektory pro každou položku zde uvedenou namísto jediného podle sekce 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

Zapnutí (true) nebo vypnutí (false) zohledňování obecné ochrany dat.

Výchozí hodnota: false

Kombinuje se s nastavením položky Obejít ochranu dat ve vlastnostech uživatele, který se pro přístup k API využívá. Výchozí hodnota je false.

APIServer.yaml, parametr dataProtection Agenda Uživatelé, položka Obejít ochranu dat Web API zohledňuje ochranu dat

-

ne
false ne
true ano
-
ne
false ne
true ne

Zohledňování ochrany dat může mít (v závislosti na konkrétní implementaci) výrazný negativní dopad na výkon - před nastavením tohoto parametru na hodnotu true v produkčním prostředí je zapotřebí provoz aplikací využívajících Web API důkladně otestovat.

Maximální počet vláken, které mohou souběžně zpracovávat požadavky.

Výchozí hodnota: 64

Doba, po které jsou vlákna určená pro zpracování požadavků ukončena.

Výchozí hodnota: 3600000

Jedná se o vlákna, jejichž maximální počet je určen výše uvedeným parametrem threadPoolSize. V případě potřeby jsou operativně vytvářena vlákna nová.

Doba (v milisekundách), po které je vlákno ukončeno, pokud se během ní požadavek nepodaří zpracovat (vyřídit). Počítá se pouze doba samotného zpracování požadavku, nikoli čas, kdy požadavek čeká ve frontě. Po ukončení vlákna vrátí server chybu 408 Request Timeout.

Výchozí hodnota: 600000

Požadavky jsou zařazovány do fronty v případě, kdy je vyčerpán maximální počet aktivních vláken daný hodnotou parametru threadPoolSize.

Doba (v milisekundách), po kterou požadavek čeká ve frontě, než se uvolní vlákno, které by ho mohlo začít zpracovávat. Po uplynutí této doby vrátí server chybu 503 Service Unavailable, požadavek je z fronty vyřazen a je nutné jej zaslat znovu.

Výchozí hodnota: 30000

Parametr byl ve verzi 21.3.4 odstraněn.

Parametr ovlivňoval, zda se má s každým požadavkem provádět nové přihlášení.

V současné době je každý požadavek autorizován novým přihlášením automaticky. Pokud je uživatel se stejnými přihlašovacími údaji uložen v cache, provede se přihlášení jen v případě, pokud mezitím došlo ke změně (např. nastavení nového hesla).

Díky tomuto chování se změna přihlašovacích údajů uživatele provádějícího požadavky projeví okamžitě. Změnami se může rozumět:

Přecházíte-li na verzi 21.3.4 z předchozí verze 21.3.1, zkontrolujte, zda váš konfigurační soubor APIServer.yaml neobsahuje již nepodporovaný parametr authorizeEachRequest, případně ho odstraňte.

Pokud konfigurační server obsahuje nepodporované parametry, Web API server se nespustí. Toto chování bude v budoucích verzích systému upraveno.

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ýchozí 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.

Max. počet možných session. Parametr se týká nastavení Stavu na serveru.

časový limit od posledního použití session, po kterém bude sezení smazáno (výchozí doba 4 hodiny). Parametr se týká nastavení Stavu na serveru.

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.

Adresářová cesta, do které jsou logy ukládány. Více informací viz popis v sekci Konfigurace logování.

Výchozí hodnota: ""

Úroveň podrobnosti logování (čím vyšší číslo, tím detailnější logování). Více informací viz popis v sekci Konfigurace logování.

Výchozí hodnota: 1

Aktivuje logování. Pokud chcete logování používat, změňte výchozí hodnotu false na hodnotu true.

Výchozí hodnota: false

Maximální velikost logu v bajtech. Výchozí hodnota 0 znamená, že je velikost logu neomezená

Výchozí hodnota: 0

Počet logů zařazených do rotace. Více informací viz popis v sekci Konfigurace logování.

Výchozí hodnota: 1

Logování Web API má dvě "úrovně".

Úpravami sekce logs v konfiguračním souboru APIServer.yaml je možné ovlivňovat logování činnosti samotného Web API serveru (APIServer.jar). Pokud chcete změnit výchozí hodnotu některého z parametrů, odstraňte znak # na začátku příslušného řádku (dvojici mezer za znakem # ponechte).

# 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

Prostřednictvím souboru APIServer.yaml je možné konfigurovat následující parametry týkající se logování:

Adresářová cesta, do které jsou logy ukládány.

Výchozí hodnota: ""

Výchozí hodnotou je prázdný řetězec; pokud tuto výchozí hodnotu nezměníte, budou se logy ukládat do stejné složky, ve které se nachází Web API server (soubor APIServer.jar).

Pokud v cestě používáte zpětná lomítka a zároveň cestu uzavřete do uvozovek, z technických důvodů musíte každé lomítko uvodit dalším zpětným lomítkem, tedy zdvojit:

  • path: C:\AbraGen\Logs - správně
  • path: C:/AbraGen/Logs - rovněž správně; standardní lomítka lze použít i na platformě Windows

  • path: "C:\AbraGen\Logs" - nelze použít, pokus o spuštění Web API skončí chybou:

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

Nejjednodušším řešením je cesty do uvozovek neuzavírat - ve skutečnosti uvozovky nejsou zapotřebí, a to ani v případě, kdy cesta obsahuje mezery.

Určuje, jaké informace a v jaké podrobnosti se do logu zapisují. Čím vyšší číslo, tím detailnější logování.

Možnosti:

    • 0 (severe) - do logu se zapisují pouze následující události:

      • chyby, kvůli kterým se Web API server nepodařilo inicializovat/spustit

    • 1 (warning) - Výchozí hodnota. Události úrovně 0 + navíc:

      • chyby při inicializaci logování

    • 2 (info) - Události úrovní 0 a 1 + navíc:

      • informace o (úspěšném) spuštění Web API serveru
      • informace o aktuální konfiguraci
      • informace o adrese a portu, na kterých naslouchá Javalin
    • 3 (config) - v současné době se nevyužívá

    • 4 (fine) - Události úrovní 0, 1, 2 a 3 + navíc:

      • použitá cesta k ApiLib.dll
      • veškeré zasílané požadavky (pouze metoda a URL)
      • veškeré obdržené odpovědi (pouze metoda a URL)

    • 5 (finer) - Události úrovní 0, 1, 2, 3 a 4 + navíc:

      • veškeré zasílané požadavky (včetně hlavičky a těla)
      • veškeré obdržené odpovědi (včetně hlavičky a těla)

    • 6 (finest) - v současné době se nevyužívá

Aktivuje logování. Pokud chcete logování používat, změňte výchozí hodnotu false na hodnotu true.

Maximální velikost logu v bajtech. Výchozí hodnota 0 znamená, že je velikost logu neomezená (do logu se zapisuje, dokud se nezaplní disk). Výchozí hodnotu je vhodné změnit.

Skutečná velikost logu může být nepatrně vyšší o délku jednoho záznamu. Hodnota parametru se kontroluje před zápisem - pokud je log menší než maxsize, přidá se do něj další záznam (bez ohledu na délku záznamu), v opačném případě se log uzavře a založí se nový.

Počet logů zařazených do rotace.

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

Pokud je zapotřebí do logu zapsat něco dalšího a velikost logu "0" přesáhla nastavenou velikost maxsize, log "0" se uzavře, přejmenuje se na "1", založí se nový prázdný log "0" a nové záznamy se zapisují do něj. Pokud se opět zaplní, log "1" se přejmenuje na "2", log "0" se uzavře a přejmenuje na "1" a založí se nový prázdný log "0".

Toto pokračuje, dokud se nedosáhne maximálního počtu logů (maxcount). Pokud je např. maxcount: 5 a již existují logy "0", "1", "2", "3" a "4", při zaplnění logu "0" se log "4" smaže, "3" se přejmenuje na "4", "2" se přejmenuje na "3", "1" se přejmenuje na "2", "0" se uzavře a přejmenuje na "1" a založí se nový prázdný log "0".

Výchozí hodnotu 1 je vhodné změnit zejména v případě, že máte nastavenou nenulovou hodnotu parametru maxsize. Pokud si např. nastavíte maxsize na 10485760 a maxcount ponecháte na výchozí hodnotě 1, jakmile dosáhne velikost logu 10 MB (1024 x 1024 x 10), celý log se smaže a začne se vytvářet nový a v tu chvíli máte v logu jenom jeden záznam z poslední logované akce, veškeré předchozí záznamy jsou ztraceny.

Logování zpracování požadavků Web API (na úrovni business logiky - tj. co se děje poté, co Web API server předá požadavek knihovně ApiLib.dll) se konfiguruje jako jakékoli jiné logování činnosti ABRA Gen.

Podrobnější informace o logování naleznete v samostatné kapitole Logování Web API.

Pro zapnutí HTTPS je třeba do konfiguračního souboru zadat hodnoty parametrů cert_pfx a cert_password. Protokol HTTPS se začne používat automaticky.

Zabezpečená komunikace vyžaduje použití protokolu TLS 1.2.

Zda jsou všechny komponenty Web API správně nastavené a funkční, je možné jednoduše vyzkoušet zadáním nastavené adresy a portu do internetového prohlížeče, např.

http://localhost:80/

V případě úspěchu se zobrazí HTML tabulka obsahující informace o verzi, seznam databázových spojení a odkaz na online nápovědu k systému AbraGen. Viz také příklad Základní zdroj (informace o systému) v kapitole Struktura URI.

 

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

Při práci s daty prostřednictvím rozhraní Web API je nutné pamatovat na skutečnost, že veškeré systémové položky jsou v databázi systému ABRA Gen uloženy ve znakové sadě Windows-1250. Při vytváření požadavků a zpracování odpovědí na ně proto používejte uvedenou znakovou sadu (kódovou stránku). Podrobněji viz poznámka Podporované znakové sady v kapitole Charakteristika systému ABRA Gen, produkty, podporované databázové servery.