Webové služby v systému ABRA - obecně

V této kapitole naleznete výklad následujících témat:

Nezbytnou podmínkou pro provoz webových služeb je, aby byla tato část systému nainstalována a licencována.

Systém ABRA Gen by měl být nainstalován jako síťový (tj. s aplikačním serverem). (ABRA WS server je klientem aplikačního serveru, jak bylo řečeno výše, a tudíž po jeho spuštění není možné již spustit systém ABRA Gen nainstalovaný jako single a naopak (systém nahlásí pokus o opakované spuštění stejné jednouživatelské verze).

Dále je pro provoz třeba:

  • Mít splněny podmínky pro provoz skriptování, viz co je třeba k provozu skriptování.
  • Mít nadefinované operace a web. služby v ABRA Gen
  • Mít správně nastavené parametry pro WS server v souboru WS.cfg.

  • Poté zajistit běh ABRA WS serveru a jeho komunikaci s aplikačním serverem, tj.:

    • mít nainstalovanou službu ABRA Server webových služeb a mít ji spuštěnu (pokud jej provozujete jako službu (doporučeno)),

      Pro správné fungování musí být služba spuštěna pod uživatelem, který má přidělenou a nastavenou tiskárnu Tedy služba nesmí běžet pod Lokálním účtem. Důvod je ten, že se ovladače přidělené tiskárny používají pro generování tiskových sestav.

    • mít spuštěnou aplikaci (pokud jej provozujete jako Win aplikaci),
    • zajistit spuštění aplikačního serveru (aplikační server se ale umí spustit automaticky v případě instalace na stejném PC, z kterého se spustí klientská část ABRA Gen (zde ABRA WS server)).

  • Poté zajistit běh externího webového serveru (např. Apache), tj.:

    • mít nainstalovaný Apache,
    • mít v něm v adresáři \modules nakopírovaný ABRA WSDL modul odpovídající verzi Apache a OS, na kterém běží,
    • mít v něm v adresáři \conf nakopírován konfigurační soubor abraws.conf,
    • mít Apache správně nakonfigurován (viz popis ABRA WSDL modulů), jedná se v prvé řadě o úpravu konfiguračního souboru httpd.conf,
    • zajistit spuštění Apache
  • Po update ABRA Gen provést aktualizaci potřebných souborů. Viz Web. služby a update.

Pořadí spuštění a zastavování služeb ABRA WS serveru a Apache není důležité. Apache po spuštění nahrává ABRA modul, který se snaží spojit s ABRA WS serverem, aby si načetl poskytované služby. Spojení není udržováno trvale, jakmile si poskytované služby k sobě načte, spojení se rozpojí. Toto spojení se samo obnovuje, resp. se vždy znovu vytváří, když je potřeba, a to pouze na nezbytně nutnou dobu, poté se opět ukončí. Z toho plyne, že případný restart ABRA WS serveru není na závadu, není třeba zastavovat a znovu spouštět Apache a WS server v nějakém definovaném pořadí.

Systém ABRA Gen od verze 8.03 plně podporuje standard webových služeb a umožňuje externím systémům se připojit, načíst či uložit data zcela konzistentně a to pomocí libovolného programovacího prostředí, které webové služby (WS) podporuje.

Operace - Operace je v podstatě základní stavební jednotka webových služeb. Je to funkce, která vykonává určitou (požadovanou) činnost. Např. "označ tuto objednávku jako potvrzenou" nebo "sděl mi, zda je tato objednávka již vyfakturována" apod. (Viz na obrázku 1 bod 2). V systému ABRA Gen se jednotlivé operace definují v agendě Operace.

Webová služba - Je to skupina jedné nebo více operací sdružených do jakési logické skupiny. Například to mohou být všechny operace související s určitou konkrétní činností (např. v systému ABRA Gen operace ovládající adresář) (Viz na obrázku 1 bod 1). V systému ABRA Gen se webové služby definují v agendě Webové služby.

Obrázek 1.  Body 1 a 3 jsou Webové služby, bod 2 je operace ve vybrané službě.

Každá operace je vlastně metoda, která má jméno, vstupní (volitelně i výstupní) parametry a může mít i návratovou hodnotu. Vlastní operace jsou definovány v agendě Operace. Každá operace má název, což je jméno, pod kterým se tato operace zobrazuje v prohlížeči (viz Obrázek 1, bod 2) a zároveň je to jméno, kterým se tato operace volá. Dále je nutné specifikovat, zda se jedná o "proceduru" nebo o "funkci". V případě funkce je třeba specifikovat návratovou hodnotu funkce, což se zajistí zařazením parametru jménem Result mezi parametry operace. Ke každé operaci lze definovat vstupně/výstupní parametry. Každý parametr má jméno, typ parametru (číslo, řetězec, ...) a příznak parametru, pomocí něhož se specifikuje, zda se jedná o jen o vstupní či vstupně/výstupní parametr. Tj. parametr může být buď bez příznaků, v tom případě se jedná pouze o vstupní parametr, nebo může mít hodnotu Var, což znamená, že jedná o vstupně/výstupní parametr, jenž je předán jako vstup, jehož hodnota může být operací modifikována a upravená hodnota bude vrácena zpět.

Požadovaná funkcionalita (to, co má daná operace vlastně vykonat) je realizována pomocí skriptování, tj. ke každé operaci musí být definována odpovídající metoda v nějakém balíčku v agendě Balíčky skriptů. Tudíž každá operace musí mít dále nastaveny odkazy pro volání obsluhy do skriptování, tj. jméno balíčku, jméno knihovny a jméno metody volané v knihovně, která implementuje požadovanou funkcionalitu. Pokud daná metoda dosud neexistuje, je možné si hlavičku pro ni rovnou z agendy Operace založit.

Webové služby se definují v agendě Webové služby. Služba nabízí jednotlivé operace, které spolu nějak souvisí (viz Obrázek 1, kde body 1 a 3 jsou Webové služby, bod 2 je operace ve vybrané službě). Každá webová služba má ve své definici název, který se zobrazuje v prohlížeči (viz Obrázek 1, bod 1) a který se používá i při volání operací v ní obsažených. U každé služby je specifikován seznam operací, které budou v rámci této služby dostupné. Operaci je možné použít i několikrát v rámci různých služeb. To je důležité, neboť celá webová služba vykonává všechny své operace pod jediným specifikovaným uživatelem. Vícenásobné použití umožňuje volat tu samou operaci pokaždé jako jiný uživatel. Uživatel se zadává v definici webové služby.

Implementací se rozumí samotné naprogramování toho, co má operace vykonávat. To se děje ve skriptování. Zde je potřeba vytvořit nový balíček, v něm knihovnu a v ní funkci nebo proceduru, přesně podle jmen, jaké jsme zadali v definici operace, včetně všech parametrů a v případě funkce i včetně návratové hodnoty.

Pozor, každá metoda obsluhující ve skriptování určitou webovou operaci přebírá jako první parametr hodnotu Self, která je typu TNxWebServicesHelper. Tento parametr se nikde v definici operace neuvádí, ani není třeba jej zasílat při volání operace ze vzdáleného systému. Pouze je třeba s ním počítat při psaní kódu ve skriptování. Jeho vytvoření i správné umístění na první pozici mezi parametry v definici dané metody zajistí systém ABRA Gen sám, pokud si necháte hlavičku skriptu pro vámi zadávanou operaci předvyplnit funkcí Vytvořit hlavičku (v opačném případě jej musíte uvést sami).

Tento objekt (Self) má dvě vlastnosti (property) a to:

  • Context (TNxContext) – jedná se o klasický kontext, kde je již přihlášený uživatel, pod kterým se operace vykonává. Umožňuje získat interní ABRAOLE, získat či případně "zahodit" číselník, vykonat SQL příkaz atd.

  • ObjectSpace (TNxCustomObjectSpace) – jedná se o objektový prostor odvozený od kontextu. Slouží k vytváření nových business objektů, řízení transakcí, vykonání SQL příkazu atd.

    Nabídka třídy TNxWebServiceHelper v Class exploreru ve skriptování

Příklad skriptu:

Ukázka jednoduché implementace operace, která vytvoří business objekt Firma, načte z databáze zadanou firmu (v našem případě firmu ABC s.r.o.) a jako výsledek celé operace vrátí TNxSOAPBusinessObject reprezentující tuto firmu.

TNxSOAPBusinessObject je struktura, která umožňuje přenášet business objekty systému ABRA Gen přes webové služby. Struktura TNxSOAPBusinessObjectje následující:

TNxSOAPBusinessObject
property Fields: TNxSOAPBusinessObjectFields
end;

TNxSOAPBusinessObject obsahuje mj. vlastnost Fields (typu TNxSOAPBusinessObjectFields), což je pole obsahující jednotlivé položky (fields) v business objektu:

TNxSOAPBusinessObjectFields = array of TNxSOAPBusinessObjectField;

TNxSOAPBusinessObjectField je objekt obsahující informace o jednom "fieldu" business objektu (BO). Struktura TNxSOAPBusinessObjectField je následující:

TNxSOAPBusinessObjectField
property FieldName: String
property FieldDataType: TNxDataType
property FieldDataKind: TAWSDataKind
property FieldValueAsString: String
property FieldValueAsInteger: Integer
property FieldValueAsFloat: Extended
property FieldValueAsDateTime: TDateTime
property FieldValueAsBoolean: Boolean
property BusinessObject: TNxSOAPBusinessObject
property Collection: TNxSOAPBusinessObjectCollection
end;

TNxDataType = (dtUnknown, dtString, dtSmallint, dtInteger, dtWord, dtBoolean,
 dtFloat, dtCurrency, dtBCD, dtDate, dtTime, dtDateTime, dtBytes,
 dtVarBytes, dtAutoInc, dtBlob, dtMemo, dtGraphic, dtFmtMemo,
 dtTypedBinary, dtCursor, dtGuid, dtList);

TAWSDataKind = (adkData, adkBusinesObject, adkCollection);

Význam jednotlivých vlastností:

  • FieldName – jméno fieldu (např. ID je vlastní identifikace)
  • FieldDataType – typ dat, které field BO obsahuje. Jednotlivé hodnoty jsou vyjmenovány výše, ale v praxi se používají pouze dtString, dtSmallint, dtInteger, dtWord, dtBoolean, dtFloat, dtCurrency, dtDate, dtTime, dtDateTime, dtMemo, dtFmtMemo
  • FieldDataKind – upřesňuje, o jaký druh fieldu se jedná

  • adkData – jedná se o data, jejichž typ je specifikovaný v FieldDataType. Příslušná hodnota je uložena ve FieldValueAs... – jedná se o data, jejichž typ je specifikovaný v FieldDataType. Příslušná hodnota je uložena ve FieldValueAs...

    • dtString, dtMemo, dtFmtMemo FieldValueAsString
    • dtSmallint, dtInteger, dtWord FieldValueAsInteger
    • dtFloat, dtCurrency FieldValueAsFloat
    • dtDate, dtTime, dtDateTime FieldValueAsDateTime
    • dtBoolean FieldValueAsBoolean
  • adkCollection – jedná se o kolekci jednoho nebo více business objektů. Typicky jsou zde uloženy např. řádky dokladu. V tomto případě je v Collection instance TnxSOAPBusinessObjectCollectionrep reprezentující kolekci.
  • adkBusinessObject – field je typu odkaz na jiný business objekt. V tomto případě je v property BusinessObject další instance TNxSOAPBusinessObject reprezentující odkazovaný business objekt.

V této části naleznete princip ABRA WS serveru, jak jej zprovoznit, nakonfigurovat a jak řešit rozložení zátěže.

Pojmem ABRA WS server (zkráceně AWS server) budeme označovat ABRA server webových služeb, který vykonává vše potřebné v systému ABRA Gen. ABRA WS server může být realizován více způsoby:

  • WSServer.exe - ABRA WS serverem je Windows aplikace (exe).
  • WSServerS.exe - ABRA WS serverem je Windows služba (service). Doporučeno.

Oba soubory jsou po instalaci ABRA Gen k dispozici v rootu adresáře, do něhož byla ABRA Gen instalována.

ABRA WS server se chová jako klientská část aplikace ABRA Gen, která komunikuje s aplikačním serverem (tedy obdobně jako jakýkoliv jiný klient ABRA Gen). (Pojem klientská část viz kap. Technologie zpracování dat.) Je-li spuštěn, "poslouchá" na definovaném TCP/IP portu 3121 (je možno nastavit i jiný, viz konfigurační soubor abraws.conf) a provádí, "co se mu řekne", tj. přes aplikační server přistupuje k ABRA Gen, načítá si služby, které jsou v ní nadefinovány, ty zpřístupňuje ven a provádí požadavky, které dostává z externí aplikace komunikující s ním přes internetový webový server (např. Apache).

Nezaměňujte "server webových služeb" (v systému ABRA Gen ABRA WS server) a "webový server" neboli web server (např. Apache).

Registrace, další podmínky spuštění atd.

WSserver.exe se spustí standardním způsobem jako exe soubor, pak, je-li spuštěn, je na toolbaru zobrazen jako jiné běžící aplikace.

WSserverS.exe je Windows služba, která vykonává vše potřebné v systému ABRA Gen. Pro provoz ABRA WS serveru jako služby je nejprve nutné tuto službu zaregistrovat spuštěním dodávaného exe souboru z příkazové řádky (k tomu je třeba mít administrátorský přístup). Tj. pod administrátorským účtem nainstalovat servis z příkazové řádky jeho zavoláním s parametrem /INSTALL (resp. -INSTALL) z adresáře, kde je ABRA WS server umístěn:

<cesta>\WSserverS.exe /INSTALL

Pokud se instalace služby zdaří, zobrazí se zpráva potvrzující úspěšné nainstalování a v přehledu služeb ve Windows se objeví nová služba nazvaná ABRAGenWebServices (zobrazovaný název ABRA Gen® WebServices).

Nainstalovaná služba ve Windows.

Pro odinstalaci totéž ale s parametrem /UNINSTALL (resp. -UNINSTALL).

  • ABRA WS server musí být umístěn ve stejném adresáři jako systém ABRA Gen. (Využívá balíčky systému ABRA Gen). Nicméně běžet může jinde, viz další bod.

  • ABRA WS může běžet na jiném počítači, než kde běží aplikační server a než kde je instalován systém ABRA Gen. To bude typický případ v praxi (kvůli rozdělení zátěže).

    Aplikační server běží na jednom počítači, server webových služeb na jiném počítači, přičemž leží fyzicky na třetím v adresáři, kde je ABRA nainstalována.

    V takovém případě se WSServerS.exe musí instalovat s UNC cestou (ne z namapované cesty). Tedy např. \\GxAppServer\AbraGen\WSServerS -install. Instalace s cestou zadanou přes mapovaný disk, tj. např. W:\AbraGen\WSServerS -install sice půjde nainstalovat, ale nepůjde spustit. Je to z toho důvodu, že služba neběží pod profilem aktuálně přihlášeného uživatele. Nemá jeho prostředí (plochu, různá nastavení atd. a mimo jiné ani mapování síťové cesty \\GxAppServer\AbraGen\ na písmenko W).

  • ABRA WS server musí být správně nakonfigurován. Viz dále konfigurace ABRA WS serveru.
  • ABRA WS server může být zaregistrován i vícenásobně.

Logování

O průběhu akcí ABRA WS serveru resp. jeho kernelů (viz dále) si můžeme zobrazit log. Logování událostí v kernelu webových služeb se konfiguruje jako ostatní logování v konfiguračním souboru Nexus.cfg v sekci [WS~Group]. Konfigurační soubor Nexus.cfg systém hledá ve stejné cestě, jako je AbraGen.exe.

[Log.WS~Group]
Enabled=1
Level=6

Jelikož WS server je nevizuální, je v případě potíží potřeba logovat vícero věcí a logování týkající se webových služeb tudíž probíhá více třídami. Jejich vzájemná konfigurace může být složitá, navíc logování jen jedné z nich může být v praxi pro odhalení problému nedostatečné, nebude-li k dispozici současně i log jiné z nich. Proto je k dispozici logovací skupina WS~Group. Zapnout "rozumné" logování je možné přidáním právě této skupiny do Nexus.cfg. Pozor, bude vznikat množství log souborů, které je nutné rozumně odsouvat.

Webové služby umožňují vyřizování více požadavků najednou. ABRA WS server WSServer.exe resp. WSServerS.exe je jen jakási "obálka", která zajišťuje spouštění procesů pro vyřizování jednotlivých požadavků od klientů. Každý takový požadavek vykonává tzv. jádro (resp. kernel) ABRA WS serveru (WSServerKernel.exe). Tedy samotný server nevykonává požadavky, ale pouze přijímá požadavky od klientů a řadí je do fronty, odkud si je vyzvedávají jádra (kernely) a provádí je. Každé jádro dokáže vykonávat najednou pouze jeden požadavek, což v podstatě znamená, že počet právě spuštěných jader (kernelů) se rovná max. počtu současně vyřizovaných požadavků. Maximální počet současně běžících kernelů (tj. současně vyřizovaných požadavků) lze nastavit v konfiguračním souboru WS.cfg.

Uživatel sám nijak WSServerKernel.exe nespouští. ABRA WS server si tyto své kernely spouští a ukončuje automaticky sám podle vytíženosti služeb. Tj. když fronta požadavků na ABRA WS serveru vyžaduje spuštění dalšího kernelu, ABRA WS server si jej spustí. (Spuštění nenastane okamžitě, kernel potřebuje nějakou režii na navázání spojení (cca desítky sekund), přičemž existuje timeout (cca 3 min), po který ABRA WS server čeká na jeho spuštění a další kernely nespouští. Pokud kernel z nějakého důvodu spojení nenaváže, ABRA WS server jej po tomto timeoutu ukončí a spustí jiného.

Obdobně, pokud dojde při vykonávání požadavku v jádru (kernelu) k nějaké fatální chybě (např. k výpadku sítě, kdy se ztratilo spojení na aplikační server a jádro není schopné dále pokračovat), jádro to serveru oznámí a ukončí se. Server tedy spustí jiné jádro (kernel), na které požadavek předá. Chyba, ke které může při vykonávání požadavku dojít, nemusí být jen ve spojení, ale může být přímo ve volaném skriptu, přičemž může být natolik fatální, že způsobí ukončení jádra. Aby se pak nestalo, že server bude daný požadavek předávat na další jádra do nekonečna, platí:

Požadavek se předává na další jádra, dokud jedno z nich požadavek nevyřídí, přičemž maximální počet předání na další jádro je roven Maximálnímu počtu současně běžících jader (kernelů). Tím se zajistí kompletní obnova jader a v případě, že to nepomůže, zpracovávání požadavku se přeruší a chyba se přepošle na volající stranu.

Na správu běžících kernelů lze využívat např. Telnet, viz konfigurace ABRA WS serveru.

V instalačním adresáři jsou v podadresáři ..\Doc\webservices dvě šablony konfiguračních souborů, které slouží ke konfiguraci webových služeb. Jedna pro komunikaci WS serveru se serverem Apache, druhá pro samotnou konfiguraci WS serveru:

Šablona sloužící pro konfiguraci modulů serveru Apache a konfiguraci komunikace mezi serverem Apache a WS serverem ABRA. Všechny případné moduly (i ty případně přejmenované pro obsluhu více spojení) se konfigurují z tohoto souboru. Šablonu stačí pouze přejmenovat (resp. odstranit koncovku tmpl) a nahrát do instalačního adresáře serveru Apache a v něm do podadresáře conf. V tomto umístění je konfigurační soubor očekáván! Konfigurační soubor je obsahuje sekci [WebServices], které dále obsahují parametry, jež jsou v základním stavu okomentovány (je před nimi uveden znak #) a v tomto stavu se přebírá vyplněná výchozí hodnota parametru. Pokud je daný parametr nutno změnit, je třeba znak # odstranit.

abraws.conf.tmpl obsahuje tyto parametry:

Název Popis
WSServerIP IP adresa, na které bude webový server komunikovat s ABRA WS serverem. Výchozí hodnota je localhost.
WSServerPort Číslo TCP/IP portu, na němž bude webový server komunikovat s ABRA WS serverem. Výchozí hodnota je 3121.
MaximumProcessingTime Max. doba na vykonání požadavku. Čas vyhrazený na zpracování požadavku. Hodnota může být v rozmezí <1..MaxInt>. Hodnota je v sekundách. Výchozí hodnota je 1800.
HTTPInterfaceVersion

Speciální parametr pro HTTP modul, který určuje jaká verze volání skriptů bude použita pro obsluhu požadavků z tohoto modulu Hodnoty mohou být tyto:

  • 1=Původní skripty s 5ti parametry,
  • 2=Nové rozhraní metod ve skriptingu, kdy jsou kromě SELF předány 2 objekty: Request a Response

Výchozí hodnota je 1

Za základní sekcí [WebServices] mohou následovat další sekce. Tyto sekce využijete v případě, že máte více spojení a chcete provozovat více ABRA WS serverů (pro obsluhu jednotlivých spojení) z jedné instalace Apache, tj. máte zkopírované a přejmenované so soubory pro obsluhu dalších spojení. Jména těchto sekcí musí odpovídat přejmenovaným so souborům. Např. [mod_abra_wsserver2_2_01], za kterým bude následovat parametr s hodnotou pro toto spojení. Typicky se volí minimálně WSServerPort. Více viz popis v samotné šabloně abraws.conf.tmpl.

Stejným způsobem je možné postupovat i v případě využívání RESTful rozhraní (několik různě pojmenovaných kopií Apache modulu mod_abra_wsserver_http_2_2.so, pro každý sekce v abraws.conf).

Šablona sloužící pro konfiguraci serveru webových služeb. Šablonu stačí pouze přejmenovat (resp. odstranit koncovku tmpl) a nahrát do instalačního adresáře systému ABRA Gen. V tomto umístění je konfigurační soubor očekáván! Konfigurační soubor obsahuje sekci [WebServices], které dále obsahují parametry, jež jsou v základním stavu okomentovány (je před nimi uveden znak #) a v tomto stavu se přebírá vyplněná výchozí hodnota parametru. Pokud je daný parametr nutno změnit, je třeba znak # odstranit.

ws.cfg.tmpl obsahuje tyto parametry:

Název Popis
ConnectionName Název spojení, na které se má ABRA WS server připojit. Výchozí hodnota není nastavena, je ji vždy nutno vyplnit.
ConcurrentProcessesCount Maximální počet souběžně spuštěných "kernelů". Hodnota definuje, kolik požadavků může server webových služeb zpracovávat paralelně. Podle zátěže budou dynamicky spouštěné další dceřinné procesy až do nastavené hodnoty. Hodnota může být nastavena v rozmezí <1..20>. Výchozí hodnota je 3.
ModulePort Číslo TCP/IP portu, na němž má ABRA WS server komunikovat s webových serverem, tj. na němž přijímá přeposlané požadavky z modulu Apache. Pozor, pokud na 1 PC potřebujete spouštět více WS serverů, musí každý z nich poslouchat na jiném portu. Výchozí hodnota je 3121.
KernelPort Číslo TCP/IP portu, na němž má ABRA WS server komunikovat se svými kernely (jádry). Využijete tehdy, pokud na 1 PC potřebujete spouštět více WS serverů. "Port kernelů" pak umožnuje, aby každý ABRA WS server používal pro své kernely jiný TCP port. Výchozí hodnota je 3546.
KernelInactivityTime Interval, za který bude nepotřebný kernel ukončen. Nebude-li kernel po stanovený interval vytížen (neobslouží během této doby žádný požadavek), bude ukončen. Hodnota může být v rozmezí <30..MaxInt>. Hodnota je v sekundách. Výchozí hodnota je 120.
WaitingRequestsCountTreshold Hromadí-li se požadavky ve frontě a jejich počet překročí stanovenou hranici, server web.služeb aktivně spustí nový kernel, aby zvýšil propustnost zpracování. Hodnota může být v rozmezí <1..MaxInt>. Výchozí hodnota je 3.
WaitingRequestTimeTreshold Max. čekací doba požadavku. Stanovuje dobu čekání ve frontě. Čeká-li požadavek ve frontě déle, než stanovený interval, ABRA WS server aktivně spustí další dceřinný proces (za předpokladu, že není překročen max. počet "kernelů"), aby zvýšil propustnost zpracování. Hodnota může být v rozmezí <100..MaxInt>. Hodnota je v milisekundách. Výchozí hodnota je 500.
MaximumProcessingTime Max. doba na vykonání požadavku. Čas vyhrazený na zpracování požadavku. Hodnota může být v rozmezí <1..MaxInt>. Hodnota je v sekundách. Výchozí hodnota je 1800.
ChildProcessStartUpThreshold Čas vyhrazený na start dceřinného procesu. Hodnota může být v rozmezí <1..MaxInt>. Hodnota je v sekundách. Výchozí hodnota je 180.
ServiceNameSuffix

Parametr, jehož odnota ovlivňuje název služby Windows webového serveru. Požívá se v případě, kdy je nutné provozovat více WS serverů. Uvádí se za základní sekcí [WebServices].

Do verze 11.05 byla v systému při užívání parametru chyba, která byla ve verzi 11.06 opravena (hodnota parametru v configuračním souboru abraws.conf se musela shodovat s hodnotou stejného parametru v souboru nexus.cfg). Pokud provádíte update ze starší verze než 11.06 na novější a využíváte parametr ServiceNameSuffix, bude třeba službu přeregistrovat.

Za základní sekcí [WebServices] mohou následovat další sekce. Tyto sekce využijete v případě, že máte více spojení a chcete provozovat více ABRA WS serverů (pro obsluhu jednotlivých spojení) z jedné instalace ABRA Gen, tj. máte zkopírované a přejmenované exe soubory ABRA WS serveru pro obsluhu dalších spojení. Jméno těchto sekcí musí odpovídat přejmenovanému exe souboru ABRA WS serveru. K dispozici je zde navíc i parametr ServiceNameSuffix, jehož hodnota ovlivňuje název služby Windows WS Serveru. Více viz popis v samotné šabloně WS.cfg.tmpl.

Jak již bylo zmíněno v popisu konfiguračního souboru, v praxi může pro jeden systém ABRA Gen běžet více ABRA WS serverů najednou a to:

  • tehdy, pokud máte více spojení na databázi ABRA Gen a chcete provozovat web. služby pro každé z nich
  • anebo tehdy, pokud potřebujete rozložit zátěž na více PC

To vede na následující řešení:

  • na 1 PC běží několik různých WS serverů
  • několik "stejných" WS serverů běží na několika PC
  • libovolná kombinace předchozího

Jak bylo řečeno výše v popisu zprovoznění ABRA WS serveru, ABRA WS server musí být spouštěný z PC a adresáře, kde je ABRA Gen nainstalovaná (ale běžet může na jiném PC). V instalačním adresáři jsou v podadresáři ..\Doc\webservices  je i šablona konfiguračního souboru. Ze šablony je možné vytvořit soubor, který po nahrání do kořenového adresáře systému ABRA Gen (a odstranění přípony tmpl) může být společný pro více současně běžících WS serverů.

  • Na 1 PC lze službu "ABRA webových služeb" zaregistrovat vícenásobně.Všechny ABRA WS servery se registrují s prefixem WSServerS_%nazevexe% (např. WSServerS_WSServerS pro WSSErverS.exe nebo WSServerS_WSServerS2 pro WSSErverS2.exe atd.). Zároveň i popis služby obsahuje jméno příslušného *.exe. Tudíž lze zkopírovat např. WSServerS.exe do WSServerS2.exe a obě služby na daném PC zaregistrovat.
  • . Pokud jsme zkopírovali WSServerS.exe do WSServerS2.exe, tak tento druhý WS server bude po svém spuštění hledat v konfiguračním souboru WS.cfg sekci nazvanou [WSServerS2].

Na 1 PC běží více různých WS serverů - řešení více spojení na 1 PC

V konfiguračním souboru lze mj. nastavit, jaké spojení na databázi ABRA Gen daný ABRA WS server obsluhuje.

Na jednom PC může běžet více WS serverů najednou. Tudíž obě služby lze zaregistrovat na témže PC. Pak na 1 PC poběží 2 různé WS servery, které budou číst z konfiguračního souboru, které spojení mají obsluhovat.

Protože samotný ABRA WS server je možné provozovat pouze na OS Windows a naopak webové servery, které zpřístupňují samotné webové služby, bývají provozovány mnohdy na linuxových OS nebo na samostatných strojích, kde není nainstalován systém ABRA Gen), je celé řešení webových služeb v systému ABRA Gen rozděleno do dvou částí:

První částí je ABRA WS server a druhou částí jsou ABRA_WSDL moduly, které jsou řešeny jako pluginy nejběžnějších webových serverů (Apache, IIS, ale i CGI -exe použitelné prakticky v jakémkoliv webovém serveru). Tyto pluginy se spojí s ABRA WS serverem. Adresa a port serveru, se kterým se má modul spojit, se nacházejí v textové podobě v příslušném konfiguračním souboru, viz dále.

Moduly dodávané pro server Apache v. 2.2:

  • mod_abra_wsserver2_2.so
  • mod_abra_wsserver_http_2_2.so - určen pro rozhraní REST

Moduly dodávané pro server Apache v. 2.4:

  • mod_abra_wsserver2_4.so
  • mod_abra_wsserver_http_2_4.so - určen pro rozhraní REST

Moduly dodávané pro server Apache v. 2.4 64-bit:

  • mod_abra_wsserver2_4_64.so
  • mod_abra_wsserver_http_2_4_64.so - určen pro rozhraní REST

V případě použití 64-bitových modulů je nutné odstranit suffix _64 z jejich názvů. Vše ostatní zůstává stejné jako u 32-bitové verze

Zatím není k dispozici modul pro Apache běžícího na Linuxu. Z toho důvodu lze zatím provozovat webové služby pouze v kombinaci s Apachem běžícím na Windows. Ovšem vzhledem k tomu, že minimálně kvůli ABRA WS serveru (který je z principu rozbíhání a "sestřelování" klientských kernelů pouze Win) musí být v systému Windows stroj a tento lze využít i pro běh win Apache, byť by byl tento využíván jen extra pro tento účel.

Výše uvedené knihovny jsou určeny pro server Apache (název modulů do Apache začíná na mod_). Zda jsou aktuálně k dispozici knihovny i pro jiné webové servery (např. IIS), příp. pro vyšší verze se informujte v obchodním oddělení výrobce. Nicméně se úpravy v tomto směru nepředpokládají a spíše se předpokládá rozvoj Web API.

Po update ABRA Gen nezapomeňte provést aktualizaci příslušných souborů. Viz Web. služby a update.

Adresa serveru, se kterým se má modul spojit, a port, na kterém mají komunikovat, jsou dány v konfiguračním souboru webového serveru. Pro Apache se jedná o soubor abraws.conf v podadresáři conf (tedy tak, jak je běžné u jiných modulů Apache). Formát nastavení uloženého v tomto souboru je

WSServerIP=AdresaIP (nebo jméno serveru web. služeb)

WSServerPort=Port. Port není povinný, pokud není zadán, je použit výchozí port 3121.

Pokud je zapotřebí, aby Apache obsluhoval služby několika WS serverů najednou, je možné v souboru abraws.conf nadefinovat několik sekcí s názvy odpovídající názvům modulů (soubory .so nebo .dll). Viz sekce abraws.conf.tmpl, respektive popis použití uvedený přímo v souboru abraws.conf.tmpl.

Do konfiguračního souboru je možno zapsat více WS serverů. Tj. více řádků v syntaxi AdresaIP (nebo jméno serveru web. služeb):Port a modul vždy používá první dostupný server. Modul navazuje nové TCP spojení pro každý jednotlivý požadavek na provedení služby a vždy při navazování spojení hledá první fungující webserver z konfigurace. To umožňuje přejít za běhu na záložní server v případě výpadku primárního serveru a pak zpět na primární server při obnovení činnosti primárního serveru.

Příklad instalace modulu pro webový server Apache pro obsluhu jednoho ABRA WS serveru:

Dodávaný modul (např. mod_abra_wsserver2_2.so) nakopírujeme do adresáře, kde má Apache moduly. Typicky je to podadresář \modules v adresáři, kde je Apache nainstalován. V adresáři, kde je konfigurace Apache (\conf), by měl být vytvořen konfigurační soubor abrawsserver.conf (do něj zapíšeme IP adresu, kde běží ABRA WS server, např. 192.168.1.1:3121). Dále je třeba upravit konfigurační soubor Apache httpd.conf, který se nachází v podadresáři \conf. Tady je třeba zajistit nahrání našeho modulu. Za místo, kde se přidávají jednotlivé moduly (LoadModule), umístíme text:

LoadModule abra_wsserver2_2_module modules/mod_abra_wsserver2_2.so
<Location /AWS>
SetHandler mod_abra_wsserver2_2-handler
</Location>

<Location /AWS> určuje, na jaké cestě se budeme na naše webové služby odkazovat. Tj. zjednodušeně řečeno "namapujeme" modul na nějakou url adresu resp. její část. Konkrétně tento příklad znamená, že naše služby budou dostupné na adrese http://jmenoserveru.cz/AWS. (V předchozí url adrese je jmenoserveru.cz identifikace serveru, kde je Apache nainstalován.) Pokud máme vše nastaveno, můžeme spustit webový server. Na http://jmenoserveru.cz/AWS se zobrazí stránka našich webových služeb, kde si můžeme prohlédnout, co všechno za služby nabízíme a jsou zde i odkazy na WSDL.

Pokud Apache nainstalujeme na vlastní lokální počítač s názvem např. moje-ntb a modul abra_wsserver2_2_module namapujeme např. takto: <Location /MojeAWS>, tak naše služby budou dostupné na http://java-ntb/MojeAWS.

Od verze 24.1 je nutné do modulů Apache nakopírovat spolu se soubory mod_abra_wsserver2_*.so i knihovnu NxSystemD.dll, která je také umístěná v hlavním adresáři ABRA Gen pro Firebird.

Další postup se liší podle toho, jaké programovací prostředí či nástroj pro připojení k ABRA Gen použijeme. Je možné použít klasické nástroje jako např. Delphi, C++, Java či skriptovací jazyky s podporou webových služeb např. PHP.

Poznámka k oprávněným přístupům k datům přes Webové služby ABRA Gen:

  1. V systému ABRA Gen je doporučeno si zavést fiktivní uživatele pro vygenerování WSDL a uživatele pro spuštění služby (a jim odpovídající role bez přístup. práv). Viz doporučení uvedené ve zmíněných položkách.
  2. Koncová aplikace - Koncovou např. webovou aplikaci by si měl autor zabezpečit ve své režii. Autor konc. aplikace si tedy zařídí zaregistrování uživatele a jeho
    přihlášení k serveru Apache. V rámci této koncové aplikace bude autor řešit, které funkce komu povolí volat.
  3. WSDL - Dále je třeba mít na paměti, že WSDL je "veřejné", tj. Apache poskytuje informace o funkcích, které umí volat, veřejně. Proti obejití Apache a volání funkcí WSserveru zvenku je možné se zabezpečit firewallem.

Po update ABRA Gen je potřeba také provést aktualizaci souborů potřebných pro provoz webových služeb. Jedná se o jednu z dalších akcí spojených s instalací nové verze (update) ABRA Gen. Tj. je třeba z aktuální instalace ABRA Gen vzít aktuální soubory a nahrát je do cílových cest.

Doporučený postup:

  • Zastavit Apache

  • Nahrát do příslušné cílové cesty aktuální modul

  • Nahrát do příslušné cílové cesty aktuální knihovnu NxSystemD.dll, která se nachází v adresáři s instalací ABRA Gen.

  • Spustit Apache
  • Ověřit běh webových služeb