Erstellen benutzerdefinierter APIs, die über Azure Logic Apps aufgerufen werden können

Gilt für: Azure Logic Apps (Verbrauch)

Obwohl Azure Logic Apps Hunderte Connectors bietet, die Sie in Logik-App-Workflows verwenden können, möchten Sie möglicherweise APIs, Systeme und Dienste aufrufen, die nicht als Connectors zur Verfügung stehen. Sie können eigene APIs erstellen, die Aktionen und Trigger zur Verwendung in Workflows bereitstellen. Es gibt noch andere Gründe, warum Sie möglicherweise eigene APIs erstellen möchten, die Sie in Workflows aufrufen können:

• Erweitern Ihrer aktuellen Systemintegrations- und Datenintegrationsworkflows.
• Um Kunden zu helfen, Ihren Dienst zum Verwalten professioneller oder persönlicher Aufgaben zu verwenden.
• Erweitern von Reichweite, Erkennbarkeit und Verwendung Ihres Diensts.

Connectors sind grundsätzlich Web-APIs, die REST-APIs für austauschbare Schnittstellen, Swagger-Metadatenformat für Dokumentation und JSON als Datenaustauschformat verwenden. Da Connectors REST-APIs sind, die über HTTP-Endpunkte kommunizieren, können Sie eine beliebige Sprache wie .NET, Java, Python oder Node.js für die Erstellung von Connectors verwenden. Sie können Ihre APIs auch in Azure App Service hosten, einem „Platform as a Service“-Angebot (PaaS), das eine der besten, einfachsten und skalierbarsten Möglichkeiten zum Hosten von APIs bietet.

Damit benutzerdefinierte APIs mit Logik-App-Workflows funktionieren, kann Ihre API Aktionen bereitstellen, die bestimmte Aufgaben in Workflows ausführen. Ihre API kann auch als Trigger dienen, der eine Workflowausführung startet, wenn neue Daten oder ein Ereignis eine angegebene Bedingung erfüllen. Dieses Thema beschreibt allgemeine Muster, die Sie zum Erstellen von Aktionen und Triggern in Ihrer API befolgen können, basierend auf dem Verhalten, dass Ihre API bieten soll.

Sie können Ihre APIs in Azure App Service hosten, einem PaaS-Angebot (Platform-as-a-Service), das ein einfaches API-Hosting mit hoher Skalierbarkeit ermöglicht.

Wie unterscheiden sich benutzerdefinierte APIs von benutzerdefinierten Connectors?

Benutzerdefinierte APIs und benutzerdefinierte Connectors sind Web-APIs, die REST-APIs für austauschbare Schnittstellen, das Swagger-Metadatenformat für Dokumentation und JSON als Datenaustauschformat verwenden. Da diese APIS und Connectors REST-APIs sind, die über HTTP-Endpunkte kommunizieren, können Sie eine beliebige Sprache wie .NET, Java, Python oder Node.js für die Erstellung benutzerdefinierter APIs und Connectors verwenden.

Mit benutzerdefinierten APIs können Sie APIs aufrufen, die keine Connectors sind, und Endpunkte bereitstellen, die Sie mit HTTP + Swagger, Azure API Management oder App Services aufrufen können. Benutzerdefinierte Connectors funktionieren wie benutzerdefinierte APIs, haben aber auch diese Merkmale:

• Werden als Logic Apps-Connectorressourcen in Azure registriert.
• Werden im Designer für Logic Apps mit Symbolen neben von Microsoft verwalteten Connectors angezeigt.
• Sind nur für die Ersteller der Connectors und Benutzer von Logik-App-Ressourcen verfügbar, die denselben Microsoft Entra-Mandanten und dasselbe Azure-Abonnement in der Region haben, in der die Logik-Apps bereitgestellt werden.

Sie können registrierte Connectors auch für die Microsoft-Zertifizierung vorschlagen. Dieser Prozess überprüft, ob registrierte Connectors die Kriterien für die öffentliche Nutzung erfüllen, und stellt diese Connectors Benutzern in Power Automate und Microsoft Power Apps zur Verfügung.

Weitere Informationen finden Sie in der folgenden Dokumentation:

• Übersicht über benutzerdefinierte Connectors
• Erstellen benutzerdefinierter Connectors aus Web-APIs
• Registrieren benutzerdefinierter Connectors in Azure Logic Apps

Nützliche Tools

Eine benutzerdefinierte API funktioniert am besten mit Logik-Apps, wenn die API auch über ein Swagger-Dokument verfügt, das die API-Vorgänge und -Parameter beschreibt. Viele Bibliotheken wie Swashbuckle können die Swagger-Datei automatisch für Sie generieren. Um die Swagger-Datei für Anzeigenamen, Eigenschaftentypen usw. mit Anmerkungen zu versehen, können Sie auch TRex verwenden, damit Ihre Swagger-Datei gut mit Logik-Apps funktioniert.

Aktionsmuster

Damit Logik-Apps Aufgaben ausführen, sollte Ihre benutzerdefinierte API Aktionen bereitstellen. Jeder Vorgang in Ihrer API wird einer Aktion zugeordnet. Eine einfache Aktion ist ein Controller, der HTTP-Anforderungen akzeptiert und HTTP-Antworten zurückgibt. Beispielsweise sendet ein Workflow eine HTTP-Anforderung an Ihre Web-App oder API-App. Ihre App gibt dann eine HTTP-Antwort zurück, zusammen mit Inhalt, den der Workflow verarbeiten kann.

Für Standardaktionen können Sie eine HTTP-Anforderungsmethode in Ihre API schreiben und diese Methode in einer Swagger-Datei beschreiben. Sie können dann Ihre API direkt mit einer HTTP-Aktion oder einer HTTP + Swagger-Aktion aufrufen. Standardmäßig müssen Antworten innerhalb des Timeoutlimits für die Anforderung zurückgegeben werden.

Damit ein Workflow wartet, während Ihre API zeitaufwändigere Aufgaben abschließt, kann Ihre API dem in diesem Thema beschriebenen asynchronen Abrufmuster oder Webhookmuster folgen. Stellen Sie sich als Analogie, anhand der Sie sich die unterschiedlichen Verhaltensweisen dieser Muster veranschaulichen können, den Prozess der Bestellung eines nach Kundenwünschen gebackenen Kuchens bei einer Bäckerei vor. Das Abrufmuster entspricht dem Verhalten, dass Sie alle 20 Minuten in der Bäckerei nachfragen, ob der Kuchen fertig ist. Das Webhookmuster entspricht dem Verhalten, dass die Bäckerei nach Ihrer Telefonnummer fragt, um Sie anrufen zu können, wenn der Kuchen fertig ist.

Ausführen zeitaufwändiger Aufgaben mit dem Abrufaktionsmuster

Damit Ihre API Aufgaben ausführen kann, deren Ausführungsdauer das Timeoutlimit für die Anforderung überschreiten könnte, können Sie das asynchrone Abrufmuster verwenden. Bei diesem Muster arbeitet Ihre API in einem separaten Thread, behält aber eine aktive Verbindung mit der Azure Logic Apps-Engine bei. So wird kein Timeout für den Workflow wirksam, noch wird mit dem nächsten Schritt im Workflow fortgefahren, bevor die Ausführung Ihrer API abgeschlossen ist.

Das allgemeine Muster sieht so aus:

1. Stellen Sie sicher, dass die Engine weiß, dass Ihre API die Anforderung akzeptiert und die Verarbeitung gestartet hat.
2. Wenn die Engine darauffolgende Anforderungen zum Auftragsstatus stellt, sorgen Sie dafür, dass die Engine informiert wird, wenn Ihre API die Aufgabe abschließt.
3. Lassen Sie relevante Daten an die Engine zurückgeben, sodass der Workflow fortgesetzt werden kann.

Wenden Sie nun die obige Bäckereianalogie auf das Abrufmuster an, und stellen Sie sich vor, dass Sie in einer Bäckerei anrufen und einen Kuchen nach Ihren Wünschen bestellen. Die Herstellung des Kuchens braucht ihre Zeit, und Sie möchten nicht am Telefon warten, während die Bäckerei den Kuchen backt. Die Bäckerei bestätigt Ihre Bestellung, und Sie rufen alle 20 Minuten an, um den Status des Kuchens abzufragen. Nach 20 Minuten rufen Sie in der Bäckerei an, aber sie erfahren, dass der Kuchen noch nicht fertig ist, und Sie nach weiteren 20 Minuten anrufen sollen. Dieses Hin und Her und wird fortgesetzt, bis die Bäckerei Ihnen, als Sie anrufen, mitteilt, dass Ihre Bestellung fertig ist und den Kuchen liefert.

Wir werden nun dieses Abrufmuster zurückverfolgen. Die Bäckerei stellt Ihre benutzerdefinierte API dar, während Sie als Kuchenkäufer die Azure Logic Apps-Engine darstellen. Wenn die Engine eine Anforderung an Ihre API sendet, bestätigt die API die Anforderung und antwortet mit dem Zeitintervall, in dem die Engine den Auftragsstatus abfragen kann. Die Engine prüft immer wieder den Auftragsstatus, bis Ihre API antwortet, dass der Auftrag erledigt ist, und Daten an Ihre Logik-App zurückgibt, die dann den Workflow fortsetzt.

Hier werden die einzelnen Schritte Ihrer API aus API-Sicht beschrieben:

1. Wenn Ihre API eine HTTP-Anforderung zum Starten der Ausführung erhält, wird unverzüglich eine HTTP-202 ACCEPTED-Antwort mit dem location-Header zurückgegeben, der weiter unten in diesem Schritt beschrieben wird. Diese Antwort teilt der Azure Logic Apps-Engine mit, dass Ihre API die Anforderung erhalten hat, die Anforderungsnutzlast (Dateneingabe) akzeptiert hat und sie nun verarbeitet.

   Die 202 ACCEPTED-Antwort sollte diese Header enthalten:

   • Erforderlich: Ein location-Header, der den absoluten Pfad zu einer URL angibt, über die die Azure Logic Apps-Engine den Auftragsstatus Ihrer API überprüfen kann

   • Optional: Ein retry-after-Header, der die Anzahl der Sekunden angibt, für die die Engine vor der Überprüfung des Auftragsstatus über die location-URL warten sollte.

     Standardmäßig ruft das Modul die URL location nach einer Sekunde ab. Schließen Sie zum Angeben eines anderen Zeitintervalls den retry-after-Header und die Anzahl der Sekunden bis zum nächsten Abruf ein.

2. Wenn die angegebene Zeit verstrichen ist, ruft die Azure Logic Apps-Engine die location-URL zum Prüfen des Auftragsstatus auf. Ihre API sollte diese Überprüfungen ausführen und diese Antworten zurückgeben:

   • Wenn der Auftrag abgeschlossen ist, wird eine HTTP-200 OK-Antwort zusammen mit der Antwortnutzlast (Eingabe für den nächsten Schritt) zurückgegeben.

   • Wenn der Auftrag immer noch verarbeitet wird, wird eine weitere HTTP-202 ACCEPTED-Antwort zurückgegeben, aber mit den gleichen Headern wie die ursprüngliche Antwort.

Wenn Ihre API diesem Muster folgt, müssen Sie keine Änderungen in der Workflowdefinition vornehmen, um die Überprüfung des Auftragsstatus fortzusetzen. Wenn die Engine eine HTTP-202 ACCEPTED-Antwort und einen gültigen location-Header erhält, respektiert die Engine das asynchrone Muster und überprüft die location-Header, bis Ihre API eine andere Antwort als 202 zurückgibt.

Ausführen zeitaufwändiger Aufgaben mit dem Webhookaktionsmuster

Als Alternative können Sie die Webhookmuster für zeitaufwändige Aufgaben und asynchrone Verarbeitung verwenden. Bei diesem Muster hält der Workflow an und wartet vor dem Fortsetzen des Workflows auf einen „Rückruf“ von Ihrer API, der den Abschluss der Verarbeitung anfordert. Dieser Rückruf ist ein HTTP POST, der eine Nachricht an eine URL sendet, wenn ein Ereignis eintritt.

Wenden Sie nun die obige Bäckereianalogie auf das Webhookmuster an, und stellen Sie sich vor, dass Sie in einer Bäckerei anrufen und einen Kuchen nach Ihren Wünschen bestellen. Die Herstellung des Kuchens braucht ihre Zeit, und Sie möchten nicht am Telefon warten, während die Bäckerei den Kuchen backt. Die Bäckerei bestätigt Ihre Bestellung, aber diesmal geben Sie Ihre Telefonnummer an, damit Sie angerufen werden können, wenn der Kuchen fertig ist. Dieses Mal informiert die Bäckerei Sie, wenn Ihre Bestellung ausgeführt ist, und liefert den Kuchen.

Beim Rückverfolgen dieses Webhookmusters stellen wir fest, dass die Bäckerei Ihre benutzerdefinierte API darstellt, während Sie als Kuchenkäufer die Azure Logic Apps-Engine darstellen. Die Engine ruft Ihre API mit einer Anforderung auf und bezieht einen URL-„Rückruf“ ein. Wenn der Auftrag abgeschlossen ist, benachrichtigt Ihre API die Engine über die URL und gibt Daten an Ihre Logik-App zurück, die dann den Workflow fortsetzt.

Richten Sie für dieses Muster zwei Endpunkte auf dem Controller ein: subscribe undunsubscribe.

• subscribe-Endpunkt: Wenn die Ausführung die Aktion Ihrer API im Workflow erreicht, ruft die Azure Logic Apps-Engine den subscribe-Endpunkt auf. Dieser Schritt bewirkt, dass der Workflow eine Rückruf-URL erstellt, die Ihre API speichert, und dann auf den Rückruf von Ihrer API wartet, wenn die Arbeit abgeschlossen ist. Dann sendet Ihre API wieder einen HTTP POST-Rückruf an die URL und übergibt alle zurückgegebenen Inhalte und Header als Eingabe an die Logik-App.

• unsubscribe-Endpunkt: Wenn der Workflow abgebrochen wird, ruft die Azure Logic Apps-Engine den unsubscribe-Endpunkt auf. Ihre API kann dann die Registrierung der Rückruf-URL aufheben und alle Prozesse nach Bedarf beenden.

Der Workflow-Designer unterstützt derzeit keine Ermittlung von Webhookendpunkten über Swagger. Also müssen Sie für dieses Muster eine Webhookaktion hinzufügen und URL, Header und Text für die Anforderung angeben. Siehe auch Workflow-Aktionen und -Trigger. Ein Beispiel für Webhookmuster finden Sie in diesem Webhooktriggerbeispiel in GitHub.

Hier finden Sie weitere Tipps und Hinweise:

• Um die Rückruf-URL zu übergeben, können Sie in jedem dieser vorherigen Felder nach Bedarf die @listCallbackUrl()-Workflowfunktion verwenden.

• Wenn Sie sowohl die Logik-App-Ressource als auch den abonnierten Dienst besitzen, müssen Sie den unsubscribe-Endpunkt nicht aufrufen, nachdem die Rückruf-URL aufgerufen wurde. Andernfalls muss die Azure Logic Apps-Runtime den unsubscribe-Endpunkt aufrufen, um zu signalisieren, dass keine weiteren Aufrufe mehr erwartet werden, und die Ressourcenbereinigung auf der Serverseite zuzulassen.

Triggermuster

Ihre benutzerdefinierte API kann als Trigger dienen, der eine Workflowausführung startet, wenn neue Daten oder ein Ereignis eine angegebene Bedingung erfüllen. Dieser Trigger kann entweder regelmäßig überprüfen, ob neue Daten oder Ereignisse an Ihrem Dienstendpunkt vorliegen, oder warten und lauschen. Wenn neue Daten oder ein Ereignis die angegebene Bedingung erfüllen, wird der Trigger ausgelöst und startet die Logik-App, die auf diesen Trigger lauscht. Um Logik-Apps auf diese Weise zu starten, kann Ihre API dem Abruftrigger- oder Webhooktriggermuster folgen. Diese Muster ähneln ihren Äquivalenten für Abrufaktionen und Webhookaktionen. Erfahren Sie auch mehr über die Nutzung der Messung für Trigger.

Regelmäßiges Überprüfen auf neue Daten oder Ereignisse mit dem Abruftriggermuster

Ein Abruftrigger verhält sich ähnlich wie die zuvor in diesem Thema beschriebene Abrufaktion. Die Azure Logic Apps-Engine ruft in regelmäßigen Abständen den Triggerendpunkt auf und überprüft ihn auf neue Daten oder Ereignisse. Wenn die Engine neue Daten oder Ereignisse findet, die die angegebene Bedingung erfüllen, wird der Trigger ausgelöst. Dann erstellt die Engine eine Workflowinstanz, die die Daten als Eingabe verarbeitet.

Hier werden die einzelnen Schritte für einen Abruftrigger aus API-Sicht beschrieben:

Um beispielsweise Ihren Dienst in regelmäßigen Abständen auf neue Dateien zu überprüfen, können Sie einen Abruftrigger mit diesem Verhalten erstellen:

Warten und Lauschen auf neue Daten oder Ereignisse mit dem Webhooktriggermuster

Ein Webhooktrigger ist ein Pushtrigger, der an Ihrem Dienstendpunkt auf neue Daten oder Ereignisse wartet und lauscht. Wenn neue Daten oder Ereignisse die angegebene Bedingung erfüllen, wird der Trigger ausgelöst und erstellt eine Workflowinstanz, die dann die Daten als Eingabe verarbeitet. Webhooktrigger fungieren ähnlich wie die zuvor in diesem Thema beschriebenen Webhookaktionen und werden mit subscribe- und unsubscribe-Endpunkten eingerichtet.

• subscribe-Endpunkt: Wenn Sie in der Logik-App einen Webhooktrigger hinzufügen und speichern, ruft die Azure Logic Apps-Engine den subscribe-Endpunkt auf. Dieser Schritt bewirkt, dass der Workflow eine Rückruf-URL erstellt, die Ihre API speichert. Wenn neue Daten oder Ereignisse vorliegen, die die angegebene Bedingung erfüllen, ruft Ihre API mit einem HTTP POST zur URL zurück. Inhaltsnutzlast und Header werden der Logik-App als Eingabe übergeben.

• unsubscribe-Endpunkt: Wenn der Webhooktrigger oder die gesamte Logik-App gelöscht wird, ruft die Azure Logic Apps-Engine den unsubscribe-Endpunkt auf. Ihre API kann dann die Registrierung der Rückruf-URL aufheben und alle Prozesse nach Bedarf beenden.

Der Workflow-Designer unterstützt derzeit keine Ermittlung von Webhookendpunkten über Swagger. Also müssen Sie für dieses Muster einen Webhooktrigger hinzufügen und URL, Header und Text für die Anforderung angeben. Siehe auch HTTPWebhook-Trigger. Ein Beispiel für Webhookmuster finden Sie in diesem Webhooktriggercontroller-Beispiel in GitHub.

Hier finden Sie weitere Tipps und Hinweise:

• Um die Rückruf-URL zu übergeben, können Sie in jedem dieser vorherigen Felder nach Bedarf die @listCallbackUrl()-Workflowfunktion verwenden.

• Um die mehrfache Verarbeitung der gleichen Daten zu verhindern, sollte Ihr Trigger Daten bereinigen, die bereits gelesen und an die Logik-App übergeben wurden.

• Wenn Sie sowohl die Logik-App-Ressource als auch den abonnierten Dienst besitzen, müssen Sie den unsubscribe-Endpunkt nicht aufrufen, nachdem die Rückruf-URL aufgerufen wurde. Andernfalls muss die Logic Apps-Runtime den unsubscribe-Endpunkt aufrufen, um zu signalisieren, dass keine weiteren Aufrufe mehr erwartet werden, und die Ressourcenbereinigung auf der Serverseite zuzulassen.

Verbessern der Sicherheit für Aufrufe Ihrer APIs in Logik-Apps

Nachdem Sie Ihre benutzerdefinierten APIs erstellt haben, richten Sie die Authentifizierung für Ihre APIs so ein, dass Sie sie in Logik-Apps sicher aufrufen können. Informationen zu Verbessern der Sicherheit für Aufrufe von benutzerdefinierten APIs in Logik-Apps.

Bereitstellen und Aufrufen Ihrer APIs

Nachdem Sie die Authentifizierung eingerichtet haben, richten Sie Bereitstellung Ihrer APIs ein. Erfahren Sie mehr zum Bereitstellen und Aufrufen benutzerdefinierter APIs in Logik-Apps.

Veröffentlichen benutzerdefinierter APIs in Azure

Um Ihre benutzerdefinierten APIs für andere Azure Logic Apps-Benutzer in Azure verfügbar zu machen, müssen Sie Sicherheitseinstellungen hinzufügen und sie als Azure Logic App-Connectors registrieren. Weitere Informationen finden Sie unter Übersicht über benutzerdefinierte Connectors.

Um Ihre benutzerdefinierten APIs allen Benutzern in Logic Apps, Power Automate und Microsoft Power Apps zur Verfügung zu stellen, müssen Sie Sicherheitseinstellungen hinzufügen, Ihre APIs als Azure Logic App-Connectors registrieren und Ihre Connectors für das Microsoft Azure Certified-Programm vorschlagen.

Support

• Spezifische Hilfe zu benutzerdefinierten APIs finden Sie unter customapishelp@microsoft.com.

• Weitere Informationen finden Sie auf der Frageseite von Microsoft Q&A für Azure Logic Apps.

Nächste Schritte

• Behandeln von Fehlern und Ausnahmen
• Aufrufen, Auslösen oder Schachteln von Workflows mit HTTP-Endpunkten in Logik-Apps
• Nutzung der Messung für Aktionen und Trigger