ABRA API Tutoriál - Nastavení a příprava rozhraní Web API

Předpokládáme, že máte systém ABRA Gen nainstalovaný a aktivovaný tak, aby umožňoval provoz rozhraní Web API. Dále pro účely našeho příkladu předpokládáme, že budete pracovat nad spojením s nahranými demodaty (nedoporučujeme zkoušet nad ostrými daty), tj. nainstalovali jste si demoverzi, kterou jste si následně zaktivovali vaším licenčním klíčem, nebo jste si ve vaší instalaci založili další spojení s demodaty apod.

Dále viz podrobný help. Kap.: Instalace a kap. Aktivace programu. Jak si založit spojení s nahráním demodat, viz podrobný help. Kap.: DBAdmin.exe.

Dále předpokládáme, že máte k dispozici nějakého HTTP klienta. Klient může být integrovaný ve vašem vývojovém prostředí, ale také se může jednat o samostatnou aplikaci. Pro účely naší příručky budeme používat jako HTTP klienta aplikaci Postman. V minulosti se jednalo o rozšíření pro Google Chrome, v současné době je k dispozici jako nativní aplikace pro Windows, macOS nebo Linux. Aplikace je volně ke stažení na internetu (hledejte "Postman download"). Pomocí Postmanu se budeme do rozhraní Web API dotazovat.

V tomto kroku nastavíme Alias spojení, abychom nemuseli v URL používat Název spojení (zejména pokud název spojení obsahuje znaky s diakritikou, jeho použití je v URL nepraktické, různá kódování mohou způsobovat problémy).

Spustíme DBAdmin.exe (najdete jej v instalační složce ABRA Gen). Zde zvolíme Editovat spojení. Nechť se vaše spojení jmenuje např. "DemoG3G4_CZ_podnikatel" (nebo jakkoliv jinak, není podstatné). Alias zadáme jednoduchý, např. "data".

Dále viz podrobný help. Kap.: DBAdmin.exe.

V hostitelském OS je nutno nastavit bránu firewall tak, aby byl volný port, na kterém Web API server naslouchá, viz dále konfigurace Web API.

V kořenové instalační složce ABRA Gen nalezneme šablonu konfiguračního souboru. Šablonu si zazálohujeme a přejmenujeme (odstraníme příponu .tmpl):

• APIServer.yaml.tmpl → APIServer.yaml

  Web API je možné spustit i bez tohoto kroku, pak poběží s defaultním nastavením (které odpovídá obsahu šablony), ale bez konfiguračního souboru nebudete mít možnost nastavení změnit.

Předvedeme si změnu výchozího portu a aktivaci logování.

Změna výchozího portu

Port, na kterém Web API server naslouchá, je v šabloně defaultně nastaven na hodnotu 80. Port 80 nechť máme obsazen, tudíž jej změníme na jiný, např. 8082. Tj. v souboru APIServer.yaml v sekci server přepíšeme hodnotu parametru port na hodnotu 8082 a odstraníme znak # na začátku řádku.

# server configuration
server:
#  address and port to listen to
...
  port: 8082
...

Na řádku s parametrem port odmažte pouze samotný znak # a nechte řádek uvozený dvojicí mezer, aby bylo patrné, že parametr port patří do sekce server. Viz obecná poznámka k formátu yaml výše.

Aktivace nastavení logování

Logování Web API má dvě "úrovně".

Logování činnosti samotného Web API serveru

Úpravami sekce logs v konfiguračním souboru APIServer.yaml je možné ovlivňovat logování činnosti samotného Web API serveru (APIServer.jar). Pokud chcete změnit výchozí hodnotu některého z parametrů, odstraňte znak # na začátku příslušného řádku (dvojici mezer za znakem # ponechte).

Prostřednictvím souboru APIServer.yaml je možné konfigurovat následující parametry týkající se logování:

• path - adresářová cesta, do které jsou logy ukládány.

  Výchozí hodnotou je prázdný řetězec; pokud tuto výchozí hodnotu nezměníte, budou se logy ukládat do stejné složky, ve které se nachází Web API server (soubor APIServer.jar).

  Pokud v cestě používáte zpětná lomítka a zároveň cestu uzavřete do uvozovek, z technických důvodů musíte každé lomítko uvodit dalším zpětným lomítkem, tedy zdvojit.

• level - určuje, jaké informace a v jaké podrobnosti se do logu zapisují. Čím vyšší číslo, tím detailnější logování.

• enabled - aktivuje logování. Pokud chcete logování používat, změňte výchozí hodnotu false na hodnotu true.
• maxsize - maximální velikost logu v bajtech. Výchozí hodnota 0 znamená, že je velikost logu neomezená (do logu se zapisuje, dokud se nezaplní disk). Výchozí hodnotu je vhodné změnit.
• maxcount - počet logů zařazených do rotace.

Dále viz podrobný help. Kap.: Nastavení Web API, sekce Konfigurace logování.

Logování na úrovni business logiky

Logování zpracování požadavků Web API (na úrovni business logiky - tj. co se děje poté, co Web API server předá požadavek knihovně ApiLib.dll) se konfiguruje jako jakékoli jiné logování činnosti ABRA Gen. Tj. do souboru Nexus.cfg zadáte sekci Logs např. následovně:

[Logs]
Level=2
Enabled=1
LogsDirectory=C:\AbraGen\logs\

Pro logování činnosti API (na straně ABRA Gen, tj. například zpracování obdržených požadavků) slouží skupina WA~Group.

Dále viz podrobný help. Kap.: Nastavení Web API.

V ABRA Gen musí být založen uživatel s nastavením nevizuálního přístupu do Web API. V systému ABRA Gen otevřeme agendu Uživatelé. U vybraného uživatele zatrhneme příznak Přihlášení nevizuálního uživatele API. Pro účely naší příručky použijeme uživatele Supervisor, ale v praxi doporučujeme si zavést pro tento účel speciálního uživatele. Pod tímto uživatelem se budeme později dotazovat.

Další podrobnosti podrobný help. Kap.: Uživatelé - záložka Detail.

V rámci komunikace přes Web API se je zapotřebí identifikovat (aby bylo možné ověřit, zda máme k vykonání požadavku a vrácení výsledku potřebné oprávnění). Autentizace uživatelů je realizována pomocí metody HTTP Basic authentication. V požadavku se posílá HTTP hlavička (header) "Authorization". Hodnotou (value) této hlavičky je označení metody ("Basic") a řetězec obsahující uživatelské jméno a heslo oddělené dvojtečkou, převedený do kódování Base64. Celá hlavička vypadá následovně:

Authorization: Basic [uživatelské jméno:heslo v Base64]

Postman vyřeší převod přihlašovacích údajů na autentizační Base64 řetězec za nás, postačí při sestavování požadavku vyplnit přihlašovací jméno (Supervisor) a heslo (prázdné) na záložce Authorization.

Když se následně přepneme na záložku Headers, nalezneme zde předvyplněnou hlavičku Authorization. Zobrazené hlavičky (včetně té autentizační) se budou odesílat na server společně s požadavkem.

Dále viz podrobný help. Kap.: Struktura URI.