Aangepaste API's maken die u kunt aanroepen vanuit Azure Logic Apps

Van toepassing op: Azure Logic Apps (verbruik)

Hoewel Azure Logic Apps honderden connectors biedt die u kunt gebruiken in werkstromen voor logische apps, kunt u API's, systemen en services aanroepen die niet beschikbaar zijn als connectors. U kunt uw eigen API's maken die acties en triggers bieden voor gebruik in werkstromen. Hier volgen andere redenen waarom u mogelijk uw eigen API's wilt maken die u kunt aanroepen vanuit werkstromen:

• Breid uw huidige systeemintegratie- en gegevensintegratiewerkstromen uit.
• Klanten helpen uw service te gebruiken om professionele of persoonlijke taken te beheren.
• Breid het bereik, de detectie en het gebruik voor uw service uit.

In principe zijn connectors web-API's die GEBRUIKMAKEN van REST voor pluggable interfaces, Swagger-metagegevensindeling voor documentatie en JSON als hun indeling voor gegevensuitwisseling. Omdat connectors REST API's zijn die communiceren via HTTP-eindpunten, kunt u elke taal gebruiken om connectors te bouwen, zoals .NET, Java, Python of Node.js. U kunt uw API's ook hosten op Azure-app Service, een PaaS-aanbieding (Platform-as-a-Service) die een van de beste, eenvoudigste en meest schaalbare manieren biedt voor API-hosting.

Om aangepaste API's te laten werken met de werkstroom van logische apps, kan uw API acties bieden waarmee specifieke taken in werkstromen worden uitgevoerd. Uw API kan ook fungeren als een trigger waarmee een werkstroom wordt gestart wanneer nieuwe gegevens of een gebeurtenis aan een opgegeven voorwaarde voldoet. In dit onderwerp worden veelvoorkomende patronen beschreven die u kunt volgen voor het bouwen van acties en triggers in uw API, op basis van het gedrag dat uw API moet bieden.

U kunt uw API's hosten op Azure-app Service, een PaaS-aanbieding (Platform-as-a-Service) die zeer schaalbare, eenvoudige API-hosting biedt.

Tip

Hoewel u uw API's als web-apps kunt implementeren, kunt u overwegen om uw API's als API-apps te implementeren, waardoor uw taak gemakkelijker kan worden wanneer u API's in de cloud en on-premises bouwt, host en verbruikt. U hoeft geen code in uw API's te wijzigen. Implementeer uw code alleen in een API-app. Leer bijvoorbeeld hoe u API-apps bouwt die zijn gemaakt met deze talen:

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

Hoe verschillen aangepaste API's van aangepaste connectors?

Aangepaste API's en aangepaste connectors zijn web-API's die GEBRUIKMAKEN van REST voor pluggable interfaces, Swagger-metagegevensindeling voor documentatie en JSON als hun indeling voor gegevensuitwisseling. En omdat deze API's en connectors REST API's zijn die communiceren via HTTP-eindpunten, kunt u elke taal gebruiken, zoals .NET, Java, Python of Node.js, voor het bouwen van aangepaste API's en connectors.

Met aangepaste API's kunt u API's aanroepen die geen connectors zijn en eindpunten bieden die u kunt aanroepen met HTTP + Swagger, Azure API Management of App Services. Aangepaste connectors werken als aangepaste API's, maar hebben ook de volgende kenmerken:

• Geregistreerd als Logic Apps Verbinding maken or resources in Azure.
• Worden weergegeven met pictogrammen naast door Microsoft beheerde connectors in logic apps Designer.
• Alleen beschikbaar voor de auteurs van connectors en resourcegebruikers van logische apps die dezelfde Microsoft Entra-tenant en hetzelfde Azure-abonnement hebben in de regio waar de logische apps worden geïmplementeerd.

U kunt ook geregistreerde connectors nomineren voor Microsoft-certificering. Dit proces controleert of geregistreerde connectors voldoen aan de criteria voor openbaar gebruik en maakt deze connectors beschikbaar voor gebruikers in Power Automate en Microsoft Power Apps.

Raadpleeg de volgende documentatie voor meer informatie:

• Overzicht van aangepaste connectors
• Aangepaste connectors maken op basis van web-API's
• Aangepaste connectors registreren in Azure Logic Apps

Handige hulpprogramma's

Een aangepaste API werkt het beste met logische apps wanneer de API ook een Swagger-document heeft dat de bewerkingen en parameters van de API beschrijft. Veel bibliotheken, zoals Swashbuckle, kunnen automatisch het Swagger-bestand voor u genereren. Als u aantekeningen wilt maken voor het Swagger-bestand voor weergavenamen, eigenschapstypen, enzovoort, kunt u ook TRex gebruiken, zodat uw Swagger-bestand goed werkt met logische apps.

Actiepatronen

Voor het uitvoeren van taken door logische apps moet uw aangepaste API acties bieden. Elke bewerking in uw API wordt toegewezen aan een actie. Een basisactie is een controller die HTTP-aanvragen accepteert en HTTP-antwoorden retourneert. Een werkstroom verzendt bijvoorbeeld een HTTP-aanvraag naar uw web-app of API-app. Uw app retourneert vervolgens een HTTP-antwoord, samen met inhoud die door de werkstroom kan worden verwerkt.

Voor een standaardactie kunt u een HTTP-aanvraagmethode schrijven in uw API en die methode beschrijven in een Swagger-bestand. Vervolgens kunt u uw API rechtstreeks aanroepen met een HTTP-actie of een HTTP + Swagger-actie . Antwoorden moeten standaard worden geretourneerd binnen de time-outlimiet van de aanvraag.

Als u een werkstroom wilt laten wachten terwijl uw API langer lopende taken voltooit, kan uw API het asynchrone polling-patroon of het asynchrone webhookpatroon volgen dat in dit onderwerp wordt beschreven. Voor een analogie die u helpt bij het visualiseren van het verschillende gedrag van deze patronen, stelt u zich het proces voor het bestellen van een aangepaste taart van een bakkerij voor. Het polling-patroon weerspiegelt het gedrag waar u de bakkerij elke 20 minuten aanroept om te controleren of de taart gereed is. Het webhookpatroon weerspiegelt het gedrag waar de bakkerij u vraagt om uw telefoonnummer, zodat ze u kunnen bellen wanneer de taart klaar is.

Langlopende taken uitvoeren met het polling-actiepatroon

Als u wilt dat uw API taken uitvoert die langer kunnen worden uitgevoerd dan de time-outlimiet van de aanvraag, kunt u het asynchrone polling-patroon gebruiken. Dit patroon werkt uw API in een afzonderlijke thread, maar houdt een actieve verbinding met de Azure Logic Apps-engine. Op die manier treedt er geen time-out op of gaat de werkstroom niet verder met de volgende stap in de werkstroom voordat uw API klaar is.

Dit is het algemene patroon:

1. Zorg ervoor dat de engine weet dat uw API de aanvraag heeft geaccepteerd en aan de slag is gegaan.
2. Wanneer de engine volgende aanvragen voor taakstatus indient, laat de engine weten wanneer de API de taak heeft voltooid.
3. Relevante gegevens retourneren aan de engine, zodat de werkstroom kan worden voortgezet.

Pas nu de vorige bakkerij-analogie toe op het pollingpatroon en stel dat u een bakkerij belt en een aangepaste taart bestelt voor levering. Het proces voor het maken van de taart kost tijd en u wilt niet op de telefoon wachten terwijl de bakkerij op de taart werkt. De bakkerij bevestigt uw bestelling en laat u elke 20 minuten bellen voor de status van de taart. Na 20 minuten bel je de bakkerij, maar ze vertellen je dat je taart niet klaar is en dat je over 20 minuten moet bellen. Dit back-and-forth proces gaat door totdat je belt, en de bakkerij vertelt je dat je bestelling klaar is en je taart aflevert.

Laten we dit polling-patroon dus weer toewijzen. De bakkerij vertegenwoordigt uw aangepaste API, terwijl u, de cakeklant, de Azure Logic Apps-engine vertegenwoordigt. Wanneer de engine uw API aanroept met een aanvraag, bevestigt uw API de aanvraag en reageert deze met het tijdsinterval wanneer de engine de taakstatus kan controleren. De engine blijft de taakstatus controleren totdat uw API reageert dat de taak is voltooid en gegevens retourneert naar uw logische app, waarna de werkstroom wordt voortgezet.

Hier volgen de specifieke stappen die uw API moet volgen, zoals beschreven vanuit het perspectief van de API:

1. Wanneer uw API een HTTP-aanvraag ontvangt om aan de slag te gaan, retourneert u onmiddellijk een HTTP-antwoord 202 ACCEPTED met de location header die verderop in deze stap wordt beschreven. Met dit antwoord weet de Azure Logic Apps-engine dat uw API de aanvraag heeft ontvangen, de nettolading van de aanvraag (gegevensinvoer) heeft geaccepteerd en nu wordt verwerkt.

   Het 202 ACCEPTED antwoord moet de volgende headers bevatten:

   • Vereist: Een location header die het absolute pad naar een URL aangeeft waar de Azure Logic Apps-engine de taakstatus van uw API kan controleren

   • Optioneel: Een retry-after header die het aantal seconden aangeeft dat de engine moet wachten voordat de URL voor de location taakstatus wordt gecontroleerd.

     De engine pollt standaard de location URL na één seconde. Als u een ander interval wilt opgeven, neemt u de retry-after koptekst en het aantal seconden op tot de volgende poll.

2. Nadat de opgegeven tijd is verstreken, controleert de Azure Logic Apps-engine de URL om de location taakstatus te controleren. Uw API moet deze controles uitvoeren en deze antwoorden retourneren:

   • Als de taak is voltooid, retourneert u een HTTP-antwoord 200 OK , samen met de nettolading van het antwoord (invoer voor de volgende stap).

   • Als de taak nog steeds wordt verwerkt, retourneert u een ander HTTP-antwoord 202 ACCEPTED , maar met dezelfde headers als het oorspronkelijke antwoord.

Wanneer uw API dit patroon volgt, hoeft u niets te doen in de werkstroomdefinitie om de taakstatus te blijven controleren. Wanneer de engine een HTTP-antwoord 202 ACCEPTED en een geldige location header ontvangt, respecteert de engine het asynchrone patroon en controleert de location header totdat uw API een niet-202-antwoord retourneert.

Tip

Bekijk voor een voorbeeld van een asynchroon patroon dit asynchrone controllerantwoordvoorbeeld in GitHub.

Langlopende taken uitvoeren met het webhookactiepatroon

Als alternatief kunt u het webhookpatroon gebruiken voor langlopende taken en asynchrone verwerking. Met dit patroon wordt de werkstroom onderbroken en wordt gewacht op een callback van uw API om de verwerking te voltooien voordat de werkstroom wordt voortgezet. Deze callback is een HTTP POST die een bericht naar een URL verzendt wanneer een gebeurtenis plaatsvindt.

Pas nu de vorige bakkerij-analogie toe op het webhookpatroon en stel dat u een bakkerij belt en een aangepaste taart bestelt voor levering. Het proces voor het maken van de taart kost tijd en u wilt niet op de telefoon wachten terwijl de bakkerij op de taart werkt. De bakkerij bevestigt uw bestelling, maar deze keer geeft u ze uw telefoonnummer zodat ze u kunnen bellen wanneer de taart klaar is. Deze keer vertelt de bakkerij je wanneer je bestelling klaar is en je taart aflevert.

Wanneer we dit webhookpatroon weer toewijzen, vertegenwoordigt de bakkerij uw aangepaste API, terwijl u, de cakeklant, de Azure Logic Apps-engine vertegenwoordigt. De engine roept uw API aan met een aanvraag en bevat een callback-URL. Wanneer de taak is voltooid, gebruikt uw API de URL om de engine op de hoogte te stellen en gegevens terug te sturen naar uw logische app, waarna de werkstroom wordt voortgezet.

Stel voor dit patroon twee eindpunten in op uw controller: subscribe en unsubscribe

• subscribe eindpunt: wanneer de uitvoering de actie van uw API in de werkstroom bereikt, roept de Azure Logic Apps-engine het subscribe eindpunt aan. Deze stap zorgt ervoor dat de werkstroom een callback-URL maakt die door uw API wordt opgeslagen en vervolgens wacht op de callback van uw API wanneer het werk is voltooid. Uw API roept vervolgens terug met een HTTP POST naar de URL en geeft alle geretourneerde inhoud en headers door als invoer aan de logische app.

• unsubscribe eindpunt: als de uitvoering van de werkstroom is geannuleerd, roept de Azure Logic Apps-engine het unsubscribe eindpunt aan. Uw API kan vervolgens de registratie van de callback-URL ongedaan maken en alle processen indien nodig stoppen.

Momenteel biedt de werkstroomontwerper geen ondersteuning voor het detecteren van webhook-eindpunten via Swagger. Voor dit patroon moet u dus een webhookactie toevoegen en de URL, headers en hoofdtekst voor uw aanvraag opgeven. Zie ook Werkstroomacties en triggers. Bekijk dit voorbeeld van een webhooktrigger in GitHub voor een voorbeeld van een webhookpatroon.

Hier volgen enkele andere tips en notities:

• Als u de callback-URL wilt doorgeven, kunt u indien nodig de @listCallbackUrl() werkstroomfunctie in een van de vorige velden gebruiken.

• Als u zowel de resource van de logische app als de geabonneerde service bezit, hoeft u het unsubscribe eindpunt niet aan te roepen nadat de callback-URL is aangeroepen. Anders moet de Azure Logic Apps-runtime het unsubscribe eindpunt aanroepen om aan te geven dat er geen aanroepen meer worden verwacht en om het opschonen van resources aan de serverzijde toe te staan.

Triggerpatronen

Uw aangepaste API kan fungeren als een trigger waarmee een werkstroom wordt gestart wanneer nieuwe gegevens of een gebeurtenis aan een opgegeven voorwaarde voldoet. Met deze trigger kunt u regelmatig controleren of wachten en luisteren naar nieuwe gegevens of gebeurtenissen op uw service-eindpunt. Als nieuwe gegevens of gebeurtenissen voldoen aan de opgegeven voorwaarde, wordt de trigger geactiveerd en wordt de logische app gestart, die naar die trigger luistert. Als u op deze manier logische apps wilt starten, kan uw API de polling-trigger of het patroon van de webhooktrigger volgen. Deze patronen zijn vergelijkbaar met hun tegenhangers voor pollingacties en webhookacties. Lees ook meer over gebruiksmeter voor triggers.

Regelmatig controleren op nieuwe gegevens of gebeurtenissen met het polling-triggerpatroon

Een pollingtrigger werkt net als de polling-actie die eerder in dit onderwerp is beschreven. De Azure Logic Apps-engine roept periodiek het triggereindpunt aan en controleert het triggereindpunt op nieuwe gegevens of gebeurtenissen. Als de engine nieuwe gegevens of een gebeurtenis vindt die voldoet aan uw opgegeven voorwaarde, wordt de trigger geactiveerd. Vervolgens maakt de engine een werkstroomexemplaren die de gegevens verwerkt als invoer.

Notitie

Elke polling-aanvraag telt als een actie-uitvoering, zelfs wanneer er geen werkstroomexemplaren worden gemaakt. Om te voorkomen dat dezelfde gegevens meerdere keren worden verwerkt, moet uw trigger gegevens opschonen die al zijn gelezen en doorgegeven aan de logische app.

Hier volgen specifieke stappen voor een polling-trigger, beschreven vanuit het perspectief van de API:

Hebt u nieuwe gegevens of gebeurtenis gevonden?	API-reactie
Gevonden	Retourneer een HTTP-status 200 OK met de nettolading van het antwoord (invoer voor de volgende stap). Met dit antwoord wordt een werkstroomexemplaren gemaakt en wordt de werkstroom gestart.
Niet gevonden	Retourneer een HTTP-status 202 ACCEPTED met een location header en een retry-after header. Voor triggers moet de location header ook een triggerState queryparameter bevatten. Dit is meestal een tijdstempel. Uw API kan deze id gebruiken om bij te houden wanneer de werkstroom de laatste keer is geactiveerd.

Als u bijvoorbeeld regelmatig uw service wilt controleren op nieuwe bestanden, kunt u een poll-trigger bouwen die dit gedrag heeft:

Aanvraag omvat triggerState?	API-reactie
Nee	Retourneer een HTTP-status 202 ACCEPTED plus een location header die triggerState is ingesteld op de huidige tijd en het retry-after interval op 15 seconden.
Ja	Controleer uw service op bestanden die zijn toegevoegd na de DateTime voor triggerState.

Aantal gevonden bestanden	API-reactie
Eén bestand	Retourneer een HTTP-status 200 OK en de nettolading van de inhoud, werk deze bij triggerState naar het DateTime geretourneerde bestand en stel retry-after het interval in op 15 seconden.
Meerdere bestanden	Retourneer één bestand tegelijk en een HTTP-status 200 OK , werk triggerStatehet bij en stel het retry-after interval in op 0 seconden. Met deze stappen weet de engine dat er meer gegevens beschikbaar zijn en dat de engine onmiddellijk de gegevens van de URL in de location header moet aanvragen.
Geen bestanden	Retourneer een HTTP-status 202 ACCEPTED , wijzig triggerStatedeze niet en stel het retry-after interval in op 15 seconden.

Tip

Bekijk dit voorbeeld van een polltriggercontroller in GitHub voor een voorbeeld van een poll-triggertriggerpatroon.

Wacht en luister naar nieuwe gegevens of gebeurtenissen met het triggerpatroon van de webhook

Een webhooktrigger is een push-trigger die wacht en luistert naar nieuwe gegevens of gebeurtenissen op uw service-eindpunt. Als nieuwe gegevens of gebeurtenissen voldoen aan de opgegeven voorwaarde, wordt de trigger geactiveerd en wordt een werkstroomexemplaren gemaakt, die vervolgens de gegevens verwerkt als invoer. Webhooktriggers werken net als de webhookacties die eerder in dit onderwerp zijn beschreven en worden ingesteld met subscribe en unsubscribe eindpunten.

• subscribe eindpunt: Wanneer u een webhooktrigger toevoegt en opslaat in uw logische app, roept de Azure Logic Apps-engine het subscribe eindpunt aan. Deze stap zorgt ervoor dat de werkstroom een callback-URL maakt die door uw API wordt opgeslagen. Wanneer er nieuwe gegevens of een gebeurtenis zijn die voldoet aan de opgegeven voorwaarde, roept uw API een HTTP POST aan met een HTTP POST naar de URL. De nettolading en headers van de inhoud worden doorgegeven als invoer voor de logische app.

• unsubscribe eindpunt: Als de webhooktrigger of de hele resource van de logische app wordt verwijderd, roept de Azure Logic Apps-engine het eindpunt aan unsubscribe . Uw API kan vervolgens de registratie van de callback-URL ongedaan maken en alle processen indien nodig stoppen.

Momenteel biedt de werkstroomontwerper geen ondersteuning voor het detecteren van webhook-eindpunten via Swagger. Voor dit patroon moet u dus een webhooktrigger toevoegen en de URL, headers en hoofdtekst voor uw aanvraag opgeven. Zie ook de HTTPWebhook-trigger. Bekijk dit voorbeeld van een webhooktriggercontroller in GitHub voor een voorbeeld van een webhookpatroon.

Hier volgen enkele andere tips en notities:

• Als u de callback-URL wilt doorgeven, kunt u indien nodig de @listCallbackUrl() werkstroomfunctie in een van de vorige velden gebruiken.

• Om te voorkomen dat dezelfde gegevens meerdere keren worden verwerkt, moet uw trigger gegevens opschonen die al zijn gelezen en doorgegeven aan de logische app.

• Als u zowel de resource van de logische app als de geabonneerde service bezit, hoeft u het unsubscribe eindpunt niet aan te roepen nadat de callback-URL is aangeroepen. Anders moet de Logic Apps-runtime het unsubscribe eindpunt aanroepen om aan te geven dat er geen aanroepen meer worden verwacht en dat resourceopruiming aan de serverzijde is toegestaan.

De beveiliging verbeteren voor aanroepen naar uw API's vanuit logische apps

Nadat u uw aangepaste API's hebt gemaakt, stelt u verificatie in voor uw API's, zodat u deze veilig kunt aanroepen vanuit logische apps. Meer informatie over het verbeteren van de beveiliging voor aanroepen naar aangepaste API's vanuit logische apps.

Uw API's implementeren en aanroepen

Nadat u verificatie hebt ingesteld, stelt u de implementatie voor uw API's in. Meer informatie over het implementeren en aanroepen van aangepaste API's vanuit logische apps.

Aangepaste API's publiceren naar Azure

Als u uw aangepaste API's beschikbaar wilt maken voor andere Azure Logic Apps-gebruikers, moet u beveiliging toevoegen en deze registreren als Azure Logic Apps-connectors. Zie voor meer informatie het Overzicht van aangepaste connectors.

Als u uw aangepaste API's beschikbaar wilt maken voor alle gebruikers in Logic Apps, Power Automate en Microsoft Power Apps, moet u beveiliging toevoegen, uw API's registreren als Azure Logic Apps-connectors en uw connectors nomineren voor het Microsoft Azure Certified-programma.

Support krijgen

• Voor specifieke hulp bij aangepaste API's neemt u contact op met customapishelp@microsoft.com.

• Ga naar de microsoft Q&A-vragenpagina voor Azure Logic Apps voor vragen.

Volgende stappen

• Fouten en uitzonderingen verwerken
• Logische apps aanroepen, activeren of nesten met HTTP-eindpunten
• Gebruiksmeter voor acties en triggers