Nastavení Web API | FLORES API dokumentace

V hostitelském OS je nutno nastavit bránu firewall tak, aby byly dostupné všechny porty, na kterých jednotlivé komponenty Web API naslouchají.

Konfigurace Workera

Je nutné šablonu vzorového konfiguračního souboru Workera \Doc\webapi\WebAPIWorker.cfg.tmpl přejmenovat (resp. odstranit koncovku tmpl) a nakopírovat do instalačního adresáře systému IS FLORES (tj. např. \IS FLORES\WebAPIWorker.cfg).

Konfigurační direktivy

Jednotlivé direktivy odpovídají názvům vlastností konfiguračního JSON dokumentu. Většinu direktiv je možné měnit pomocí parametrů spuštění souboru, které mají před nastavením v konfiguračním souboru přednost. V konfiguračním JSON dokumentu je nutné dodržet typy parametrů.

Tabulka A1 - Worker - Kořenový konfigurační objekt

Název direktivy Typ Parametr spuštění Popis

port

Integer

--port nebo -a

Port, na kterém je služba dostupná - pro komunikaci se Workera se Serverem.

Hodnota by měla být stejná jako hodnota direktivy port v konfiguraci Serveru.

auth_token

String

--auth-token nebo -t

Autorizační token systémových požadavků (doporučuje se změnit).

context_timeout

Integer

--context-timeout

Timeout přihlášení, po kterém dochází k revalidaci přihlašovacího údajů. Udává se v sekundách.

context_clear_period

Integer

--context-clear-period

Při přihlašování různých uživatelů a přepínání mezi spojeními jsou tyto informace cachovány, tato direktiva ovlivňuje periodu, po které jsou čištěny nepoužívané záznamy. Udává se v sekundách.

roll_cache

Boolean

Zapnutí (true) nebo vypnutí (false) cache číselníků.

Výchozí hodnota je true.

Neměňte výchozí nastavení této direktivy, pokud chcete používat QuickReport funkce pracující s číselníky, jako například NxGetStoreCardUnitPrice. Funkce by nedokázaly dohledat požadované hodnoty a v odpovědích na požadavky by se vracela hodnota 0.

data_protection

Boolean

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

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.

WebAPIWorker.cfg, direktiva data_protection	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 zapnutím této direktivy v produkčním prostředí je zapotřebí provoz aplikací využívajících Web API důkladně otestovat.

V minulosti byly součástí konfigurace Workera také parametry spojení (direktivy connection, username a password). V současné době se již tyto parametry v konfiguračním souboru nenastavují.

connection je při zasílání požadavků součástí URL, viz kapitola Struktura URI
username a password jsou při zasílání požadavků součástí HTTP hlavičky, viz kapitola Autentizace, přihlašování

Konfigurace Supervisora

Je nutné šablonu vzorového konfiguračního souboru Supervisora \Doc\webapi\WebAPISupervisor.cfg.tmpl přejmenovat (resp. odstranit koncovku tmpl) a nakopírovat do instalačního adresáře systému IS FLORES (tj. např. \ISFLORES\WebAPISupervisor.cfg).

Supervisor přiřazuje spuštěným Workerům porty, na kterých naslouchají. Pokud je tedy např. nastaven výchozí port 8000 a počet Workerů na 4, je nutno povolit ve firewallu porty 8000-8003.

Konfigurační direktivy

Jednotlivé direktivy odpovídají názvům vlastností konfiguračního JSON dokumentu. Většinu direktiv je možné měnit pomocí parametrů spuštění, které mají před nastavením v konfiguračním souboru přednost. V konfiguračním JSON dokumentu je nutné dodržet typy parametrů.

Tabulka B1 - Supervisor - Kořenový konfigurační objekt
Název direktivy	Typ	Parametr spuštění	Popis
	String	`--config`	Cesta ke konfiguračnímu souboru (pouze parametr spuštění).
port	Integer	`--port` nebo `-a`	Port, na kterém je Supervisor dostupný.
host_name	String	`--hostname` nebo `-h`
min_instances	Integer	`--min-instances`	Minimální počet Workerů, které Supervisor udržuje spuštěné.
max_instances	Integer	`--max-instances`	Maximální počet Workerů, které Supervisor udržuje spuštěné.
auth_token	String	`--auth-token`	Autorizační token systémových požadavků na Supervisora (doporučuje se změnit).
monitor_frequency	Integer	`--monitor-frequency`	Perioda monitorování dostupnosti Workerů. Udává se v sekundách.
worker	Object		Objekt nastavení parametrů spouštěných Workerů – jeho vlastnosti viz Tabulka B2 - Supervisor - Konfigurační objekt Worker.
main_server	Object		Objekt nastavení hlavního serveru (oznamování dostupnosti Workerů), viz Tabulka B3 - Supervisor - Konfigurační objekt main_server.

Tabulka B2 - Supervisor - Konfigurační objekt Worker
Název direktivy	Typ	Parametr spuštění	Popis
start_port	Integer	`--Worker-start-port`	Počáteční port přiřazovaný jednotlivým Workerům.
auth_token	String	`--Worker-auth-token`	Autorizační token systémových požadavků na Workera (změnit podle auth_token Workera).
shutdown_timeout	Integer	`--Worker-shutdown-timeout`	Čas, po který Supervisor čeká po nitifikaci vypnutí Workera na jeho zastavení; po jeho uplynutí je proces Workera ukončen "natvrdo" (kill). Udává se v sekundách.

Tabulka B3 - Supervisor - Konfigurační objekt main_server
Název direktivy	Typ	Parametr spuštění	Popis
auth_token	String	`--mainserver-auth-token`	Autorizační token systémových požadavků na hlavní server (změnit podle auth_token hlavního serveru).
address	String	`--mainserver-address`	Adresa hlavního serveru (včetně protokolu a portu, např.: http://mainserver.local:80)

Konfigurace serveru

Je nutné šablonu vzorového konfiguračního souboru \Doc\webapi\WebAPIServer.cfg.tmpl přejmenovat (resp. odstranit koncovku tmpl) a nakopírovat do instalačního adresáře systému IS FLORES (tj. např. \ISFLORES\WebAPIServer.cfg).

Konfigurační direktivy

Jednotlivé direktivy odpovídají názvům vlastností konfiguračního JSON dokumentu. Většinu direktiv je možné měnit pomocí parametrů spuštění souboru, které mají před nastavením v konfiguračním souboru přednost. V konfiguračním JSON dokumentu je nutné dodržet typy parametrů.

Tabulka C1 - Server - Kořenový konfigurační objekt
Název direktivy	Typ	Parametr spuštění	Popis
	String	`--cfg-file` nebo `-c`	Cesta ke konfiguračnímu souboru (pouze parametr spuštění).
inet_listen	String		IP, na které je server k dispozici.
port	Integer		Port, na kterém server naslouchá.
max_connections	Integer		Maximum otevřených spojení.
connections_per_worker	Integer		Počet spojení navázaných na downstream server (Worker).
auth_token	String		Autorizační token systémových požadavků (doporučuje se změnit).
supervisors	Array		Pole obsahující konfigurační objekty jednotlivých Supervisorů, viz Tabulka C2 - Konfigurační objekt Supervisors.
hosts_enabled	Array		Pole obsahující konfigurační objekty protokolů domén, viz Tabulka C3 - Konfigurační objekt hosts_enabled.
proxy_connection	Array		Pole obsahující konfigurační objekty timeoutů přeposílání, viz Tabulka C4 - Server - Konfigurační objekt proxy_connection.

Tabulka C2 - Server - Konfigurační objekt supervisors
Název	Typ	Parametr spuštění	Popis
url	String		URL Supervisora.
auth_token	String		Autorizační token systémových požadavků daného Supervisora.

Tabulka C3 - Server - Konfigurační objekt hosts_enabled
Název	Typ	Parametr spuštění	Popis
host	String		Název domény.
cert_pfx	String		Cesta k souboru certifikátu ve formátu PFX. V cestě je zapotřebí používat standardní lomítka nebo zpětná lomítka zdvojovat, viz upozornění v sekci Konfigurace HTTPS.
cert_pem	String		Cesta k souboru certifikátu ve formátu PEM.
cert_pem_keyfile	String		Cesta k souboru s privátním klíčem certifikátu (při použití certifikátu ve formátu PEM).
cert_ca	String		Cesta k souboru certifikační autority (při použití certifikátu ve formátu PEM).
cert_password	String		Heslo k certifikátu (privátnímu klíči), společné pro oba formáty certifikátů.

Tabulka C4 - Server - Konfigurační objekt proxy_connection
Název	Typ	Parametr spuštění	Popis
timeout	integer		Doba vypršení spojení při nečinnosti (v ms); defaultně 60000
connect_timeout	integer		Doba vypršení inicializace TCP spojení (v ms); defaultně 100
response_timeout	integer		Doba čekání na odpověď (nebo dílčí část odpovědi) (v ms); defaultně 30000
worker_connection_retrieve_timeout	integer		Doba čekání na uvolnění spojení pro Workera (v ms); defaultně 5000

Konfigurace HTTPS

Pro zapnutí HTTPS je třeba v konfiguraci Serveru uvést certifikát, který má být při komunikaci použit. Nastavuje se na objektu Hosta, viz Tabulka C3 - Server - Konfigurační objekt hosts_enabled.

Několik užitečných upozornění souvisejících s provozem HTTPS:

Pokud není uvedeno jinak, předpokládá se, že HTTPS servery naslouchají na portu 443 (nastavuje se direktivou "port" v hlavním objektu konfigurace Serveru, viz Tabulka C1 - Server - Kořenový konfigurační objekt).
Při použití HTTPS je na Serveru možné provozovat pouze jednoho Hosta (doménu).
Pokud na objektu Hosta v konfiguračním objektu hosts_enabled uvádíte cestu k souboru s certifikátem, pamatujte, že znak zpětného lomítka v souborech JSON slouží k uvozování řídicích znaků se speciálním významem (například konce řádků). Zpětná lomítka ve smyslu zpětných lomítek je proto zapotřebí zdvojovat (\\) nebo nahrazovat standardními (dopřednými) lomítky.

Oba níže uvedené příklady jsou v pořádku:
```
...
"hosts_enabled": [
	{
		"host": "localhost",
		"cert_pfx": "c:\\FLORES\\mycert.pfx",
		"cert_password": "password123"
	}
]
...
```
```
...
"hosts_enabled": [
	{
		"host": "localhost",
		"cert_pfx": "c:/FLORES/mycert.pfx",
		"cert_password": "password123"
	}
]
...
```

Typický příklad základního nastavení

Příklad předpokládá spouštění WebAPIServeru a WebAPISupervisora na jednom počítači (častá konfigurace).

Úpravy WebAPIWorker.cfg

zkontrolovat, zda je direktiva port nastavená na stejnou hodnotu jako stejnojmenná direktiva ve WebAPIServer.cfg (ve výchozím nastavení 80)

Úpravy WebAPISupervisor.cfg

zkontrolovat počet WebAPIWorkerů (direktivy min_instances a max_instances) - doporučuje se nastavit obě hodnoty na 1,5 až dvojnásobek počtu jader CPU.

Pro správnou funkci systému musí být hodnoty min_instances a max_instances stejné.
nastavit direktivu address v konfiguračním objektu main_server na platnou/používanou adresu WebAPIServeru

Stejnou adresu je zapotřebí uvést jako hodnotu direktivy host v konfiguračním objektu hosts_enabled v souboru WebAPIServer.cfg.

Úpravy WebAPIServer.cfg

uvést všechny dostupné hosty (domény a IP adresy, ze kterých je Web API dostupné) do hosts_enabled

Výjimkou je situace, kdy chceme provozovat HTTPS, pak je uveden pouze jeden host (WebAPIServer je pak dostupný pouze pod jednou doménou).
je doporučeno zvýšit worker_connection_retrieve_timeout (výchozí hodnota 5000) - při větším vytížení je jinak zbytečně rychle (a často) vracen status 503.

Kontrola obsazení portů

Je zapotřebí zkontrolovat, zda nejsou obsazeny porty, na kterých poslouchají jednotlivé komponenty Web API:

WebAPISupervisor.cfg:, direktiva port
WebAPISupervisor.cfg:, konfigurační objekt worker - direktiva start_port + počet workerů (např. pokud je start_port=8000 a počet workerů 3, budou obsazeny porty 8000, 8001 a 8002)
WebAPIServer.cfg:, direktiva port

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 adresy a portu WebAPIServeru 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í 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.

Časté chyby

Nastavení firewallu (blokování komunikace na portech uvedených v jednotlivých konfiguračních souborech).
Různé hodnoty direktiv min_instances a max_instances v konfiguraci WebAPISupervisora. Obě hodnoty musí být stejné.
Chybné nastavení komunikace mezi WebAPISupervisorem a WebAPIServerem
- Nesprávná adresa a token WebAPIServeru v nastavení WebAPISupervisora (v konfiguračním objektu main_server).
  
  Adresa musí odpovídat některému z hostů (domén/IP), který je v konfiguraci WebAPIServeru povolen (direktiva host v konfiguračním objektu hosts_enabled ve WebAPIServer.cfg).
  
  Z toho vyplývá, že pokud je na WebAPIServeru nastaveno používání HTTPS, musí zde být uvedena veřejná adresa (doména).
- V nastavení WebAPIServeru (v konfiguračním objektu supervisors) musí být správná adresa (a token) WebAPISupervisora. Typicky localhost.
Komunikace mezi WebAPISupervisorem a WebAPIServerem je zbytečně nastavena přes veřejnou IP adresu, když je možné použít localhost (WebAPISupervisor by měl být vždy na localhostu); situaci pak komplikuje firewall a partitioning sítě

Komunikace s WebAPIServerem přes veřejnou IP adresu je nutná při používání protokolu HTTPS.
Použití jednoduchých zpětných lomítek při specifikaci cesty k cerfitikátu v konfiguračním objektu hosts_enabled. Viz upozornění v sekci Konfigurace HTTPS.