Webové služby v systému FLORES - 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 IS FLORES by měl být nainstalován jako síťový (tj. s aplikačním serverem). (FLORES 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 IS FLORES 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 IS FLORES
  • Mít správně nastavené parametry pro WS server v souboru WS.cfg.

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

    • mít nainstalovanou službu FLORES 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 IS FLORES (zde FLORES 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ý FLORES 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 floresws.conf,
    • mít Apache správně nakonfigurován (viz popis FLORES WSDL modulů), jedná se v prvé řadě o úpravu konfiguračního souboru httpd.conf,
    • zajistit spuštění Apache
  • Po update IS FLORES provést aktualizaci potřebných souborů. Viz Web. služby a update.

Pořadí spuštění a zastavování služeb FLORES WS serveru a Apache není důležité. Apache po spuštění nahrává FLORES modul, který se snaží spojit s FLORES 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 FLORES 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 IS FLORES 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 IS FLORES 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 IS FLORES operace ovládající adresář) (Viz na obrázku 1 bod 1). V systému IS FLORES 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 IS FLORES 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í FLORESOLE, 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 IS FLORES 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 FLORES WS serveru, jak jej zprovoznit, nakonfigurovat a jak řešit rozložení zátěže

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

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

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

FLORES WS server se chová jako klientská část aplikace IS FLORES, která komunikuje s aplikačním serverem (tedy obdobně jako jakýkoliv jiný klient IS FLORES). (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 floresws.conf) a provádí, "co se mu řekne", tj. přes aplikační server přistupuje k IS FLORES, 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 IS FLORES FLORES 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 IS FLORES. Pro provoz FLORES 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 FLORES 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á FLORESWebServices (zobrazovaný název FLORES® WebServices).

.

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

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

  • FLORES 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 IS FLORES. 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 FLORES nainstalován.

    V takovém případě se WSServerS.exe musí instalovat s UNC cestou (ne z namapované cesty). Tedy např. \\GxAppServer\FLORES\WSServerS -install. Instalace s cestou zadanou přes mapovaný disk, tj. např. W:\FLORES\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\FLORES\ na písmenko W).

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

Logování

O průběhu akcí FLORES 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 IS FLORES.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. FLORES 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) FLORES 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í. FLORES 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 FLORES WS serveru vyžaduje spuštění dalšího kernelu, FLORES 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ý FLORES WS server čeká na jeho spuštění a další kernely nespouští. Pokud kernel z nějakého důvodu spojení nenaváže, FLORES 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 FLORES 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 FLORES. 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.

floresws.conf.tmpl obsahuje tyto parametry:

Název Popis
WSServerIP IP adresa, na které bude webový server komunikovat s FLORES WS serverem. Výchozí hodnota je localhost.
WSServerPort Číslo TCP/IP portu, na němž bude webový server komunikovat s FLORES 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 FLORES 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_flores_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ě floresws.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_flores_wsserver_http_2_2.so, pro každý sekce v floresws.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 IS FLORES. 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.

floresws.conf.tmpl obsahuje tyto parametry:

Název Popis
ConnectionName Název spojení, na které se má FLORES 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á FLORES 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á FLORES 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ý FLORES 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, FLORES 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].

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 FLORES WS serverů (pro obsluhu jednotlivých spojení) z jedné instalace IS FLORES, tj. máte zkopírované a přejmenované exe soubory FLORES WS serveru pro obsluhu dalších spojení. Jméno těchto sekcí musí odpovídat přejmenovanému exe souboru FLORES WS serveru. K dispozici je zde navíc i parametr ServiceNameSuffix, jehož hodnota ovlivňuje název NT služby 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 IS FLORES běžet více FLORES WS serverů najednou a to:

  • tehdy, pokud máte více spojení na databázi IS FLORES 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í FLORES WS serveru, FLORES WS server musí být spouštěný z PC a adresáře, kde je IS FLORES 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 IS FLORES, může být společný pro více současně běžících WS serverů.

  • Na 1 PC lze službu "FLORES webových služeb" zaregistrovat vícenásobně.Všechny FLORES 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.
  • . Tudíž, pokud jsme zkopírovali WSServerS.exe do WSServerS2.exe, tak tento druhý WS server bude po svém spuštění hledat konfigurační soubor WSServerS2.cfg.

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 IS FLORES daný FLORES 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ý FLORES 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 IS FLORES), je celé řešení webových služeb v systému IS FLORES rozděleno do dvou částí:

První částí je FLORES WS server a druhou částí jsou FLORES_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 FLORES 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 jsou dodávané pro server Apache v. 2.2:

  • mod_flores_wsserver2_2.so
  • mod_flores_wsserver_http_2_2.so - určen pro rozhraní REST

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 FLORES 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 (Apache 2.4) 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 IS FLORES 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 floresws.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 floresws.conf nadefinovat několik sekcí s názvy odpovídající názvům modulů (soubory .so nebo .dll). Viz sekce floresws.conf.tmpl, respektive popis použití uvedený přímo v souboru floresws.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 FLORES WS serveru:

Dodávaný modul (např. mod_flores_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 floreswsserver.conf (do něj zapíšeme IP adresu, kde běží FLORES 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 flores_wsserver2_2_module modules/mod_flores_wsserver2_2.so
<Location /AWS>
SetHandler mod_flores_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 flores_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 IS FLORES pro Firebird.

Další postup se liší podle toho, jaké programovací prostředí či nástroj pro připojení k IS FLORES 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 IS FLORES:

  1. V systému IS FLORES 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 IS FLORES 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) IS FLORES. Tj. je třeba z aktuální instalace IS FLORES 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í IS FLORES.

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