Spuštění Web API serveru

Aktuálně jsou dvě možnosti spuštění Web API serveru. Jedna varianta pomocí *.exe programu, druhá možnost je spouštět Web API server powershellovým skriptem APIServer.ps1,Obě varianty si níže popíšeme.

API při spuštění kontroluje, že databáze je ve stavu spojení OK, jinak vrací chybu 400. Z kontroly jsou vyjmuty servisní endpointy maintenance a monitoring.

Pomocí programu

V adresáři s instalovanou ABRA Gen jsou k dispozici dva programy.

ApiServerCmd.exe

Jedná se o konzolovou variantu serveru, kde výstup a všechny diagnostické zprávy probíhají přímo v konzoli.

Spustí API server jako podproces
Zapisuje výstup a diagnostické zprávy přímo do konzole
Vhodné pro ladění a detekci chyb při startu serveru

ApiServer.exe

Chová se stejně jako aplikační server a podporuje více režimů běhu podle způsobu instalace viz níže.

Parametr	Popis parametru
-app	Spustí server jako proces na pozadí (background)
-install	Nainstaluje server jako Windows službu.
-uninstall	Odinstaluje službu ze systému.

Pro instalaci/odinstalaci je nutné, aby uživatel spouštěl příkazový řádek jako administrátor.

Název služby lze přizpůsobit parametrem ServiceNameSuffix v konfiguračním souboru nexus.cfg.

Vlastnosti serveru

Všechny varianty spuštění (včetně služby) automaticky restartují server v případě pádu Java procesu.
Tím je server robustnější a odolnější proti selhání.
Konfiguraci serveru v souboru apiserver.yaml lze měnit i za běhu – stačí ukončit Java proces, a server jej automaticky znovu spustí s novou konfigurací (není nutný restart celé služby).

Logování v případě problémů registrace

Pro ladění problémů při registraci (např. neplatný znak suffixu) je důležité zapnout logování, sekci [Log.Tool] v nexus.cfg. Platí i u jiných registrací než je apiserver. Výsledný log se bude jmenovat podle exe, které se spouští.

[Log.Tool]

Enabled=1

Level=6

Příklad chyby vypsané v logu:
29.07.2025 11:01:17.480 [2] 00001020 (Tool) Název služby ABRAGenApiServerTOHO-X obsahuje neplatné znaky(platné jsou jen velké a malé písmena bez diakritiky, číslice a podtržítko, název nesmí začínat číslicí).

V případě apiserver existuje i log konfigurovatelný v yaml souboru, který má v názvu taky apiserver, ale na rozdíl od logů konfigurovaných v nexus.cfg nemá v názvu abragen.

Konfigurace JVM

Parametry pro JVM se definují v konfiguračním souboru systému ABRA Gen, tedy nexus.cfg v sekci API Nacházejí se tam parametry pro nastavení garbage collectoru, maximální čerpání paměti JVM nebo možnosti zadání uživatelských parametrů.

Powershellový skript APIServer.ps1

Web API server se spouští powershellovým skriptem APIServer.ps1, který je k dispozici v instalačním adresáři ABRA Gen. Skript je nutné spouštět v terminálu Powershellu v režimu správce.

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>]}]

Pokud přecházíte na ABRA Gen verze 21.3 (nebo novější) z verze 21.2 (nebo starší), před instalací nové verze Web API serveru (způsobem popsaným níže) nejprve zastavte původní služby (WebAPISupervisor a WebAPIServer) a odinstalujte je. Viz sekce Přechod ze starší verze v kapitole Nastavení Web API.

Parametry spouštěcího skriptu

Skript APIServer.ps1 má jeden hlavní parametr, a to -Action, kterému předáváme tyto argumenty:

Argument	Popis argumentu
app	Skript spustí ApiServer v režimu aplikace a vyčkává.
launch	Skript spustí ApiServer v režimu aplikace, vypíše název procesu (java.exe), jeho PID a ukončí se. Proces ApiServeru běží na pozadí.
kill	Skript ukončí proces ApiServeru (java.exe).
install	Skript provede instalaci ApiServeru jako služby. Pro argument install jsou k dispozici tyto parametry: -ServiceName - Název služby -ServiceDisplayName - Zobrazovaný název služby -User - Uživatel Windows, pod kterým služba běží. Je třeba jej zadat ve správném formátu, např.: hostname\username - jde-li o lokální účet %userdomain%\username - jde-li o doménový účet -Password - Heslo uživatele Windows, pod kterým služba běží Po instalaci služby spusťte správce služeb a zkontrolujte, zda se služba nainstalovala (ve výchozím nastavení se bude jmenovat "ABRA Gen® APIServer"). Dále vyzkoušejte, zda se službu podaří spustit (ručně). Při nejbližší vhodné příležitosti také vyzkoušejte, zda se služba spustí automaticky po restartu počítače. Pokud spouštíte službu ze síťového umístění (specifikovaného pomocí UNC cesty), je spouštění pod konkrétním uživatelem povinné. Výchozí uživatel "Místní systémový účet" nemá totiž přístup k síťovým prostředkům a službu by se vám nepodařilo spustit. Název služby ovlivňuje také parametr ServiceNameSuffix v souboru nexus.cfg, Pokud je vyplněn, doplní se tento sufix jak k názvu služby, tak k zobrazovanému názvu služby.
uninstall	Skript provede odinstalaci služby ApiServeru. Pro argument install je k dispozici tento parametr: -ServiceName - Název služby

Instalace Web API serveru jako služby pod uživatelem Otmar Vokoun, který je v doméně ABRA.

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

Parametr -Action je nepovinný. Pokud je skript APIServer.ps1 volán bez parametrů, spustí se jako by byl volán s parametrem -Action app.

Ve verzi 25.4 došlo k přidání parametru do skriptu a pro jeho správné fungování je nutné spouštěcí skript odinstalovat a znova provést jeho instalaci nebo rovnou začít používat novou službu ApiServer.exe, která parametry čte z konfiguračního souboru Nexus.cfg, a při případné změně nepotřebuje reinstalaci

Kořenový endpoint

Kořenový enpoint zobrazí základní informace o produktu a seznamech spojení:

GET {server-api}:{port}

GET localhost:80

Výsledek zpracování 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
        }
    ]
}

Při načtení kořenového endpointu v html prohlížeči se zobrazí rozcestníková stránka se seznamem spojení a odkazy na dokumentaci a monitoringWeb API.

Příklad html stránky se seznamem spojení.

Monitoring Web API

Ve webovém prohlížeči k dispozici monitorovací přehledy a nástroje. Jsou přístupné na následujícím endpointu:

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

Více viz kap. Monitoring Web API.

Řešení problémů

Pokud se vám instalační skript nedaří spustit, pravděpodobně:

Máte nastavenou příliš restriktivní politiku spouštění PowerShell skriptů (výchozí politika je Restricted nebo RemoteSigned v závislosti na tom, zda skripty spouštíte na stanici nebo na serveru).
Instalační skript se nachází ve složce, která kvůli nastavení sdílení není z konzole PowerShell dostupná.

Podrobněji k jednotlivým skupinám problémů:

Příliš restriktivní politika spouštění skriptů

Zakázané spouštění skriptů se při pokusu o instalaci projevuje následovně:

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é vyřešit dočasnou změnou nastavené politiky.

Podrobnější informace o problematice politik spouštění skriptů, rozsahu platnosti politik (scope) atd. naleznete například na serveru SS64.com (kapitola Set-ExecutionPolicy).

Ladící nástroj ApiRunner.exe

Pro potřeby ladění lze využít nástroj ApiRunner.exe nacházející se v instalačním adresáři systému ABRA Gen. Je možné jej volat s těmito parametry:

-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

Zpracování funguje stejně jako přes APIServer. URL musí být v korektním formátu, protože se interně parsuje. Podpora pro hlavičky zatím není. Dotazy, které vyžadují autorizaci, je třeba doplnit o parametr auth (jedná se o user:heslo v base64 a poslední rovnítko se odstraní):

Jméno: Supervisor, Heslo: 12345. Převedeno do base64 je U3VwZXJ2aXNvcjoxMjM0NQ.

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

Výsledek 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

[{...}]