Způsob vytváření programových bloků
Každá operácia v sekcii Definition predstavuje samostatné API volanie voči systému CDESK. Tieto operácie je možné vytvárať na základe existujúcich endpointov, ktoré sú dostupné v Swagger (OpenAPI) dokumentácii CDESK servera.
Doporučený postup
Před samotným vytvořením operace v Power Automate je vhodné:
- Otestovat API volání v nástroji Postman
Testování v Postmanu umožňuje ověřit chování endpointu, jeho vstupních parametrů a analyzovat návratová data bez nutnosti úprav konektoru. - Ověřit autentifikaci a oprávnění
Ujistěte se, že API uživatel, pod kterým se volání provádí, má dostatečná oprávnění pro danou operaci. Nedostatečná oprávnění se mohou projevit chybami 401 Unauthorized nebo 403 Forbidden. - Získat funkční vzorový URL (sample URL)
Po úspěšném otestování volání v Postmanu je vhodné použít funkční request URL jako základ pro definici operace v Power Automate. - Importovat nebo ručně nakonfigurovat operaci v konektoru
V sekci Definition se následně vytvoří nová operace, do které se přenese URL, HTTP metoda, hlavičky, parametry a očekávaná odpověď.
Zjištění koncového bodu API pomocí Dev Tools (F12)
Další možností, jak zjistit správný API endpoint, je využít vývojářské nástroje přímo v rozhraní CDESK.
Postup je následující:
- Přihlaste se do CDESK ve webovém prohlížeči.
- Otevřete vývojářskou konzoli pomocí klávesy F12.
- Přepněte na záložku Network.
- V rozhraní CDESK vykonejte požadovanou akci (např. vyhledání požadavků, otevření detailu, uložení požadavku atd.).
- V seznamu síťových volání vyhledejte API request, který danou akci vyvolal.
Po identifikaci správného volání je možné:
- zkontrolovat použitý API endpoint
- ověřit HTTP metodu
- zobrazit parametry dotazu, hlavičky a tělo požadavku
Ověření volání v Postmanu
Identifikované volání API se doporučuje následně otestovat v nástroji Postman, kde je možné ověřit jeho funkčnost, chování a návratová data mimo Power Automate. Teprve po úspěšném otestování se doporučuje použít toto volání při vytváření operace v sekci Definition Custom Connectora.
Filtrování požadavků pomocí filtru SB
Tímto způsobem lze získat také volání API, která využívají a filtr SB na straně CDESK. Filtr SB se nachází jako parametr v URL a umožňuje filtrovat data již na straně backendu.
Například při vyhledávání požadavků:
- API endpoint vrátí pouze ty požadavky, které splňují podmínky definované ve filtru SB
- namísto zpracování celého seznamu požadavků ve flow
- Prejdite do sekcie, v ktorej je dostupné vyhľadávanie, napríklad Requests, a kliknite na ikonu Advanced filter
. - V poli filter si vytvoríte vlastný filter na strane CDESK, následne otvoríte Dev console prehliadača (F12)
- Prejdete do sekcie Network v Dev console, spustíte nahrávanie akcií, a kliknete v CDESK na tlačidlo Hľadať.
- V sekcii Network sa zobrazia API volania vykonané na základe vašej akcie. Identifikujte volanie, ktoré zodpovedá vyhľadávaniu, a kliknite naň.
.
V hlavičce volání se nachází parametr sb, který má v backendovém API stejnou funkci jako filtr nastavený v Advanced filter. To znamená, že při volání API endpointu s daným parametrem sb vrátí API pouze ta data, která jsou vyhovující pro zvolený filtr.
Tímto způsobem lze nastavit filtrování pro API koncové body, které podporují vyhledávání, jako například Requests, Work Orders, Address Book, Contacts a další. Ve všech případech, kdy je možné nastavit filtr v uživatelském rozhraní, lze stejný filtr použít i na úrovni volání API.
Vytváření a testování vlastních programových bloků
Pro vytvoření vlastních programových bloků je nutné přidat Action v záložce 3. Definition Custom Connectora. Action představuje jednu operaci konektoru, která mapuje konkrétní API volání vůči systému CDESK. Každá Action definuje:
- cílový API endpoint
- použitou HTTP metodu
- vstupní parametry (URL, query, headers, body)
Z pohledu Power Automate se akce chová jako samostatný funkční blok, který lze v cloudových tokech použít stejně jako nativní konektory.
V rozhraní Custom Connectora prejdite do záložky 3. Definition. Kliknite na tlačidlo New action.
Je třeba vyplnit následující informace o programovém bloku:
- Summary – výstižný popis bloku, zobrazuje se při použití ve Flow
- Description – jednoduchý interní popis, vhodný v případě, že více bloků používá stejné volání API
- Operation ID – interní ID operace pro Power Automate, musí být jedinečné, začíná velkým písmenem
Následne pre nastavenie API volania kliknite na 4. Import from sample.
1. HTTP metoda (Verb)
V této části se vybírá HTTP metoda, která určuje typ prováděné operace vůči CDESK API. Zvolená metoda musí odpovídat definici endpointu v Swagger dokumentaci CDESK.
2. URL
Pole URL obsahuje úplnou adresu API koncového bodu, který bude volán.
V případě potřeby dynamické práce s URL volání je možné v adrese definovat proměnné, se kterými je následně možné pracovat v rámci toku Power Automate. Tyto proměnné jsou při použití operace vyplňovány dynamickým obsahem nebo hodnotami získanými z předchozích kroků.
Například při práci s konkrétním požadavkem je nutné, aby bylo v URL dynamicky přiřazeno ID požadavku. Z tohoto důvodu je při vytváření operace nutné definovat URL v následujícím tvaru:
https://cdesk_address.xx/api/request/{requestId}
Při takovéto definici je možné s proměnnou requestId dále pracovat ve flow, například iterovat seznamem více požadavků a volat každý z nich samostatně.
3. Headers
V tejto časti sa definujú HTTP hlavičky odosielané spolu s požiadavkou.
Napríklad:
- Content-Type: application/json
Autorizační hlavička (Authorization) se nezadává ručně, protože je automaticky spravována mechanismem OAuth 2.0 a upravována pomocí vlastního kódu v konektoru.
Po importovaní sa vami zadané údaje zobrazia v tabuľke Request. Ak sú údaje správne, kliknite na tlačidlo Update Connector, následne sa presuňte do tabu 5. Test.
1. Vytvoření a výběr připojení
V horní části obrazovky je třeba vytvořit nebo vybrat připojení, které se používá k autentizaci vůči serveru CDESK. Pokud ještě žádné připojení neexistuje, lze jej vytvořit kliknutím na Nové připojení.
V případě, že je k dispozici více připojení, je vhodné zvolit nejnovější připojení podle času vytvoření, aby se předešlo použití neaktuálních nebo neplatných přihlašovacích údajů.
2. Výběr operace
V levé části obrazovky se nachází seznam dostupných API volání konektoru. V tomto případě se jedná o API volání Profile.
3. Spuštění testu
Po výběru operace je možné spustit její testování kliknutím na tlačítko Test operation. Power Automate v tomto kroku vykoná skutečné volání API na server CDESK pomocí zvoleného připojení.
4. Vyhodnocení odpovědi
Výsledek testu se zobrazuje v dolní části obrazovky v sekci Response. Stav 200 signalizuje úspěšné provedení operace. Zobrazují se HTTP hlavičky i tělo odpovědi. Zelený kruh u operace potvrzuje, že volání proběhlo úspěšně a konektor funguje správně.
V tomto případě jsme volali API endpoint Profile, který nám vrátil informace o aktuálně přihlášeném uživateli. V odpovědi můžete nahlédnout do pole Body, kde bude zobrazeno aktuální ID uživatele a ověřit si, že konektor provádí API volání pod správným účtem CDESK.
V případě chyby je možné podrobně analyzovat odpověď serveru a případné chyby v záložce Code Logs.