Instalace a konfigurace API

Instalace a základní konfigurace API se týká pouze provozu ESO9 na prostředcích zákazníka (on-premise řešení). V rámci CLOUDu ESO9 řeší instalaci, konfiguraci a provoz API naše firma.

Podmínky provozu

API funguje jako samostatný web na webovém serveru IIS (Internet Information Server), který je součástí všech serverových edicí MS Windows Serveru. Instalace tedy počítá s existujícím a funkčním prostředím IIS.

API je vytvořeno v prostředí .NET 8, potřebuje tedy ke svému běhu:

• RunTime .NET v8.0 (je součástí instalačního balíčku)
• ASP.NET Core Runtime Hosting Bundle v8.0 – ke stažení na dotnet.microsoft.com

Postup instalace

Obsah instalace je k dispozici na podpora.eso9.cz.

1. V IIS založíme nový aplikační pool. Klíčové vlastnosti:

2. .NET CLR Version = No Managed Code

3. Managed pipeline mode = Integrated

4. Load User Profile = True

5. Identity = ApplicationPoolIdentity (pokud chceme pro přístup API k aplikační databázi používat SQL autentikaci), nebo vyhrazený Windows účet (pokud chceme pro přístup API k aplikační databázi používat Windows autentikaci)

6. Pomocí instalačního programu nainstalujeme API. Jméno virtuální složky zvolíme libovolně; v dalším textu budeme předpokládat, že API je nainstalováno ve složce c:\inetpub\wwwroot\JsonAPI.

7. Během instalace vybereme také aplikační pool – nejlépe ten, který jsme vytvořili v kroku 1.

8. Autentikaci ponecháme webu anonymní (Anonymous Authentication).

Postup konfigurace

Veškerá konfigurace se týká souboru appsettings.json ve webu API (typicky c:\inetpub\wwwroot\JsonAPI\appsettings.json).

Konfigurační soubor obsahuje zejména:

• Definici připojení k aplikační databázi (tzv. connection string).
• Přístupové údaje pro webový přístup k API.
• Registrační číslo zákazníka pro získání licence.

Položky Username a Password obsahují přístupové údaje pro Basic Authentication, které bude API vyžadovat při každém přístupu k datům. Pokud je API vystavené do Internetu, měly by být jméno i heslo velmi silné.

Přístup k databázi Windows účtem

Pokud plánujeme přistupovat k aplikační databázi přes Windows účet, použijeme v konfiguračním souboru formát:

ConnectionStrings – AppDB: „Data Source=server;Initial Catalog=database;Integrated Security=SSPI;"

Na úrovni SQL Serveru nastavíme pro Windows účet přístup pro čtení dat buď k celé databázi (tj. nastavíme účtu roli db_datareader pro celou aplikační databázi):

Nebo účet zařadíme do vyhrazené role, která má oprávnění pro čtení jen k vybraným databázovým objektům (tabulky, pohledy), z nichž budeme přes API číst data (tj. nastavíme roli oprávnění Select na vybrané databázové objekty):

Přístup k databázi SQL účtem

Pokud plánujeme přistupovat k aplikační databázi přes SQL účet, použijeme v konfiguračním souboru formát:

ConnectionStrings – AppDB: „Data Source=server;Initial Catalog=database;User Id=xxxx;Password=xxxx;"

Nastavení oprávnění vyhrazeného SQL účtu je řešeno analogicky s nastavením Windows účtu.

Licencování

info

Licencování se týká pouze zákazníků s vlastními servery. Pro zákazníky na CLOUDu ESO9 je API k dispozici zdarma.

Při provozu na vlastních serverech vyžaduje každá instance API jednu licenci. Pokud tedy na jednom webovém serveru poběží tři instance API, z nichž každá přistupuje k jiné databázi, je třeba mít zakoupené tři licence.

Licencování probíhá stejným způsobem jako licencování běžných aplikací ESO9 nebo jejich doplňků, tj. online pomocí webové služby. K tomu je zapotřebí zadat do konfiguračního souboru registrační číslo zákazníka do položky regNumber.

Pokud je API nainstalované na stejném webovém serveru, na němž již běží aplikační server ESO9, není zpravidla třeba tento server (resp. jeho HW otisk / aktivační klíč) znovu registrovat oproti licenční službě. Pokud se z daného serveru nikdy licence ESO9 neaktivovala (běžně se to dělá ze Správce ESO9), je třeba registraci aktivačního klíče serveru jednorázově provést.

Registrace aktivačního klíče

Stejně jako se při aktivaci licence aplikací ESO9 registruje HW otisk daného aplikačního serveru, je třeba zaregistrovat i webový server, na němž je provozováno JSON API. Registrace se provádí z příkazového řádku pomocí programu ESO9ExcelAPI.exe, který najdeme v instalačním adresáři API:

ESO9ExcelAPI.exe /register

Výsledek registrace je následně uložen v logovacím souboru v adresáři Logs.

Příklad úspěšné registrace:

2024-03-12T16:49:36.9426275+01:00  [INF] Registering FP. (3971d2d2)
2024-03-12T16:49:39.9395043+01:00  [INF] FP registered successfully. (4bcca35e)

Příklad neúspěšné registrace:

2024-03-12T16:51:43.5466877+01:00  [INF] Registering FP. (3971d2d2)
2024-03-12T16:51:46.9969519+01:00  [ERR] HW fingerprint not registred!
On-line licencování je aktivováno pro jiný aplikační server, než aktuální.
XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX  - uložený aktivační klíč.
YYYY-YYYY-YYYY-YYYY-YYYY-YYYY-YYYY  - aktuální aktivační klíč.
Došlo k přesunu na jiný server nebo k upgrade serveru.
Zažádejte o změnu aktivace.
Nalezen zákazník r.č. "xxxxxx" Testovací subjekt (cb3ae8ed)

tip

Pokud se registrace nepodaří, je třeba zažádat na Podpoře ESO9 o povolení registrace nového serveru, popř. rovnou zaslat aktuální aktivační klíč z logovacího souboru.

Kontrola funkční licence

Při startu aplikačního poolu v IIS se kontroluje licence pro danou databázi.

Licence v pořádku:

2024-03-12T16:31:45.6360734+01:00  [INF] Checking licence. (d66002f5)
2024-03-12T16:31:47.5331903+01:00  [INF] Licence checked successfully. (146308cb)

Licence není dostupná:

2024-03-12T16:09:03.9168193+01:00  [INF] Checking licence. (d66002f5)
2024-03-12T16:09:05.7161384+01:00  [ERR] Not licenced!

warning

Nepodaří-li se úspěšně zalicencovat API, kontaktujte prosím Podporu ESO9.

Provoz API v kontejneru

JSON API lze provozovat (kromě samostatné instalace, viz výše) i v Docker kontejneru. Výhodami kontejnerizace jsou zejména:

• Izolace prostředí – nezávislost na OS a verzích knihoven. Aktuální verze API je připravena na provoz v Dockeru pod Windows i pod Linuxem.
• Snadná a rychlá instalace i aktualizace – stačí stáhnout image. Základní image pro obě prostředí (Windows i Linux) je k dispozici na vyžádání v naší společnosti.
• Jednoduché škálování – další instanci API spustíte z existujícího image v řádu sekund.
• Snadná migrace mezi servery – přenositelný kontejner.
• Automatizace nasazení.
• Jednoduché zálohování a obnova – práce s image a snapshoty.