Spuštění Web API serveru

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.

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.

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

[{...}]