Skapa anpassade API:er som du kan anropa från Azure Logic Apps

Gäller för: Azure Logic Apps (förbrukning)

Även om Azure Logic Apps erbjuder hundratals anslutningsappar som du kan använda i arbetsflöden för logikappar, kanske du vill anropa API:er, system och tjänster som inte är tillgängliga som anslutningsappar. Du kan skapa egna API:er som tillhandahåller åtgärder och utlösare som ska användas i arbetsflöden. Här är andra orsaker till varför du kanske vill skapa egna API:er som du kan anropa från arbetsflöden:

• Utöka dina aktuella arbetsflöden för systemintegrering och dataintegrering.
• Hjälp kunder att använda din tjänst för att hantera professionella eller personliga uppgifter.
• Utöka räckvidden, identifieringen och användningen för din tjänst.

I grund och botten är anslutningsappar webb-API:er som använder REST för anslutningsbara gränssnitt, Swagger-metadataformat för dokumentation och JSON som datautbytesformat. Eftersom anslutningsappar är REST-API:er som kommunicerar via HTTP-slutpunkter kan du använda valfritt språk för att skapa anslutningsappar, till exempel .NET, Java, Python eller Node.js. Du kan också vara värd för dina API:er på Azure App Service, ett PaaS-erbjudande (plattform som en tjänst) som tillhandahåller ett av de bästa, enklaste och mest skalbara sätten för API-värdtjänster.

För att anpassade API:er ska fungera med logikappens arbetsflöde kan ditt API tillhandahålla åtgärder som utför specifika uppgifter i arbetsflöden. Ditt API kan också fungera som en utlösare som startar en arbetsflödeskörning när nya data eller en händelse uppfyller ett angivet villkor. Det här avsnittet beskriver vanliga mönster som du kan följa för att skapa åtgärder och utlösare i ditt API, baserat på det beteende som du vill att API:et ska tillhandahålla.

Du kan vara värd för dina API:er på Azure App Service, ett PaaS-erbjudande (platform-as-a-service) som ger mycket skalbar och enkel API-värd.

Hur skiljer sig anpassade API:er från anpassade anslutningsappar?

Anpassade API:er och anpassade anslutningsappar är webb-API:er som använder REST för anslutningsbara gränssnitt, Swagger-metadataformat för dokumentation och JSON som datautbytesformat. Och eftersom dessa API:er och anslutningsappar är REST-API:er som kommunicerar via HTTP-slutpunkter kan du använda valfritt språk, till exempel .NET, Java, Python eller Node.js, för att skapa anpassade API:er och anslutningsappar.

Med anpassade API:er kan du anropa API:er som inte är anslutningsappar och tillhandahålla slutpunkter som du kan anropa med HTTP + Swagger, Azure API Management eller App Services. Anpassade anslutningsappar fungerar som anpassade API:er men har även följande attribut:

• Registrerad som Logic Apps-Anslut eller resurser i Azure.
• Visas med ikoner tillsammans med Microsoft-hanterade anslutningsappar i Logic Apps Designer.
• Endast tillgängligt för anslutningsappens författare och logikappresursanvändare som har samma Microsoft Entra-klientorganisation och Azure-prenumeration i den region där logikapparna distribueras.

Du kan också nominera registrerade anslutningsappar för Microsoft-certifiering. Den här processen verifierar att registrerade anslutningsappar uppfyller kriterierna för offentligt bruk och gör dessa anslutningsappar tillgängliga för användare i Power Automate och Microsoft Power Apps.

Mer information finns i följande dokumentation:

• Anpassade anslutningsprogram – en översikt
• Skapa anpassade anslutningsappar från webb-API:er
• Registrera anpassade anslutningsappar i Azure Logic Apps

Användbara verktyg

Ett anpassat API fungerar bäst med logikappar när API:et även har ett Swagger-dokument som beskriver API:ets åtgärder och parametrar. Många bibliotek, till exempel Swashbuckle, kan automatiskt generera Swagger-filen åt dig. Om du vill kommentera Swagger-filen för visningsnamn, egenskapstyper och så vidare kan du också använda TRex så att Swagger-filen fungerar bra med logikappar.

Åtgärdsmönster

För att logikappar ska kunna utföra uppgifter bör ditt anpassade API tillhandahålla åtgärder. Varje åtgärd i API:et mappar till en åtgärd. En grundläggande åtgärd är en kontrollant som accepterar HTTP-begäranden och returnerar HTTP-svar. Ett arbetsflöde skickar till exempel en HTTP-begäran till webbappen eller API-appen. Appen returnerar sedan ett HTTP-svar, tillsammans med innehåll som arbetsflödet kan bearbeta.

För en standardåtgärd kan du skriva en HTTP-begärandemetod i ditt API och beskriva den metoden i en Swagger-fil. Du kan sedan anropa ditt API direkt med en HTTP-åtgärd eller en HTTP + Swagger-åtgärd . Som standard måste svar returneras inom tidsgränsen för begäran.

Om du vill att ett arbetsflöde ska vänta medan API:et har slutfört uppgifter som körs längre kan DITT API följa det asynkrona avsökningsmönstret eller det asynkrona webhookmönstret som beskrivs i det här avsnittet. För en analogi som hjälper dig att visualisera dessa mönsters olika beteenden, föreställ dig processen för att beställa en anpassad tårta från ett bageri. Avsökningsmönstret speglar beteendet där du ringer bageriet var 20:e minut för att kontrollera om kakan är klar. Webhookens mönster speglar beteendet där bageriet ber dig om ditt telefonnummer så att de kan ringa dig när kakan är klar.

Utföra långvariga uppgifter med mönstret för avsökningsåtgärden

Om du vill att API:et ska utföra uppgifter som kan köras längre än tidsgränsen för begäran kan du använda det asynkrona avsökningsmönstret. Det här mönstret har ditt API fungerar i en separat tråd, men behålla en aktiv anslutning till Azure Logic Apps-motorn. På så sätt överskrider inte arbetsflödet tidsgränsen eller fortsätter med nästa steg i arbetsflödet innan API:et har slutförts.

Här är det allmänna mönstret:

1. Kontrollera att motorn vet att ditt API accepterade begäran och började fungera.
2. När motorn gör efterföljande begäranden om jobbstatus meddelar du motorn när api:et har slutfört uppgiften.
3. Returnera relevanta data till motorn så att arbetsflödet kan fortsätta.

Tillämpa nu den tidigare bagerianalogin på avsökningsmönstret och föreställ dig att du kallar ett bageri och beställer en anpassad tårta för leverans. Processen för att göra kakan tar tid, och du vill inte vänta på telefonen medan bageriet arbetar på kakan. Bageriet bekräftar din beställning och får dig att ringa var 20:e minut för tårtans status. Efter 20 minuter ringer du bageriet, men de säger att din tårta inte är klar och att du bör ringa om ytterligare 20 minuter. Denna fram och tillbaka-process fortsätter tills du ringer, och bageriet berättar att din beställning är klar och levererar din tårta.

Så låt oss mappa det här avsökningsmönstret tillbaka. Bageriet representerar ditt anpassade API, medan du, tårtkund, representerar Azure Logic Apps-motorn. När motorn anropar ditt API med en begäran bekräftar DITT API begäran och svarar med tidsintervallet när motorn kan kontrollera jobbstatusen. Motorn fortsätter att kontrollera jobbstatusen tills ditt API svarar att jobbet är klart och returnerar data till logikappen, som sedan fortsätter arbetsflödet.

Här följer de specifika steg som api:et ska följa, som beskrivs ur API:ets perspektiv:

1. När ditt API får en HTTP-begäran om att börja arbeta returnerar du omedelbart ett HTTP-svar 202 ACCEPTED med location rubriken som beskrivs senare i det här steget. Det här svaret låter Azure Logic Apps-motorn veta att ditt API fick begäran, accepterade nyttolasten för begäran (dataindata) och nu bearbetar.

   Svaret 202 ACCEPTED bör innehålla följande rubriker:

   • Obligatoriskt: Ett location huvud som anger den absoluta sökvägen till en URL där Azure Logic Apps-motorn kan kontrollera api:ets jobbstatus

   • Valfritt: Ett retry-after sidhuvud som anger hur många sekunder motorn ska vänta innan den kontrollerar location att URL:en har jobbstatus.

     Som standard avsöker location motorn URL:en efter en sekund. Om du vill ange ett annat intervall tar du med retry-after rubriken och antalet sekunder till nästa avsökning.

2. När den angivna tiden har passerat avsöker location Azure Logic Apps-motorn URL:en för att kontrollera jobbstatusen. Api:et bör utföra dessa kontroller och returnera följande svar:

   • Om jobbet är klart returnerar du ett HTTP-svar 200 OK tillsammans med svarsnyttolasten (indata för nästa steg).

   • Om jobbet fortfarande bearbetas returnerar du ett annat HTTP-svar 202 ACCEPTED , men med samma rubriker som det ursprungliga svaret.

När ditt API följer det här mönstret behöver du inte göra något i arbetsflödesdefinitionen för att fortsätta kontrollera jobbstatusen. När motorn får ett HTTP-svar 202 ACCEPTED och ett giltigt location huvud respekterar motorn det asynkrona mönstret och kontrollerar location huvudet tills DITT API returnerar ett icke-202-svar.

Utföra långvariga uppgifter med webhook-åtgärdsmönstret

Alternativt kan du använda webhook-mönstret för tidskrävande uppgifter och asynkron bearbetning. Det här mönstret pausar arbetsflödet och väntar på att ett "återanrop" från API:et ska slutföra bearbetningen innan arbetsflödet fortsätter. Det här återanropet är ett HTTP POST som skickar ett meddelande till en URL när en händelse inträffar.

Tillämpa nu den tidigare bagerianalogin på webhooksmönstret och föreställ dig att du kallar ett bageri och beställer en anpassad tårta för leverans. Processen för att göra kakan tar tid, och du vill inte vänta på telefonen medan bageriet arbetar på kakan. Bageriet bekräftar din beställning, men den här gången ger du dem ditt telefonnummer så att de kan ringa dig när kakan är klar. Den här gången berättar bageriet när din beställning är klar och levererar din tårta.

När vi mappar tillbaka det här webhooken representerar bageriet ditt anpassade API, medan du, tårtkund, representerar Azure Logic Apps-motorn. Motorn anropar ditt API med en begäran och innehåller en URL för återanrop. När jobbet är klart använder DITT API URL:en för att meddela motorn och returnera data till logikappen, som sedan fortsätter arbetsflödet.

För det här mönstret konfigurerar du två slutpunkter på kontrollanten: subscribe och unsubscribe

• subscribe slutpunkt: När körningen når api:ets åtgärd i arbetsflödet anropar subscribe Azure Logic Apps-motorn slutpunkten. Det här steget gör att arbetsflödet skapar en motringnings-URL som ditt API lagrar och sedan väntar på återanropet från API:et när arbetet är klart. Ditt API anropar sedan tillbaka med en HTTP POST till URL:en och skickar eventuellt returnerat innehåll och rubriker som indata till logikappen.

• unsubscribe slutpunkt: Om arbetsflödeskörningen avbryts anropar unsubscribe Azure Logic Apps-motorn slutpunkten. Ditt API kan sedan avregistrera motringnings-URL:en och stoppa alla processer efter behov.

Arbetsflödesdesignern stöder för närvarande inte identifiering av webhook-slutpunkter via Swagger. Så för det här mönstret måste du lägga till en Webhook-åtgärd och ange URL, rubriker och brödtext för din begäran. Se även Arbetsflödesåtgärder och utlösare. Ett exempel på webhookmönster finns i det här webhook-utlösarexemplet i GitHub.

Här följer några andra tips och kommentarer:

• Om du vill skicka in motringnings-URL:en kan du använda arbetsflödesfunktionen @listCallbackUrl() i något av de föregående fälten efter behov.

• Om du äger både logikappresursen och prenumerationstjänsten behöver du inte anropa unsubscribe slutpunkten när motringnings-URL:en har anropats. Annars måste Azure Logic Apps-körningen unsubscribe anropa slutpunkten för att signalera att inga fler anrop förväntas och tillåta resursrensning på serversidan.

Utlösarmönster

Ditt anpassade API kan fungera som en utlösare som startar en arbetsflödeskörning när nya data eller en händelse uppfyller ett angivet villkor. Den här utlösaren kan antingen kontrollera regelbundet eller vänta och lyssna efter nya data eller händelser på tjänstslutpunkten. Om nya data eller en händelse uppfyller det angivna villkoret utlöses utlösaren och startar logikappen, som lyssnar på utlösaren. Om du vill starta logikappar på det här sättet kan ditt API följa avsökningsutlösaren eller webhookens utlösarmönster. Dessa mönster liknar deras motsvarigheter för avsökningsåtgärder och webhook-åtgärder. Läs också mer om användningsmätning för utlösare.

Sök efter nya data eller händelser regelbundet med avsökningsutlösarmönstret

En avsökningsutlösare fungerar ungefär som avsökningsåtgärden som tidigare beskrivits i det här avsnittet. Azure Logic Apps-motorn anropar regelbundet och kontrollerar utlösarslutpunkten efter nya data eller händelser. Om motorn hittar nya data eller en händelse som uppfyller ditt angivna villkor utlöses utlösaren. Sedan skapar motorn en arbetsflödesinstans som bearbetar data som indata.

Här är specifika steg för en avsökningsutlösare som beskrivs ur API:ets perspektiv:

Om du till exempel regelbundet vill kontrollera om det finns nya filer i tjänsten kan du skapa en avsökningsutlösare som har följande beteenden:

Vänta och lyssna efter nya data eller händelser med webhook-utlösarmönstret

En webhook-utlösare är en push-utlösare som väntar och lyssnar efter nya data eller händelser på tjänstslutpunkten. Om nya data eller en händelse uppfyller det angivna villkoret utlöses utlösaren och skapar en arbetsflödesinstans som sedan bearbetar data som indata. Webhook-utlösare fungerar ungefär som de webhook-åtgärder som beskrivs tidigare i det här avsnittet och konfigureras med subscribe och unsubscribe slutpunkter.

• subscribe slutpunkt: När du lägger till och sparar en webhook-utlösare i logikappen anropar subscribe Azure Logic Apps-motorn slutpunkten. Det här steget gör att arbetsflödet skapar en motringnings-URL som ditt API lagrar. När det finns nya data eller en händelse som uppfyller det angivna villkoret anropar ditt API tillbaka med en HTTP POST till URL:en. Innehållsnyttolasten och rubrikerna skickas som indata till logikappen.

• unsubscribe slutpunkt: Om webhookens utlösare eller hela logikappresursen tas bort anropar unsubscribe Azure Logic Apps-motorn slutpunkten. Ditt API kan sedan avregistrera motringnings-URL:en och stoppa alla processer efter behov.

Arbetsflödesdesignern stöder för närvarande inte identifiering av webhook-slutpunkter via Swagger. Så för det här mönstret måste du lägga till en Webhook-utlösare och ange URL, rubriker och brödtext för din begäran. Se även HTTPWebhook-utlösare. Ett exempel på webhookmönster finns i det här webhook-utlösarstyrenhetsexemplet i GitHub.

Här följer några andra tips och kommentarer:

• Om du vill skicka in motringnings-URL:en kan du använda arbetsflödesfunktionen @listCallbackUrl() i något av de föregående fälten efter behov.

• För att förhindra bearbetning av samma data flera gånger bör utlösaren rensa data som redan har lästs och skickats till logikappen.

• Om du äger både logikappresursen och prenumerationstjänsten behöver du inte anropa unsubscribe slutpunkten när motringnings-URL:en har anropats. Annars måste Logic Apps-körningen unsubscribe anropa slutpunkten för att signalera att inga fler anrop förväntas och för att tillåta resursrensning på serversidan.

Förbättra säkerheten för anrop till dina API:er från logikappar

När du har skapat dina anpassade API:er konfigurerar du autentisering för dina API:er så att du kan anropa dem säkert från logikappar. Lär dig hur du förbättrar säkerheten för anrop till anpassade API:er från logikappar.

Distribuera och anropa dina API:er

När du har konfigurerat autentisering konfigurerar du distributionen för dina API:er. Lär dig hur du distribuerar och anropar anpassade API:er från logikappar.

Publicera anpassade API:er till Azure

Om du vill göra dina anpassade API:er tillgängliga för andra Azure Logic Apps-användare måste du lägga till säkerhet och registrera dem som Azure Logic Apps-anslutningsappar. Mer information finns i Översikt över anpassade anslutningsappar.

För att göra dina anpassade API:er tillgängliga för alla användare i Logic Apps, Power Automate och Microsoft Power Apps måste du lägga till säkerhet, registrera dina API:er som Azure Logic Apps-anslutningsappar och nominera dina anslutningsappar för Microsoft Azure Certified-programmet.

Få support

• Kontakta om du vill ha specifik hjälp med anpassade API:er customapishelp@microsoft.com.

• Frågor finns på microsofts Q&A-frågesida för Azure Logic Apps.

Nästa steg

• Hantera fel och undantag
• Anropa, utlösa eller kapsla logikappar med HTTP-slutpunkter
• Användningsmätning för åtgärder och utlösare