Vytváření vlastních rozhraní API, která můžete volat z Azure Logic Apps

Platí pro: Azure Logic Apps (Consumption)

Přestože Azure Logic Apps nabízí stovky konektorů, které můžete použít v pracovních postupech aplikací logiky, můžete chtít volat rozhraní API, systémy a služby, které nejsou dostupné jako konektory. Můžete vytvořit vlastní rozhraní API, která poskytují akce a triggery pro použití v pracovních postupech. Tady jsou další důvody, proč můžete chtít vytvořit vlastní rozhraní API, která můžete volat z pracovních postupů:

• Rozšiřte aktuální integraci systému a pracovní postupy integrace dat.
• Pomozte zákazníkům používat vaši službu ke správě profesionálních nebo osobních úkolů.
• Rozšiřte dosah, zjistitelnost a použijte pro vaši službu.

Konektory jsou v podstatě webová rozhraní API, která jako formát výměny dat používají rozhraní REST, formát metadat Swaggeru pro dokumentaci a JSON. Vzhledem k tomu, že konektory jsou rozhraní REST API, která komunikují prostřednictvím koncových bodů HTTP, můžete k vytváření konektorů, jako jsou .NET, Java, Python nebo Node.js, použít libovolný jazyk. Rozhraní API můžete hostovat také ve službě Aplikace Azure Service, což je nabídka PaaS (platforma jako služba), která poskytuje jeden z nejlepších, nejjednodušších a nejš škálovatelných způsobů hostování rozhraní API.

Aby vlastní rozhraní API fungovala s pracovním postupem aplikace logiky, může vaše rozhraní API poskytovat akce , které provádějí konkrétní úlohy v pracovních postupech. Vaše rozhraní API může také fungovat jako trigger , který spustí spuštění pracovního postupu, když nová data nebo událost splňují zadanou podmínku. Toto téma popisuje běžné vzory, které můžete použít k vytváření akcí a triggerů ve vašem rozhraní API na základě chování, které má vaše rozhraní API poskytnout.

Svá rozhraní API můžete hostovat na Aplikace Azure Service, a to jako nabídku PaaS (platforma jako služba), která poskytuje vysoce škálovatelné a snadné hostování rozhraní API.

Tip

I když můžete rozhraní API nasadit jako webové aplikace, zvažte nasazení rozhraní API jako aplikací API, což může usnadnit úlohu při sestavování, hostování a využívání rozhraní API v cloudu a v místním prostředí. V rozhraních API nemusíte měnit žádný kód – stačí ho nasadit do aplikace API. Naučte se například vytvářet aplikace API vytvořené pomocí těchto jazyků:

• ASP.NET.
• Java
• Node.js
• PHP
• Python

Jak se vlastní rozhraní API liší od vlastních konektorů?

Vlastní rozhraní API a vlastní konektory jsou webová rozhraní API, která jako formát výměny dat používají rozhraní REST, formát metadat Swaggeru pro dokumentaci a JSON. A protože tato rozhraní API a konektory jsou rozhraní REST API, která komunikují prostřednictvím koncových bodů HTTP, můžete pro vytváření vlastních rozhraní API a konektorů použít libovolný jazyk, jako je .NET, Java, Python nebo Node.js.

Vlastní rozhraní API umožňují volat rozhraní API, která nejsou konektory, a poskytovat koncové body, které můžete volat pomocí HTTP + Swagger, Azure API Management nebo App Services. Vlastní konektory fungují jako vlastní rozhraní API, ale mají také tyto atributy:

• Zaregistrované jako prostředky logic Apps Připojení or v Azure.
• V Návrháři pro Logic Apps se zobrazují ikony společně s konektory spravovanými Microsoftem.
• K dispozici pouze autorům konektorů a uživatelům prostředků aplikace logiky, kteří mají stejného tenanta Microsoft Entra a předplatné Azure v oblasti, ve které jsou aplikace logiky nasazené.

Můžete také nominovat registrované konektory pro certifikaci Microsoftu. Tento proces ověří, že registrované konektory splňují kritéria pro veřejné použití a zpřístupní tyto konektory uživatelům v Power Automate a Microsoft Power Apps.

Další informace najdete v následující dokumentaci:

• Přehled vlastních konektorů
• Vytváření vlastních konektorů z webových rozhraní API
• Registrace vlastních konektorů v Azure Logic Apps

Užitečné nástroje

Vlastní rozhraní API funguje nejlépe s aplikacemi logiky, pokud má rozhraní API také dokument Swagger, který popisuje operace a parametry rozhraní API. Mnoho knihoven, jako je Swashbuckle, může automaticky vygenerovat soubor Swagger za vás. Pokud chcete anotovat soubor Swagger pro zobrazované názvy, typy vlastností atd., můžete také použít TRex , aby váš soubor Swagger dobře fungoval s aplikacemi logiky.

Vzory akcí

Aby aplikace logiky prováděly úlohy, měly by vaše vlastní rozhraní API poskytovat akce. Každá operace v rozhraní API se mapuje na akci. Základní akce je kontroler, který přijímá požadavky HTTP a vrací odpovědi HTTP. Pracovní postup například odešle požadavek HTTP do vaší webové aplikace nebo aplikace API. Aplikace pak vrátí odpověď HTTP spolu s obsahem, který může pracovní postup zpracovat.

Pro standardní akci můžete do rozhraní API napsat metodu požadavku HTTP a popsat ji v souboru Swaggeru. Rozhraní API pak můžete volat přímo pomocí akce HTTP nebo akce HTTP + Swagger. Ve výchozím nastavení musí být odpovědi vráceny v rámci limitu časového limitu požadavku.

Pokud chcete, aby pracovní postup čekal na dokončení delších úloh rozhraní API, může vaše rozhraní API postupovat podle vzoru asynchronního dotazování nebo vzoru asynchronního webhooku popsaného v tomto tématu. Pro analogii, která vám pomůže vizualizovat různé chování těchto vzorů, si představte proces objednání vlastního dortu z pekárna. Vzor dotazování zrcadlí chování, ve kterém voláte pekárna každých 20 minut, aby zkontroloval, jestli je dort připravený. Vzor webhooku zrcadlí chování, kdy pekárna žádá o vaše telefonní číslo, aby vám mohli zavolat, když je dort připraven.

Provádění dlouhotrvajících úloh pomocí vzoru akce dotazování

Pokud chcete, aby vaše rozhraní API provádělo úlohy, které by mohly běžet déle, než je limit časového limitu požadavku, můžete použít vzor asynchronního dotazování. Tento model má vaše rozhraní API fungovat v samostatném vlákně, ale aktivní připojení k modulu Azure Logic Apps. Pracovní postup tak nemá časový limit nebo pokračuje dalším krokem v pracovním postupu, než vaše rozhraní API dokončí práci.

Tady je obecný vzor:

1. Ujistěte se, že modul ví, že vaše rozhraní API přijalo požadavek a začalo fungovat.
2. Když modul provede následné požadavky na stav úlohy, dejte modulu vědět, kdy vaše rozhraní API dokončí úlohu.
3. Vraťte do modulu relevantní data, aby pracovní postup mohl pokračovat.

Nyní použijte předchozí pekárna analogie na vzor hlasování, a představte si, že zavoláte pekárna a objednat vlastní dort pro dodání. Proces vytváření dortu nějakou dobu trvá a nechcete čekat na telefonu, zatímco pekárna pracuje na dortu. Pekárna potvrdí vaši objednávku a každých 20 minut zavolá na stav dortu. Po 20 minutách zavoláte pekárna, ale řeknou vám, že váš dort není hotový a že byste měli zavolat za dalších 20 minut. Tento proces pokračuje, dokud nevoláte, a pekárna vám řekne, že vaše objednávka je připravená a doručí váš dort.

Pojďme tedy tento vzor dotazování namapovat zpět. Pekárna představuje vaše vlastní rozhraní API, zatímco vy, zákazník dortu, představuje modul Azure Logic Apps. Když modul volá vaše rozhraní API s požadavkem, vaše rozhraní API potvrdí požadavek a odpoví časovým intervalem, kdy může modul zkontrolovat stav úlohy. Modul pokračuje v kontrole stavu úlohy, dokud vaše rozhraní API neodpovědí, že se úloha dokončí, a vrátí data do aplikace logiky, která pak pokračuje v pracovním postupu.

Tady jsou konkrétní kroky, které má vaše rozhraní API sledovat, jak je popsáno z pohledu rozhraní API:

1. Když vaše rozhraní API získá požadavek HTTP pro zahájení práce, okamžitě vrátí odpověď HTTP 202 ACCEPTED s hlavičkou location popsanou dále v tomto kroku. Tato odpověď umožňuje modulu Azure Logic Apps vědět, že vaše rozhraní API získalo požadavek, přijal datovou část požadavku (vstup dat) a právě zpracovává.

   Odpověď 202 ACCEPTED by měla obsahovat tyto hlavičky:

   • Povinné: Hlavičkalocation, která určuje absolutní cestu k adrese URL, kde může modul Azure Logic Apps zkontrolovat stav úlohy vašeho rozhraní API.

   • Volitelné: Hlavička retry-after , která určuje počet sekund, po které má modul čekat, než zkontroluje location adresu URL stavu úlohy.

     Ve výchozím nastavení se modul dotazuje na adresu URL za jednu sekundu location . Pokud chcete zadat jiný interval, zahrňte retry-after záhlaví a počet sekund do dalšího dotazování.

2. Po uplynutí zadané doby se modul Azure Logic Apps dotazuje location na adresu URL a zkontroluje stav úlohy. Vaše rozhraní API by mělo provádět tyto kontroly a vracet tyto odpovědi:

   • Pokud je úloha hotová, vraťte odpověď HTTP 200 OK spolu s datovou částí odpovědi (vstup pro další krok).

   • Pokud úloha stále zpracovává, vraťte další odpověď HTTP 202 ACCEPTED , ale se stejnými hlavičkami jako původní odpověď.

Když se vaše rozhraní API řídí tímto vzorem, nemusíte v definici pracovního postupu dělat nic, abyste mohli pokračovat v kontrole stavu úlohy. Když modul získá odpověď HTTP 202 ACCEPTED a platnou location hlavičku, modul respektuje asynchronní vzor a zkontroluje hlavičku location , dokud vaše rozhraní API nevrátí odpověď, která není 202.

Tip

Příklad asynchronního vzoru najdete v této ukázce odpovědi asynchronního kontroleru na GitHubu.

Provádění dlouhotrvajících úloh pomocí vzoru akce webhooku

Jako alternativu můžete použít model webhooku pro dlouhotrvající úlohy a asynchronní zpracování. Tento vzor pozastaví pracovní postup a před pokračováním pracovního postupu počká na dokončení zpracování zpětného volání z vašeho rozhraní API. Toto zpětné volání je HTTP POST, který odesílá zprávu na adresu URL, když dojde k události.

Nyní použijte předchozí pekárna analogie na webhook vzor, a představte si, že zavoláte pekárna a objednat vlastní dort pro dodání. Proces vytváření dortu nějakou dobu trvá a nechcete čekat na telefonu, zatímco pekárna pracuje na dortu. Pekárna potvrdí vaši objednávku, ale tentokrát jim dáte své telefonní číslo, aby vám mohli zavolat, až bude dort hotový. Tentokrát vám pekárna řekne, kdy je vaše objednávka připravená a doručí váš dort.

Když tento vzor webhooku namapujeme zpět, pekárna představuje vaše vlastní rozhraní API, zatímco vy, zákazník dortu, představuje modul Azure Logic Apps. Modul volá vaše rozhraní API s požadavkem a obsahuje adresu URL zpětného volání. Po dokončení úlohy vaše rozhraní API pomocí adresy URL upozorní modul a vrátí data do aplikace logiky, která pak pokračuje v pracovním postupu.

Pro tento model nastavte na kontroleru dva koncové body: subscribeunsubscribe

• subscribe koncový bod: Když provádění dosáhne akce rozhraní API v pracovním postupu, modul Azure Logic Apps volá subscribe koncový bod. Tento krok způsobí, že pracovní postup vytvoří adresu URL zpětného volání, kterou vaše rozhraní API ukládá, a po dokončení práce pak čeká na zpětné volání z vašeho rozhraní API. Vaše rozhraní API pak zavolá zpět pomocí http POST na adresu URL a předá veškerý vrácený obsah a hlavičky jako vstup do aplikace logiky.

• unsubscribe koncový bod: Pokud je spuštění pracovního postupu zrušeno, modul Azure Logic Apps volá unsubscribe koncový bod. Vaše rozhraní API pak může zrušit registraci adresy URL zpětného volání a podle potřeby zastavit všechny procesy.

Návrhář pracovního postupu v současné době nepodporuje zjišťování koncových bodů webhooku prostřednictvím Swaggeru. Pro tento vzor tedy musíte přidat akci Webhooku a zadat adresu URL, záhlaví a text požadavku. Viz také akce a triggery pracovního postupu. Příklad vzoru webhooku najdete v této ukázce triggeru webhooku na GitHubu.

Tady jsou některé další tipy a poznámky:

• Pokud chcete předat adresu URL zpětného volání, můžete podle potřeby použít @listCallbackUrl() funkci pracovního postupu v libovolném z předchozích polí.

• Pokud vlastníte prostředek aplikace logiky i předplacenou službu, nemusíte po volání adresy URL zpětného volání volat unsubscribe koncový bod. Jinak modul runtime Azure Logic Apps musí volat unsubscribe koncový bod, aby signalizoval, že se neočekávají žádná další volání, a aby bylo možné vyčistit prostředky na straně serveru.

Vzory aktivačních událostí

Vaše vlastní rozhraní API může fungovat jako trigger , který spustí pracovní postup, když nová data nebo událost splňují zadanou podmínku. Tento trigger může pravidelně kontrolovat nebo naslouchat novým datům nebo událostem ve vašem koncovém bodu služby. Pokud nová data nebo událost splňují zadanou podmínku, trigger se aktivuje a spustí aplikaci logiky, která naslouchá dané aktivační události. Pokud chcete spustit aplikace logiky tímto způsobem, může vaše rozhraní API postupovat podle triggeru dotazování nebo vzoru triggeru webhooku. Tyto vzory jsou podobné jejich protějškům pro akce dotazování a akce webhooku. Přečtěte si také další informace o měření využití pro triggery.

Pravidelně kontrolujte nová data nebo události pomocí vzoru triggeru dotazování.

Trigger dotazování funguje podobně jako akce dotazování popsaná v tomto tématu. Modul Azure Logic Apps pravidelně volá a kontroluje koncový bod triggeru pro nová data nebo události. Pokud modul najde nová data nebo událost, která splňuje zadanou podmínku, aktivuje se trigger. Potom modul vytvoří instanci pracovního postupu, která zpracovává data jako vstup.

Poznámka:

Každý požadavek dotazování se počítá jako provádění akce, i když není vytvořena žádná instance pracovního postupu. Aby se zabránilo zpracování stejných dat vícekrát, trigger by měl vyčistit data, která už byla přečtená a předána do aplikace logiky.

Tady jsou konkrétní kroky pro trigger dotazování popsané z pohledu rozhraní API:

Našli jste nová data nebo událost?	Odpověď rozhraní API
Nalezen	Vrátí stav HTTP 200 OK s datovou částí odpovědi (vstup pro další krok). Tato odpověď vytvoří instanci pracovního postupu a spustí pracovní postup.
Nenalezeno	Vrátí stav HTTP 202 ACCEPTED se záhlavím location a hlavičkou retry-after . U triggerů location by hlavička měla obsahovat triggerState také parametr dotazu, což je obvykle časové razítko. Vaše rozhraní API může tento identifikátor použít ke sledování posledního spuštění pracovního postupu.

Pokud například chcete pravidelně kontrolovat nové soubory ve službě, můžete vytvořit trigger dotazování, který má toto chování:

Žádost zahrnuje triggerState?	Odpověď rozhraní API
No	Vrátí stav HTTP 202 ACCEPTED a hlavičku location s nastaveným triggerState aktuálním časem a retry-after intervalem na 15 sekund.
Ano	Zkontrolujte, jestli vaše služba obsahuje soubory přidané za for DateTimetriggerState.

Počet nalezených souborů	Odpověď rozhraní API
Jeden soubor	Vrátí stav HTTP 200 OK a datovou část obsahu, aktualizuje triggerState se na DateTime vrácený soubor a nastaví retry-after interval na 15 sekund.
Více souborů	Vrátí vždy jeden soubor a stav HTTP 200 OK , aktualizaci triggerStatea nastaví retry-after interval na 0 sekund. Tímto postupem dáme modulu vědět, že jsou k dispozici další data a že by měl modul okamžitě požádat o data z adresy URL v location hlavičce.
Žádné soubory	Vrátí stav HTTP 202 ACCEPTED , nezmění triggerStatese a nastaví retry-after interval na 15 sekund.

Tip

Příklad vzoru triggeru dotazování najdete v této ukázce kontroleru triggeru hlasování na GitHubu.

Čekání a naslouchání novým datům nebo událostem pomocí vzoru triggeru webhooku

Trigger webhooku je trigger nabízených oznámení, který čeká a naslouchá novým datům nebo událostem v koncovém bodu služby. Pokud nová data nebo událost splňují zadanou podmínku, trigger se aktivuje a vytvoří instanci pracovního postupu, která pak zpracuje data jako vstup. Triggery Webhooku fungují podobně jako akce webhooku popsané v tomto tématu a jsou nastavené s subscribe koncovými body.unsubscribe

• subscribe koncový bod: Když do aplikace logiky přidáte a uložíte trigger webhooku, modul Azure Logic Apps zavolá subscribe koncový bod. Tento krok způsobí, že pracovní postup vytvoří adresu URL zpětného volání, kterou vaše rozhraní API ukládá. Pokud jsou k dispozici nová data nebo událost, která splňuje zadanou podmínku, vaše rozhraní API volá zpět pomocí http POST na adresu URL. Datová část obsahu a hlavičky se předávají jako vstup do aplikace logiky.

• unsubscribe koncový bod: Pokud se odstraní trigger webhooku nebo celý prostředek aplikace logiky, modul Azure Logic Apps zavolá unsubscribe koncový bod. Vaše rozhraní API pak může zrušit registraci adresy URL zpětného volání a podle potřeby zastavit všechny procesy.

Návrhář pracovního postupu v současné době nepodporuje zjišťování koncových bodů webhooku prostřednictvím Swaggeru. Pro tento vzor tedy musíte přidat trigger Webhooku a zadat adresu URL, hlavičky a text požadavku. Viz také trigger HTTPWebhook. Příklad vzoru webhooku najdete v této ukázce kontroleru triggeru webhooku na GitHubu.

Tady jsou některé další tipy a poznámky:

• Pokud chcete předat adresu URL zpětného volání, můžete podle potřeby použít @listCallbackUrl() funkci pracovního postupu v libovolném z předchozích polí.

• Aby se zabránilo zpracování stejných dat vícekrát, trigger by měl vyčistit data, která už byla přečtená a předána do aplikace logiky.

• Pokud vlastníte prostředek aplikace logiky i předplacenou službu, nemusíte po volání adresy URL zpětného volání volat unsubscribe koncový bod. Jinak modul runtime Logic Apps musí volat unsubscribe koncový bod, aby signalizoval, že se neočekávají žádná další volání, a aby bylo možné vyčištění prostředků na straně serveru.

Vylepšení zabezpečení pro volání vašich rozhraní API z aplikací logiky

Po vytvoření vlastních rozhraní API nastavte ověřování pro vaše rozhraní API, abyste je mohli bezpečně volat z aplikací logiky. Zjistěte , jak zlepšit zabezpečení volání vlastních rozhraní API z aplikací logiky.

Nasazení a volání rozhraní API

Po nastavení ověřování nastavte nasazení pro vaše rozhraní API. Zjistěte , jak nasadit a volat vlastní rozhraní API z aplikací logiky.

Publikování vlastních rozhraní API do Azure

Pokud chcete, aby vaše vlastní rozhraní API byla dostupná pro ostatní uživatele Azure Logic Apps, musíte přidat zabezpečení a zaregistrovat je jako konektory Azure Logic Apps. Další informace najdete v tématu Přehled vlastních konektorů.

Pokud chcete, aby vaše vlastní rozhraní API byla dostupná všem uživatelům v Logic Apps, Power Automate a Microsoft Power Apps, musíte přidat zabezpečení, zaregistrovat rozhraní API jako konektory Azure Logic Apps a jmenovat konektory pro certifikovaný program Microsoft Azure.

Technická podpora

• Pokud získáte konkrétní pomoc s vlastními rozhraními API, obraťte se na customapishelp@microsoft.com.

• Pokud máte dotazy, navštivte stránku s dotazy k Microsoft Q&A pro Azure Logic Apps.

Další kroky

• Zpracování chyb a výjimek
• Volání, trigger nebo vnoření aplikací logiky pomocí koncových bodů HTTP
• Měření využití pro akce a triggery