QASIDA.API beží na Windows ako služba Windows. Obsahuje vlastný .NET runtime, .NET preto netreba inštalovať.
Odporúčaný spôsob inštalácie na Windows je Qasida API inštalátor. Tento návod popisuje ručnú inštaláciu, napr. keď inštalátor nemožno použiť. Inštalátor navyše automaticky nastaví práva účtu služby na vlastnú službu a pri ďalšej inštancii kľúč
QasidaUpdate:ApiServiceName– pri ručnej inštalácii to treba urobiť podľa tohto návodu.
Pred inštaláciou overte, že prostredie spĺňa systémové požiadavky QASIDA.API a požiadavky na automatickú aktualizáciu.
Štandardný inštalačný koreň je
C:\Qasida. Upravte ho podľa prostredia zákazníka.
$TEMP = "C:\XXXX"
$QASIDAAPI_INSTALL_FILE = "$TEMP\QasidaApi.zip"
$QASIDAAPI_INSTANTCLIENT_FILE = "$TEMP\InstantClient.zip"
$QASIDAAPI_BASE = "C:\Qasida\QasidaAPI"
$QASIDAAPI_SERVICE_NAME = "AssecoQasidaAPI"
$QASIDAAPI_SERVICE_DESCRIPTION = "Asseco Solutions - Qasida API Service"
$QASIDAAPI_VIRTUAL_SERVICE_NAME = "NT SERVICE\AssecoQasidaAPI"
Inštalačný balík QASIDA.API (QasidaApi.zip) obsahuje podadresáre pre jednotlivé platformy. Rozbaľte len časť API pre Windows:
New-Item -ItemType Directory -Path $QASIDAAPI_BASE
New-Item -ItemType Directory -Path "$QASIDAAPI_BASE\Api"
Expand-Archive -Path "$QASIDAAPI_INSTALL_FILE" -DestinationPath "$TEMP\QasidaApi_extract"
Copy-Item -Path "$TEMP\QasidaApi_extract\Api\Windows\*" -Destination "$QASIDAAPI_BASE\Api" -Recurse
Remove-Item -Path "$TEMP\QasidaApi_extract" -Recurse -Force
Oracle Instant Client (vrátane SQL*Plus) sa dodáva ako samostatný balík InstantClient.zip (modul ORACLIENT v AsolHub) s rovnakými podadresármi pre jednotlivé platformy. SQL*Plus je potrebný pre aktualizácie databázových skriptov. Časť pre Windows rozbaľte do adresára InstantClient vedľa adresára Api:
New-Item -ItemType Directory -Path "$QASIDAAPI_BASE\InstantClient"
Expand-Archive -Path "$QASIDAAPI_INSTANTCLIENT_FILE" -DestinationPath "$TEMP\InstantClient_extract"
Copy-Item -Path "$TEMP\InstantClient_extract\Windows\*" -Destination "$QASIDAAPI_BASE\InstantClient" -Recurse
Remove-Item -Path "$TEMP\InstantClient_extract" -Recurse -Force
Adresár
InstantClientnechajte vedľa adresáraApi($QASIDAAPI_BASE\InstantClient). Ak kľúčSystemMaintenance:SpinDatabaseUpdate:SqlPlusnie je nastavený alebo ukazuje na neexistujúci súbor, selfupdate hľadá SQL*Plus iba na tomto mieste (pozri appsettings.json).
Ak sa
sqlplus.exenespustí (napr. s chybou o chýbajúcomVCRUNTIME140.dllaleboMSVCR*.dll), nainštalujte Microsoft Visual C++ Redistributable, ktorý daná verzia Instant Clientu vyžaduje. Pozri kontrolu SQL*Plus.
BinaryPathNamepreApi.exesa dá zmeniť, ale ponechajte predvolenú hodnotu$QASIDAAPI_BASE\Api\Api.exe, pokiaľ sa inštalácia neodlišuje od štandardného rozloženia.
$params = @{
Name = $QASIDAAPI_SERVICE_NAME
BinaryPathName = "$QASIDAAPI_BASE\Api\Api.exe"
DisplayName = $QASIDAAPI_SERVICE_NAME
StartupType = "Auto"
Description = $QASIDAAPI_SERVICE_DESCRIPTION
}
New-Service @params
sc.exe config $QASIDAAPI_SERVICE_NAME obj= $QASIDAAPI_VIRTUAL_SERVICE_NAME
New-LocalGroup -Name $QASIDAAPI_SERVICE_NAME -Description $QASIDAAPI_SERVICE_NAME
Add-LocalGroupMember -Group $QASIDAAPI_SERVICE_NAME -Member $QASIDAAPI_VIRTUAL_SERVICE_NAME
Do skupiny aplikácie pridajte aj používateľov, ktorí potrebujú prístup k súborom aplikácie.
Príklad
Add-LocalGroupMember -Group $QASIDAAPI_SERVICE_NAME -Member "Administrator"
Selfupdate na Windows nebeží ako samostatná služba. Adresár SelfUpdate v $QASIDAAPI_BASE netreba pri inštalácii vytvárať – API doň pri aktualizácii skopíruje nástroj selfupdate z nového inštalačného balíka a parametre zapíše do selfupdate.json vedľa neho. Nástroj potom cez správcu služieb zastaví službu AssecoQasidaAPI, vymení súbory a službu znova spustí.
Virtuálny účet NT SERVICE\AssecoQasidaAPI preto musí vedieť cez správcu služieb zastaviť aj spustiť vlastnú službu. Predvolené nastavenie Windows to bežnému účtu nedovoľuje. Práva doplníte takto (spustiť ako administrátor po vytvorení služby):
$sid = (New-Object System.Security.Principal.NTAccount("NT SERVICE", $QASIDAAPI_SERVICE_NAME)).Translate([System.Security.Principal.SecurityIdentifier]).Value
$sddl = (sc.exe sdshow $QASIDAAPI_SERVICE_NAME | Out-String).Trim()
if ($sddl -notmatch [regex]::Escape($sid)) {
$ace = "(A;;CCLCSWRPWPLOCRRC;;;$sid)"
$saclStart = $sddl.IndexOf("S:")
$newSddl = if ($saclStart -ge 0) { $sddl.Insert($saclStart, $ace) } else { $sddl + $ace }
sc.exe sdset $QASIDAAPI_SERVICE_NAME $newSddl
}
Overenie: vo výpise sc.exe sdshow AssecoQasidaAPI musí byť položka s SID účtu služby a právami RP (spustenie), WP (zastavenie) a LC (zistenie stavu).
Ak účet služby smie službu zastaviť, ale nesmie ju spustiť, QASIDA.API po aktualizácii zostane zastavená a treba ju spustiť ručne.
Počas selfupdate sa v
$QASIDAAPI_BASEautomaticky vytvoria pomocné adresáreApi_selfupdate_backupaApi_selfupdate_logs, ktoré sa po úspešnej aktualizácii zmažú. Súborappsettings.jsonsa po aktualizácii automaticky obnoví. AdresáreLogs,DataProtectionKeysaCertificatessa obnovia len vtedy, ak ležia v$QASIDAAPI_BASE\Api– ten aktualizácia zmaže a vytvorí znova. Pri štandardnom rozložení ležia vedľa adresáraApi(pozri Nastavenia selfupdate), takže sa ich aktualizácia vôbec nedotkne.
Pri aktualizácii sa zachová iba jeden adresár s certifikátmi: ten, ktorý je nastavený pre zbernicu
QasidaHub(RabbitMqCertificates:Path). Ak iný modul s RabbitMQ používa vlastný adresár s certifikátmi, ktorý tiež leží v$QASIDAAPI_BASE\Api, tento adresár sa nezachová a jeho obsah vrátane privátneho kľúča sa pri ďalšej aktualizácii stratí (do logu sa zapíše upozornenie). Všetky adresáre s certifikátmi preto nechajte mimo adresáraApi.
Konfigurácia závisí od integrácie a spôsobu použitia konkrétnej inštalácie.
Predpoklady:
appsettings.jsonso správnou konfiguráciou,- databázový používateľ aplikácie s potrebnými právami,
- heslo administrátora aplikačnej databázy – používateľa
DL.
Vzor všetkých nastavení je v súbore appsettings.sample v inštalačnom balíku. TCP port a povolené adresy pre jednotlivé prostredia uvádza stránka Minimálne systémové požiadavky.
Urls(kľúč na najvyššej úrovni, napr."Urls": "http://*:8888") – adresy, na ktorých API počúva. Viac adries sa oddeľuje bodkočiarkou bez medzier. Vappsettings.sampletento kľúč nie je – doplňte ho s portom tejto inštalácie.
AllowedHosts(kľúč na najvyššej úrovni) – sieťové adresy, pod ktorými je aplikácia dostupná.
Serilog:WriteTo, sink"Name": "File",Args.path– úplná cesta k log súboru. Nepovinné, predvolene$QASIDAAPI_BASE\Logs\QasidaApi.txt. Nastavte ho len vtedy, ak sa inštalácia odlišuje od štandardného rozloženia, a vždy ako absolútnu cestu. Relatívna cesta sa vyhodnotí voči pracovnému adresáru procesu, ktorým je pri službe WindowsC:\Windows\System32, nie adresár API – logy by skončili tam. Príklad s lomkami"path": "C:/Qasida/QasidaAPI/Logs/QasidaApi.txt",alebo s dvojitými spätnými lomkami"path": "C:\\Qasida\\QasidaAPI\\Logs\\QasidaApi.txt",
SystemMaintenance:SpinDatabaseUpdate:SqlPlus– úplná cesta k SQL*Plus z Oracle Instant Clientu:"SqlPlus": "C:\\Qasida\\QasidaAPI\\InstantClient\\sqlplus.exe". Potrebná pre aktualizácie databázových skriptov. Bez tohto kľúča sasqlplushľadá vPATHúčtu služby. Ak kľúč nie je nastavený alebo sa nedá použiť, selfupdate ho pri ďalšej aktualizácii nastaví na$QASIDAAPI_BASE\InstantClient\sqlplus.exe– ak tento súbor existuje aappsettings.jsonneobsahuje komentáre. Nikdy nepoužívajte relatívnu cestu: pracovným adresárom služby Windows jeC:\Windows\System32.
Urls, AllowedHosts – povolené sú záznamy vo forme IP adresy alebo DNS mena.
Ak
SelfUpdateInstallPath,ClientInstallFilesPath,DownloadInstallFilesPath,DataProtectionPathaleboRabbitMqCertificates:Pathnastavíte explicitne, použite absolútnu cestu. Relatívna hodnota sa vyhodnotí voči samotnému adresáruApi, nie vedľa neho – napr.RabbitMqCertificates:Paths hodnotouCertificatesznamená$QASIDAAPI_BASE\Api\Certificates, teda adresár, ktorý selfupdate maže. Toto správanie existuje kvôli starším inštaláciám v IIS: aplikačný pool zvyčajne nemá prístup mimo vlastného adresára a viac inštancií na jednom serveri by si inak prekážalo v spoločnom adresári. Pri inštalácii ako služba podľa tohto návodu sa nepoužíva.
AppManagement:DataProtectionPath – nepovinné, predvolene $QASIDAAPI_BASE\DataProtectionKeys. Nechajte nenastavené, pokiaľ to nie je naozaj potrebné. Bez hodnoty API pri prvom štarte automaticky prenesie kľúče a súbor _secrets.xml zo starého umiestnenia v adresári Api. Po nastavení kľúča sa automatický prenos už nevykoná – existujúce súbory s kľúčmi a heslami presuňte ručne, inak sa vytvorí nová prázdna sada kľúčov a všetky uložené heslá a pripájacie reťazce budú nečitateľné.AppManagement:UseFileForSecretsStorage – nepovinné, predvolene false: heslá a pripájacie reťazce sa ukladajú do Správcu poverení Windows (Credential Manager). Hodnota true ich ukladá do XML súboru v AppManagement:DataProtectionPath – potrebné vtedy, keď účet služby nemá načítaný používateľský profil (napr. identita aplikačného poolu IIS) a Správca poverení zlyhá.Certifikáty pre šifrovanú komunikáciu (mTLS) s RabbitMQ sa čítajú zo súborov v adresári RabbitMqCertificates:Path (predvolene $QASIDAAPI_BASE\Certificates), nikdy z úložiska certifikátov Windows.
RabbitMqCertificates:ClientCertificateFileName, predvolene client.pfx.RabbitMqCertificates:CaCertificateFileName, predvolene ca.pem, inak ca.crt. Serveru sa dôveruje iba na základe tohto certifikátu, úložiská certifikátov operačného systému sa nepoužívajú.RabbitMqCertificates:ClientCertificatePassword. Namiesto otvoreného textu ho radšej uložte šifrovane cez PUT /api/v1/Management/SaveSecret s kódom RabbitMqCertificates:ClientCertificatePassword. Uložené heslo má prednosť a použije sa pri ďalšom pokuse o pripojenie bez reštartu API.Certifikáty sa načítajú raz, pri prvom pokuse o pripojenie. Výmena súborov (napr. po obnove certifikátu) sa preto prejaví až po reštarte služby API.
Jednotlivé moduly môžu tieto spoločné nastavenia prepísať vlastnými kľúčmi (napr. AsolLicServerUpdateLicenseBackgroundService:RabbitMqCertificatesPath) – úplný zoznam je v appsettings.sample. Ako je uvedené v časti Selfupdate, pri aktualizácii sa zachová iba adresár pre QasidaHub.
Databázový účet, pod ktorým sa API pripája k databáze, musí existovať a mať pridelené potrebné role.
Všetky adresáre nižšie sú predvolene adresáre s rovnakým názvom vedľa $QASIDAAPI_BASE\Api (teda $QASIDAAPI_BASE\Api\..\<názov>). Pri štandardnom rozložení preto netreba nastavovať žiadny z týchto kľúčov – nastavte ho, len ak sa dané umiestnenie naozaj musí líšiť.
| Kľúč | Predvolená hodnota | Význam |
|---|---|---|
QasidaUpdate:ApiServiceName |
AssecoQasidaAPI |
Názov služby Windows, ktorú selfupdate cez správcu služieb zastaví a znova spustí. |
QasidaUpdate:SelfUpdateInstallPath |
$QASIDAAPI_BASE\SelfUpdate |
Adresár, do ktorého sa pri aktualizácii pripraví a z ktorého sa spúšťa nástroj selfupdate. Nikdy nie adresár API ani koreň disku. |
QasidaUpdate:ClientInstallFilesPath |
$QASIDAAPI_BASE\ClientInstallFiles |
Adresár, z ktorého API poskytuje súbory klienta (napr. sieťové zdieľanie). Musí byť zapisovateľný, nikdy nie adresár API ani koreň disku. Pred každým zverejnením sa celý jeho obsah zmaže. |
QasidaUpdate:DownloadInstallFilesPath |
$QASIDAAPI_BASE\DownloadInstallFiles |
Adresár, do ktorého sa sťahujú inštalačné balíky z AsolHub. Musí byť zapisovateľný, nikdy nie adresár API ani koreň disku. |
icacls $QASIDAAPI_BASE /inheritancelevel:d
icacls $QASIDAAPI_BASE /setowner $QASIDAAPI_VIRTUAL_SERVICE_NAME /t
icacls $QASIDAAPI_BASE /grant $QASIDAAPI_SERVICE_NAME":(OI)(CI)(F)" /t
icacls $QASIDAAPI_BASE /remove "CREATOR OWNER" /t
icacls $QASIDAAPI_BASE /remove "NT AUTHORITY\SYSTEM" /t
icacls $QASIDAAPI_BASE /remove:g "Users" /t
$fileSystemRights = "FullControl"
$type = "Allow"
# Aktualne opravnenia
$NewAcl = Get-Acl -Path $QASIDAAPI_BASE
# Nove opravnenie
$fileSystemAccessRuleArgumentList = $QASIDAAPI_SERVICE_NAME, $fileSystemRights, $type
$fileSystemAccessRule = New-Object -TypeName System.Security.AccessControl.FileSystemAccessRule -ArgumentList $fileSystemAccessRuleArgumentList
# Pouzitie novych opravneni
$NewAcl.SetAccessRule($fileSystemAccessRule)
Set-Acl -Path $QASIDAAPI_BASE -AclObject $NewAcl
Get-ChildItem -Path $QASIDAAPI_BASE -Recurse -Force | Set-Acl -AclObject $NewAcl
Každá ďalšia inštancia QASIDA.API potrebuje vlastný inštalačný adresár, vlastnú službu a vlastné nastavenia. Selfupdate názov služby nezisťuje sám – bez kľúča QasidaUpdate:ApiServiceName by pracoval so službou primárnej inštancie.
Príklad pre inštanciu na porte 9999 – celý postup zopakujte s týmito premennými:
$QASIDAAPI_BASE = "C:\Qasida\QasidaAPI_9999"
$QASIDAAPI_SERVICE_NAME = "AssecoQasidaAPI_9999"
$QASIDAAPI_VIRTUAL_SERVICE_NAME = "NT SERVICE\AssecoQasidaAPI_9999"
V appsettings.json tejto inštancie nastavte:
"Urls": "http://*:9999",QasidaUpdate:ApiServiceName = AssecoQasidaAPI_9999.Restart-Service -Name $QASIDAAPI_SERVICE_NAME -Force
Príklady používajú predvolený TCP port QASIDA.API. Podľa potreby ho upravte pre konkrétnu inštaláciu.
curl http://localhost:8888/health -UseBasicParsing
curl http://localhost:8888/version -UseBasicParsing
Príkaz musí vypísať verziu SQL*Plus:
& "$QASIDAAPI_BASE\InstantClient\sqlplus.exe" -V
$QASIDAAPI_BASE vytvorený s podadresárom Api\$QASIDAAPI_BASE\Api\$QASIDAAPI_BASE\InstantClient\AssecoQasidaAPI vytvorená s BinaryPathName na $QASIDAAPI_BASE\Api\Api.exe; sc.exe config obj= nastavené na virtuálny účet službyAssecoQasidaAPI vytvorená; virtuálny účet služby a potrebné používateľské účty sú jej členmiRP, WP, LC vo výpise sc.exe sdshow) – požiadavka selfupdate$QASIDAAPI_BASE nastavené (vlastník a ACL pre virtuálny účet a skupinu služby)appsettings.json so správnou konfiguráciouSystemMaintenance:SpinDatabaseUpdate:SqlPlus nastavený na $QASIDAAPI_BASE\InstantClient\sqlplus.exe; sqlplus.exe -V prejde (pozri kontrolu SQL*Plus)QasidaUpdate:SelfUpdateInstallPath, ClientInstallFilesPath, DownloadInstallFilesPath na predvolených hodnotách, ak sa rozloženie neodlišuje od štandarduAppManagement:DataProtectionPath nenastavený (alebo ručne presunuté existujúce súbory s kľúčmi a heslami); UseFileForSecretsStorage nastavený na true, ak účet služby nemá načítaný používateľský profilclient.pfx, ca.pem/ca.crt) v RabbitMqCertificates:Path (predvolene $QASIDAAPI_BASE\Certificates), mimo adresára Api\QasidaUpdate:ApiServiceName s jej názvomcurl http://localhost:8888/health -UseBasicParsing