Úvod - API

Z WikiOrange
Přejít na: navigace, hledání


Upozornění Verze API: 2.0.2018.0926


Úvod

Helios Orange API je množina SQL uložených procedur a view. Poskytuje unifikované rozhraní pro možnost pořizovat, měnit, mazat a číst záznamy ve vybraných agendách a číselnících Helios Orange. API je primárně určeno pro komunikaci mezi externími systémy a Helios Orange. Externí systém řídí celou komunikaci (je aktivním článkem), tj. volá příslušné procedury, zpracovává jejich návratové hodnoty (a případné chybové stavy) nebo čte údaje z databáze prostřednictvím view. API je „pasivní vrstvou“ ve formě SQL objektů v databázi.

Příklad Typickým příkladem externího systému je e-shop, který (dle konkrétní implementace) zakládá objednávky do Heliosu, zpětně potřebuje číst katalog zboží, stav skladu, ceníky, číselník organizací…

Instalace se provádí standardním způsobem formou rozšiřujícího modulu (pluginu). Po instalaci dojde pouze k založení příslušných databázových objektů, na uživatelské úrovni v systému se instalace nijak neprojeví (nepřibudou žádné nové soudečky či akce). Vzhledem k povaze API (databázové objekty) je nutno provést jeho instalaci do všech databází, ve kterých má být API využíváno.

Jednotlivé procedury API pracují vždy na úrovni jedné primární tabulky, do které se provádí zápis hodnot. S výjimkou jednoduchých číselníků je však datová struktura Helios Orange obvykle složitější, hlavní záznam může obsahovat celou řadu vazebních údajů do jiných číselníků a nebo se k němu váže ve vztahu 1:N více záznamů v dalších tabulkách. Typickým příkladem může být například číselník organizací – k hlavnímu záznamu (obecné údaje o organizaci) může existovat více bankovních spojení, více kontaktů apod. Zároveň existuje na organizaci např. kód země, což je vazební údaj (cizí klíč) do příslušného číselníku zemí.

Při vytváření složitějšího záznamu s komplexním provázáním je tedy potřeba postupovat tak, že se nejprve založí záznamy do číselníků, do kterých má hlavní záznam nějakou vazbu (např. zmiňované kódy zemí v případě organizací). Následně je založen hlavní záznam a teprve jako poslední krok se voláním dalších procedur API k tomuto hlavnímu záznamu doplní návazné údaje v podřízených tabulkách (např. kontakty).

Složitější zápis je tedy typicky složen z několika logicky navazujících kroků – volání dílčích procedur API, přičemž volání některých procedur se může i v cyklu opakovat (např. zakládání více kontaktů, položek faktur apod.).

Upozornění Komunikace prostřednictvím API je preferovaným způsobem napojení systémů třetích stran na Helios Orange.


Technologické možnosti napojení

Konkrétní technická implementace napojení je záležitostí externího systému, jeho možností a platformy. Nabízí se v zásadě dva hlavní scénáře – „přímé“ propojení na úrovni SQL nebo REST webové služby. V případě přímé komunikace na úrovni SQL volá externí systém procedury API v databázi Helios Orange a to buď napřímo (pokud běží externí systém na stejném MS SQL serveru) nebo prostřednictvím vzdáleného propojení (linked server), ODBC apod.

Pro využití REST webových služeb je nutno nainstalovat modul Helios Orange eServer a využívat příslušné metody pro volání SQL procedur a view. eServer funguje v tomto případě jako „prostředník“, který vytváří REST vrstvu a izoluje externí systém od přímého napojení do databáze. V konečném důsledku nicméně dochází opět k volání SQL procedur API, takže popis jednotlivých parametrů procedur se vztahuje i na variantu volání přes eServer. Detailní popis způsobu volání REST služeb je popsán v kapitole Helios Orange eServer SDK.

Upozornění Pro koumunikaci API x eServer, je třeba mít zakoupenou licenci eServer Premium.


Základní kostra procedur API

Všechny procedury API se skládají ze dvou množin vstupních/výstupních parametrů. Základní sada parametrů je pro všechny procedury stejná – mimo jiné určuje typ operace se záznamem (INSERT/UPDATE/DELETE…), dále použitou legislativu, jazykovou mutaci a další obecné parametry, ovlivňující chování dané procedury. Součástí této množiny jsou i návratové parametry s kódem a textem případné chybové hlášky.

Druhou sadu tvoří parametry, které jsou specifické pro každou konkrétní agendu (číselník) a do značné míry odpovídají atributům cílové tabulky (názvem i datovým typem). Drtivá většina těchto parametrů není povinná.

Výstupní parametry lze volitelně vracet též prostřednictvím SELECTu volaného na konci procedur. Tento způsob je vhodné použít v situaci, kdy nejsou procedury API volány napřímo z jiného SQL kódu, ale přes REST webové služby či jiného „klienta“ (např. pluginu Helios Orange apod.), pro kterého je jednodušší číst výsledný dataset.

název procedury: dbo.hpx_ASOL_API_XXXXXXXXX

Prefix názvu procedur API je vždy stejný, proměnlivá část pak obsahuje anglický název dané agendy či číselníku. Dle této masky lze identifikovat v databázi všechny procedury, které jsou součástí API.


Společné parametry všech procedur API

@ID INT OUT

Vstupně/výstupní parametr, který slouží jako primární identifikátor záznamu, který je zpracováván. Pokud se jedná o zápis nového záznamu, na vstupu se předává NULL a na výstupu je vráceno ID vytvořeného záznamu z cílové tabulky. Údaj může následně sloužit pro další zpracování. Jedná-li se o aktualizaci/mazání záznamu, lze ID využít jako primární identifikátor. Není-li ID známo, záznam je nutno identifikovat „sekundárním“ identifikátorem – jiný jednoznačný údaj (či kombinace více údajů) pro jednoznačné dohledání záznamu. Sekundární identifikátor (další parametr procedury) nemusí být k dispozici u všech procedur, jeho dostupnost je závislá na konkrétní agendě/číselníku. Konkrétní sekundární identifikátory jsou vždy popsány u příslušných procedur API a jsou rovněž vraceny jako výstupní parametry.


@ErrorMsg NVARCHAR(4000) OUT

Výstupní parametr pro případnou chybovou hlášku v textové podobě. Nedojde-li k chybě, vrací NULL. Text hlášky je uveden v té jazykové mutaci, která je určena vstupním parametrem @Language (dále v dokumentaci) a to v případě, že je daný překlad k dispozici (jinak se vrací text v českém jazyce).


@ErrorNum INT OUT

Výstupní parametr s číslem chybové hlášky, které odpovídá textu v @ErrorMsg (pro lepší strojové zpracování chyb). Nedojde-li k chybě, vrací hodnotu 0. Každá procedura API má vlastní seznam chybových kódů specifických pro danou proceduru. Seznam chybových kódů je uveden u každé procedury samostatně.


@Action TINYINT = 0

Vstupní parametr určující požadovanou akci, která má být se záznamem provedena. K dispozici jsou následující varianty:

  • 0 = založení nového záznamu (INSERT); pokud záznam dle primárního či sekundárního identifikátoru již existuje, akce se neprovede a končí chybou; použitelné pouze pro zakládání nových záznamů
  • 1 = založení nového záznamu nebo jeho aktualizace (INSERT OR UPDATE); pokud záznam dle primárního či sekundárního identifikátoru již existuje, bude aktualizován a v případě neexistence založen
  • 2 = aktualizace existujícího záznamu (UPDATE); použitelné pouze pro již existující záznamy, dohledané dle primárního či sekundárního identifikátoru; použity jsou pouze ty vstupní parametry procedury, které nemají hodnoty NULL; všechny ostatní parametry (=atributy cílové tabulky) budou zachovány v původních hodnotách; při aktualizaci jen vybrané podmnožiny atributů tedy není třeba posílat kompletní sadu všech parametrů, stačí předávat pouze parametry (=atributy), které mají být změněny
  • 3 = „vynucená“ aktualizace existujícího záznamu (FORCE UPDATE); obdoba varianty 2 s tím rozdílem, že budou použity veškeré vstupní parametry včetně NULL hodnot a cílový záznam tak bude kompletně přepsán údaji předanými proceduře
  • 4 = smazání záznamu (DELETE); záznam bude smazán pouze v případě, že to integritní či další omezení dovolí, tj. nelze smazat záznamy již navázané na další záznamy v Heliosu apod., nicméně procedura se automaticky pokusí smazat ty návazné údaje, které smazat lze (tj. typicky externí atributy náležící k danému záznamu apod.), tj. provádí se stejná akce jako při „ručním“ uživatelském mazání záznamu na úrovni aplikace


@Language SMALLINT = 1

Jazyk, ve kterém bude vrácen text chybové hlášky (existuje-li překlad do daného jazyka). Výchozí hodnotou je čeština; neexistuje-li překlad chybové hlášky do zvoleného jazyka, je text taktéž vrácen v češtině


@Legislation TINYINT = 0

Legislativa, se kterou má procedura pracovat. Výchozí je legislativa česká. Ve velmi ojedinělých případech může mít zvolená legislativa vliv na způsob, jakým procedury se záznamy pracují, a proto lze specificky určit, která má být použita.


@ResultSELECT BIT = 0

Příznak, kterým lze ovlivnit způsob předávání návratových hodnot z procedury. Výchozí hodnota (0) říká, že výstup je prováděn standardním způsobem přes OUT parametry procedury. Tato varianta je obvyklá, pakliže jsou procedury volány napřímo na úrovni SQL (z jiných procedur, skriptů apod.). Hodnota 1 znamená, že všechny návratové hodnoty budou předány prostřednictvím SELECTu, volaného na konci procedury. Výsledkem zavolání procedury je tedy resultset, který může být zpracován například prostřednictvím REST rozhraní eServeru nebo libovolné jiné aplikace (klienta). Při použití eServeru (REST webových služeb) je toto vyžadované nastavení. Systémové názvy polí návratového resultu odpovídají názvům výstupních parametrů procedury.


Uživatelské procedury

Do všech procedur API je zabudován mechanismus tzv. uživatelských (slepých) procedur. Jedná se o procedury pevně určeného názvu, které jsou hlavními procedurami API automaticky zavolány v rámci zpracování záznamu, pakliže je detekována jejich existence. Je to volitelná možnost, jak na míru napsaným kódem ještě dodatečně pozměnit vytvořený záznam, spustit po vytvoření záznamu nějaké další zpracování apod.

V rámci API procedur je možnost volat dvě uživatelské procedury – na začátku zpracování a na jeho konci. Názvy procedur vycházejí z názvu příslušné hlavní procedury API a jsou tvořeny touto maskou: hpx_ASOL_API_<HlavniProcedura>_EP<xx>

<HlavniProcedura> - část názvu hlavní procedury specifikující konkrétní modul/číselník

<xx> - pořadové číslo procedury – 01 se volá na začátku, 02 na konci zpracování


Vstupní parametry (hlavička procedur):

CREATE PROC dbo.hpx_ASOL_API_<HlavniProcedura>_EPxx
@ID INT,
@Action TINYINT,
@Language SMALLINT,
@Legislation TINYINT

Význam jednotlivých parametrů odpovídá stejným parametrům hlavní procedury (popsáno v příslušných samostatných částech dokumentace).


Příklady:

Příklad dbo.hpx_ASOL_API_Employees_EP02

procedura, která je volána na závěr procedury pro zpracování zaměstnanců


Příklad dbo.hpx_ASOL_API_Companies_EP01

procedura, která je volána na začátku procedury pro zpracování organizací


Příklad hpx_ASOL_API_GoodsAndServices_EP02

procedura, která je volána na závěr procedury pro zpracování kmenových karet