Spustenie Web API servera

Aktuálne sú dve možnosti spustenia Web API servera. Jedna varianta pomocou *.exe programu, druhá možnosť je spúšťať Web API server powershellovým skriptom APIServer.ps1. Obe varianty si nižšie popíšeme.

API pri spustení kontroluje, že databáza je v stave spojenia OK, inak vracia chybu 400. Zo kontroly sú vyňaté servisné endpointy maintenance a monitoring.

Pomocou programu

V adresári s nainštalovaným ABRA Gen sú k dispozícii dva programy.

ApiServerCmd.exe

Ide o konzolovú variantu servera, kde výstup a všetky diagnostické správy prebiehajú priamo v konzole.

Spustí API server ako podproces
Zapisuje výstup a diagnostické správy priamo do konzoly
Vhodné na ladenie a detekciu chýb pri štarte servera

ApiServer.exe

Správa sa rovnako ako aplikačný server a podporuje viac režimov behu podľa spôsobu inštalácie, viď nižšie.

Parameter	Popis parametra
-app	Spustí server ako proces na pozadí (background)
-install	Nainštaluje server ako Windows službu.
-uninstall	Odinštaluje službu zo systému.

Pre inštaláciu/odinštaláciu je nutné, aby používateľ spúšťal príkazový riadok ako administrátor.

Názov služby je možné prispôsobiť parametrom ServiceNameSuffix v konfiguračnom súbore nexus.cfg.

Vlastnosti servera

Všetky varianty spustenia (vrátane služby) automaticky reštartujú server v prípade pádu Java procesu.
Tým je server robustnejší a odolnejší voči zlyhaniu.
Konfiguráciu servera v súbore apiserver.yaml je možné meniť aj za behu – stačí ukončiť Java proces a server ho automaticky znovu spustí s novou konfiguráciou (nie je nutný reštart celej služby).

Logovanie v prípade problémov registrácie

Na ladenie problémov pri registrácii (napr. neplatný znak suffixu) je dôležité zapnúť logovanie, sekciu [Log.Tool] v nexus.cfg. Platí aj pri iných registráciách než je apiserver. Výsledný log sa bude volať podľa exe, ktoré sa spúšťa.

[Log.Tool]

Enabled=1

Level=6

Príklad chyby vypísanej v logu:
29.07.2025 11:01:17.480 [2] 00001020 (Tool) Názov služby ABRAGenApiServerTOHO-X obsahuje neplatné znaky (platné sú len veľké a malé písmená bez diakritiky, číslice a podčiarkovník, názov nesmie začínať číslicou).

V prípade apiserver existuje aj log konfigurovateľný v yaml súbore, ktorý má v názve tiež apiserver, ale na rozdiel od logov konfigurovaných v nexus.cfg nemá v názve abragen.

Konfigurácia JVM

Parametre pre JVM sa definujú v konfiguračnom súbore systému ABRA Gen, teda nexus.cfg v sekcii API. Nachádzajú sa tam parametre pre nastavenie garbage collectoru, maximálne čerpanie pamäte JVM alebo možnosti zadania používateľských parametrov.

Powershellový skript APIServer.ps1

Web API server sa spúšťa powershellovým skriptom APIServer.ps1, ktorý je k dispozícii v inštalačnom adresári ABRA Gen. Skript je nutné spúšťať v termináli Powershellu v režime správcu.

APIServer.ps1 [-Action {app | launch | kill | install [-ServiceName <jméno_služby> -ServiceDisplayName <zobrazované_jméno_služby> -User <uživatel> -Password <heslo>] | uninstall [-ServiceName <jméno_služby>]}]

Pokiaľ prechádzate na ABRA Gen verzie 21.3 (alebo novšie) z verzie 21.2 (alebo staršie), pred inštaláciou novej verzie Web API servera (spôsobom popísaným nižšie) najprv zastavte pôvodné služby (WebAPISupervisor a WebAPIServer) a odinštalujte ich. Viď sekcia Prechod zo staršej verzie v kapitole Nastavenie Web API.

Parametre spúšťacieho skriptu

Skript APIServer.ps1 má jeden hlavný parameter, a to -Action, ktorému odovzdávame tieto argumenty:

Argument	Popis argumentu
app	Skript spustí ApiServer v režime aplikácie a vyčkáva.
launch	Skript spustí ApiServer v režime aplikácie, vypíše názov procesu (java.exe), jeho PID a ukončí sa. Proces ApiServera beží na pozadí.
kill	Skript ukončí proces ApiServera (java.exe).
install	Skript vykoná inštaláciu ApiServera ako služby. Pre argument install sú k dispozícii tieto parametre: -ServiceName - Názov služby -ServiceDisplayName - Zobrazovaný názov služby -User - Používateľ Windows, pod ktorým služba beží. Je potrebné ho zadať v správnom formáte, napr.: hostname\username - ak ide o lokálny účet %userdomain%\username - ak ide o doménový účet -Password - Heslo používateľa Windows, pod ktorým služba beží Po inštalácii služby spustite správcu služieb a skontrolujte, či sa služba nainštalovala (vo východiskovom nastavení sa bude volať "ABRA Gen® APIServer"). Ďalej vyskúšajte, či sa službu podarí spustiť (ručne). Pri najbližšej vhodnej príležitosti tiež vyskúšajte, či sa služba spustí automaticky po reštarte počítača. Pokiaľ spúšťate službu zo sieťového umiestnenia (špecifikovaného pomocou UNC cesty), je spúšťanie pod konkrétnym používateľom povinné. Východiskový používateľ "Miestny systémový účet" totiž nemá prístup k sieťovým prostriedkom a službu by sa vám nepodarilo spustiť. Názov služby ovplyvňuje aj parameter ServiceNameSuffix v súbore nexus.cfg. Ak je vyplnený, doplní sa tento sufix ako k názvu služby, tak k zobrazovanému názvu služby.
uninstall	Skript vykoná odinštaláciu služby ApiServera. Pre argument install je k dispozícii tento parameter: -ServiceName - Názov služby

Inštalácia Web API servera ako služby pod používateľom Otmar Vokoun, ktorý je v doméne ABRA.

./Apiserver.ps1 -Action install -user ABRA\otmar.vokoun -password sR_tr154d

Parameter -Action je nepovinný. Ak je skript APIServer.ps1 volaný bez parametrov, spustí sa ako by bol volaný s parametrom -Action app.

Vo verzii 25.4 došlo k pridaniu parametra do skriptu a pre jeho správne fungovanie je nutné spúšťací skript odinštalovať a znova vykonať jeho inštaláciu alebo rovno začať používať novú službu ApiServer.exe, ktorá parametre číta z konfiguračného súboru Nexus.cfg, a pri prípadnej zmene nepotrebuje reinštaláciu.

Koreňový endpoint

Koreňový endpoint zobrazí základné informácie o produkte a zoznamoch spojení:

GET {server-api}:{port}

GET localhost:80

Výsledok spracovania dotazu:

Status: 200 OK

{
									"product": "ABRA Gen (Firebird)",
									"version": "25.4.0",
									"major_version": 25,
									"minor_version": 4,
									"localization": "CZ",
									"userlang": "cs",
									"version_type": "development",
									"connections": [
									{
									"name": "Demodata",
									"state": "OK",
									"islocked": false,
									"isexclusivelock": false,
									"ismain": true,
									"istesting": false,
									"isvalid": true
									},
									{
									"name": "Test",
									"state": "OK",
									"islocked": false,
									"isexclusivelock": false,
									"ismain": false,
									"istesting": false,
									"isvalid": true
									}
									]
							}

Pri načítaní koreňového endpointu v html prehliadači sa zobrazí rozcestníková stránka so zoznamom spojení a odkazmi na dokumentáciu a monitoringWeb API.

Príklad html stránky so zoznamom spojení.

Monitoring Web API

Vo webovom prehliadači sú k dispozícii monitorovacie prehľady a nástroje. Sú prístupné na nasledujúcom endpointe:

GET {server-api}:{port}/{spojeni}/monitoring

Viac viď kap. Monitoring Web API.

Riešenie problémov

Ak sa vám inštalačný skript nedarí spustiť, pravdepodobne:

Máte nastavenú príliš reštriktívnu politiku spúšťania PowerShell skriptov (východisková politika je Restricted alebo RemoteSigned v závislosti od toho, či skripty spúšťate na stanici alebo na serveri).
Inštalačný skript sa nachádza v zložke, ktorá kvôli nastaveniu zdieľania nie je z konzoly PowerShell dostupná.

Podrobnejšie k jednotlivým skupinám problémov:

Príliš reštriktívna politika spúšťania skriptov

Zákaz spúšťania skriptov sa pri pokuse o inštaláciu prejavuje nasledovne:

C:\AbraGen\APIServer.ps1 -Action install
									C:\ABRA\APIServer.ps1 : File C:\AbraGen\APIServer.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170

Problém je možné vyriešiť dočasnou zmenou nastavenej politiky.

Podrobnejšie informácie o problematike politík spúšťania skriptov, rozsahu platnosti politík (scope) atď. nájdete napríklad na serveri SS64.com (kapitola Set-ExecutionPolicy).

Ladiaci nástroj ApiRunner.exe

Na potreby ladenia je možné využiť nástroj ApiRunner.exe nachádzajúci sa v inštalačnom adresári systému ABRA Gen. Je možné ho volať s týmito parametrami:

-p --parentpid - pid of the parent process
										-t --terminatedevent - event name signalizing exit process
										-n --onevent - event name signalizing to process request is prepared and can be proceed
										-f --offevent - event name process signalize request was proceed and result can be read
										-m --method - http method
										-u --url - url
								-b --body - body

Spracovanie funguje rovnako ako cez APIServer. URL musí byť v korektnom formáte, pretože sa interne parsuje. Podpora pre hlavičky zatiaľ nie je. Dotazy, ktoré vyžadujú autorizáciu, je potrebné doplniť o parameter auth (ide o user:heslo v base64 a posledné rovnítko sa odstráni):

Meno: Supervisor, Heslo: 12345. Prevedené do base64 je U3VwZXJ2aXNvcjoxMjM0NQ.

ApiRunner.exe -m get -u http://localhost:81/demodata/firms?auth=U3VwZXJ2aXNvcjoxMjM0NQ

Výsledok dotazu:

ApiRunner - command line tool
											ABRA Gen [24.1.0 release cs-CZ]
											status 200 time: 0 ms
											Link=<http://localhost:81/demodata/api-docs/swagger.json#>; rel="describedBy"
											Content-Type=application/json
											Access-Control-Allow-Credentials=true
											Access-Control-Allow-Origin=*
											Access-Control-Allow-Headers=Origin, X-Requested-With, Content-Type, Accept, Authorization, Cache-Control
											Access-Control-Allow-Methods=GET,PUT,POST,DELETE
									[{...}]