Doplněk RESTer
Přístup k Sofa přes API využívá volání v GraphQL. K povolení přístupu je třeba získat tzv. tokeny. Ty lze získat pomocí požadavku REST. K realizaci tohoto požadavku existují různé nástroje, s výhodou lze využít například snadno dostupný prohlížečový doplněk RESTer.
Kde doplněk RESTer získáte
Doplněk RESTer si můžete stáhnout pro prohlížeče Firefox a Chrome:
-
RESTer pro Firefox na adrese – https://addons.mozilla.org/cs/firefox/addon/rester/
-
RESTer pro Chrome na adrese – https://chrome.google.com/webstore/detail/rester/eejfoncpjfgmeleakejdcanedmefagga
Vystavení tokenu ExtIS pod identitou ExtIS
Jedná se požadavek na vystavení tokenu, který bude identifikovat určitý externí informační systém – nikoliv konkrétního uživatele Sofa.
Po otevření doplňku (v okně prohlížeče Firefoxu nebo Chrome klepnutím na ikonku vpravo nahoře) je možné sestavit a odeslat vlastní požadavek.
Sestavení požadavku
Důležitý je výběr správné metody požadavku. V poli Method nastavte pro náš případ položku POST.
Do pole URL je třeba vyplnit adresu, na kterou je zapotřebí požadavek odeslat do Sofa (adresy pro jednotlivá prostředí viz tabulka):
Prostředí | URL |
---|---|
DEV |
|
PRE |
|
TEST |
|
PROD |
Dále pomocí voliče v poli Name přidejte do požadavku hlavičku Content-Type.
Této hlavičce pak voličem Value přiřaďte hodnotu application/json.
Následně je potřeba pod záložkou BODY vyplnit tělo požadavku. Tělo musí obsahovat JSON s loginem a heslem (viz kapitola Nastavení externího informačního systému). Příklad zápisu JSONu je:
{
"Login": "_bacc83fc593e4577b23074e4eeaa9a40_",
"Password": "_heslo z bodu 1_"
}
Řetězec Login je obsah pole Uživatel.
Odeslání požadavku
Nakonec je možné pomocí tlačítka SEND požadavek odeslat.
Pokud je požadavek sestavený správně (viz zelený indikátor 200 OK), zobrazí se odpověď, která v těle obsahuje vyžádaný token k externímu informačnímu systému s identitou tohoto ExtIS. Tímto tokenem je řetězec začínající znaky "ey…" (bez uvozovek).
V případě chyby bude výsledek operace například takovýto:
Pak jste něco zadali nesprávně. Zkontrolujte především údaj Login a také URL adresu, zde se chybuje nejvíc. Pak zkuste požadavek odeslat znovu.
Vystavení tokenu ExtIS pod identitou uživatele
Jedná se požadavek na vystavení tokenu, který bude identifikovat určitý externí informační systém – pod identitou konkrétního uživatele Sofa.
Sestavení požadavku
Pro přístup k API je nutné nejprve získat přístupový token ke koncovému bodu pro přihlášení externího informačního systému pod identitou konkrétního uživatele.
Koncový bod: …/api/sofa/v1/auth/extis/login-impersonate
Metoda: POST
Hlavička:
-
Content-Type: application/x-www-form-urlencoded
Parametry:
-
Login – uživatelské jméno k přihlášení do externího informačního systému; zjistíte ho v okně Úpravy detailu externího IS (viz kapitola Nastavení externího informačního systému).
-
Password – přístupové heslo do externího informačního systému (viz výše uvedená kapitola).
-
ImpersonateUserId – Sofa identifikátor uživatele, jehož identitou má externí informační systém vystupovat – návod na zjištění tohoto identifikátoru je uveden v kapitole Jak zjistit identifikátor uživatele.
Příklad získání tokenu ExtIS v doplňku RESTer uvedeme na trojici obrázků.
-
Nastavení údajů Method a URL a hlavičkového údaje Content-Type na kartě HEADERS:
-
Nastavení parametrů Login, Password a ImpersonateUserId na kartě BODY:
U všech řádků pro zadání hodnot parametrů musí být ve sloupci Type nastaven typ Text.
Odeslání požadavku
Stiskem tlačítka SEND požadavek odešlete k vyřízení.
Pokud se požadavek vyřídí úspěšně (s odpovědí 200 OK), najdete požadovaný token v dolní části okna – je to ten dlouhý řetězec v uvozovkách. Pozor! Uvozovky součástí tokenu nejsou, ten musí začínat znaky ey!
Příklad:
POST /api/sofa/v1/auth/extis/login-impersonate HTTP/1.1 + Host: sofaws.602.cz + Content-Length: 119 + Content-Type: application/x-www-form-urlencoded + + Login=48a0ecdd540849f0af416307406467f0&Password=wau3S99vx2d_NW2P&ImpersonateUserId=9e5f2f76-fff5-44c3-b943-06a95fdc08e2
Výsledek:
{
"token": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOi…"
}
Ukládání požadavků pro příští použití
RESTer umožňuje ukládání šablon připravených požadavků; je tedy možné si vytvářet vlastní kolekce s různými požadavky. Lze si tak připravit požadavky k napojení na všeliké organizace a s různými parametry.
K uložení kolekce a požadavku slouží modrý řádek. Je nutné vyplnit název ve tvaru Název kolekce / Název požadavku a kliknout na tlačítko pro uložení v pravém horním rohu.
Nyní se požadavek uloží a jeho název je viditelný v levé nabídce. Pod zadaným názvem kolekce a je možné ho používat do budoucna.