Spuštění Web API serveru

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

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.

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

Pro ověření správného běhu serveru se zaměřte na logy serveru. Správně běžící server se pozná podle pěti po sobě jdoucích řádek, které začínají datem a následují po nápisu JAVALIN. Tyto řádky indikují, že server správně inicializoval všechny nezbytné komponenty a je připraven přijímat požadavky.

Pokud je v konfiguračním souboru nexus.cfg parametr Local nastaven na 0, což znamená, že server běží prostřednictvím externího aplikačního serveru, je nezbytné tento aplikační server spustit před spuštěním samotného API serveru. Pokud aplikační server není spuštěn předem, pokus o spuštění API serveru skončí chybou, protože nebude dostupná potřebná infrastruktura pro správnou funkci API serveru.

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

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.

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ů:

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.

Pokud instalujete Web API server z lokálního umístění, mělo by postačit nastavení politiky RemoteSigned. (Ke změně politiky je zapotřebí spustit PowerShell konzoli jako administrátor.)

set-executionpolicy remotesigned
Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at https:/go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): Y

Pokud Web API server instalujete v síťovém prostředí (umístění skriptu v rámci sítě specifikujete pomocí UNC, což je v produkčním prostředí častý případ), nemusí být politika RemoteSigned dostačující a je zapotřebí dočasně nastavit politiku Unrestricted.

\\server.company.local\app\AbraGen\API\APIServer.ps1
\\server.company.local\dat\AbraGen\API\APIServer.ps1 : File \\server.company.local\dat\AbraGen\API\APIServer.ps1 cannot be loaded. The file \\server.company.local\dat\AbraGen\API\APIServer.ps1 is not digitally signed. You cannot run this script on the current system. For more information about running scripts and setting execution policy, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
set-executionpolicy unrestricted
Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at https:/go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): Y
\\server.company.local\app\AbraGen\API\APIServer.ps1

Pokud se instalace zdaří (nezobrazí se žádné chybové hlášení), doporučujeme vrátit zpátky původní nastavení (remotesigned nebo restricted). Samotný provoz Web API nevyžaduje žádnou speciální politiku, úprava nastavení se provádí pouze kvůli úspěšnému spuštění a provedení PowerShell skriptu, který ve Windows vytvoří potřebnou službu.

set-executionpolicy remotesigned
Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at https:/go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): Y

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

Pokud instalujete Web API server umístěný ve sdílené složce, za určitých okolností může nastat situace, že složka se skriptem nebude z PowerShell konzole dostupná. V takovém případě může být řešením konfigurace parametru EnableLinkedConnections v systémových registrech:

  1. V editoru registrů najděte klíč HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System.
  2. Klikněte na něj pravým tlačítkem myši a z kontextového menu zvolte možnost Nový → Hodnota DWORD (32-bitová).
  3. Zadejte název hodnoty EnableLinkedConnections a potvrďte (Enter).
  4. Poklepejte na EnableLinkedConnections a do dialogu "Upravit hodnotu" zadejte hodnotu 1.
  5. Zavřete editor registrů a restartujte počítač.

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

[{...}]

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

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