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

Konfigurace WebAPI

V kořenové instalační složce IS FLORES 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.

Sekce [server]

cert_pfx

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

Výchozí hodnota: ""

Příklad nastavení:

server:
	cert_pfx: "C:\\mnt\\datashareone\\flores\\tslssl\\cert\\MyPKCS12Certificate.pkcs12"
	cert_password: "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 cert_password.

Sekce [api]

dataProtection

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.

Sekce [logs]

Konfigurace logování

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

Logování činnosti samotného Web API serveru

Ú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í:

path

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:\IS FLORES\Logs - správně
path: C:/IS FLORES/Logs - rovněž správně; standardní lomítka lze použít i na platformě Windows

path: "C:\IS FLORES\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:\\IS FLORES\\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.

level

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á

Logování na úrovni business logiky

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 IS FLORES. Tj. do souboru Nexus.cfg zadáte sekci Logs např. následovně:

[Logs]
Level=2
Enabled=1
LogsDirectory=C:\IS FLORES\logs\

Podrobnější informace o logování naleznete v samostatné kapitole Logování běhu aplikace.

Tip: Otestování funkčnosti

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 IS FLORES. Viz také příklad Základní zdroj (informace o systému) v kapitole Struktura URI.