Spuštění Web API

Pokud přecházíte na IS FLORES verzi 22.1 z verze 12.1 (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.

V této kapitole naleznete:

Rozhraní Web API je možné spouštět a provozovat jako aplikaci nebo jako službu:

  • provoz v režimu aplikace se zpravidla používá v testovacím prostředí
  • provoz v režimu automaticky spouštěné služby se zpravidla používá v produkčním prostředí

Ke spouštění, instalaci a odinstalaci rozhraní Web API slouží dodávaný PowerShell skript APIServer.ps1, který naleznete v instalační složce IS FLORES (ve stejné složce jako spustitelný soubor IS FLORES.exe).

Pro testovací provoz stačí rozhraní Web API spustit v režimu aplikace.

V ostrém provozu doporučujeme Web API spouštět jako službu. Tj. nejprve je zapotřebí Web API nakonfigurovat a poté službu nainstalovat (zaregistrovat), což provedete následovně (poté, co systém IS FLORES nainstalujete do požadovaného umístění):

  • Spusťte si konzoli PowerShell jako správce (ve Windows stiskněte kombinaci kláves Win-X a z kontextového menu zvolte možnost "Windows PowerShell (správce)").

    Pokud konzoli nespustíte jako správce, při spuštění skriptu s parametrem install nebo uninstall (viz níže) se automaticky spustí další instance konzole v administrátorském režimu a skript se spustí v ní (znovu). Pokud konzoli spustíte jako správce, skript se provede v aktuální konzoli (okně).

  • V konzoli spusťte dodávaný skript s parametrem install ze složky, kde je skript umístěn (uveďte celou cestu z pohledu počítače, na kterém službu instalujete):

    <cesta> .\APIServer.ps1 install

    Pokud se skript nespustí (v konzoli se zobrazí chybové hlášení), projděte si sekci Řešení problémů se spouštěním skriptu dále v této kapitole.

  • Spusťte správce služeb a zkontrolujte, zda se služba nainstalovala (ve výchozím nastavení se bude jmenovat "ABRA Gen® APIServer"). Ve vlastnostech služby se přepněte na záložku Přihlášení a v případě potřeby změňte uživatele, pod kterým se bude služba spouštět.

    Pokud spouštíte službu ze síťového umístění (specifikovaného pomocí UNC cesty), je tento krok povinný. Výchozí uživatel "Místní systémový účet" nemá přístup k síťovým prostředkům a službu by se vám nepodařilo spustit.

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

Případnou odinstalaci provedete stejným způsobem (z PowerShell konzole), pouze místo parametru install uvedete parametr uninstall.

<cesta> .\APIServer.ps1 uninstall

Pokud vám z nějakého důvodu nevyhovuje výchozí název služby ABRAGenAPIServer (ABRA Gen® APIServer), přečtěte si poznámku Alternativní název služby na konci této kapitoly.

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:\IS FLORES\APIServer.ps1 install
C:\ABRA\APIServer.ps1 : File C:\IS FLORES\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\IS FLORES\API\APIServer.ps1
\\server.company.local\dat\IS FLORES\API\APIServer.ps1 : File \\server.company.local\dat\IS FLORES\API\APIServer.ps1 cannot be loaded. The file \\server.company.local\dat\IS FLORES\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\IS FLORES\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:

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

Při instalaci je možné uživatelsky ovlivnit název služby ("zobrazovaný název služby", který se používá v seznamu služeb ve Windows). Výsledný název bude kombinací hodnoty volitelného parametru PowerShell skriptu, kterou uvedete při instalaci, a obsahu souboru nexus.cfg, pokud se nachází ve stejné složce jako skript APIServer.ps1. Parametry skriptu ovlivňují název služby, parametr ServiceNameSuffix v souboru Nexus.cfg způsobí doplnění přípony k tomuto názvu.

Příkaz pro instalaci služby ServiceNameSuffix v nexus.cfg Název služby Zobrazovaný název služby Příkaz pro odinstalaci služby 
APIServer.ps1 install
   ABRAGenAPIServer ABRA Gen® APIServer 
APIServer.ps1 uninstall
 
APIServer.ps1 install

[Server]
ServiceNameSuffix=Test

 ABRAGenAPIServerTest ABRA Gen® APIServer (Test) 
APIServer.ps1 uninstall
 
APIServer.ps1 install MyAPIServer "My API Server"
   MyAPIServer My API Server 

APIServer.ps1 uninstall MyAPIServer

nebo

APIServer.ps1 uninstall "My API Server"

 
APIServer.ps1 install MyAPIServer "My API Server"

[Server]
ServiceNameSuffix=Test

 MyAPIServerTest My API Server (Test) 

APIServer.ps1 uninstall MyAPIServer

nebo

APIServer.ps1 uninstall "My API Server"