Webhooktrigger
Webhooks sind beliebte HTTP-basierte Implementierungen eines allgemeineren Benachrichtigungsmusters zwischen Herausgeber und Abonnent. Sie bieten eine Möglichkeit, Benachrichtigungen an einen externen Dienst (Abonnenten) zu senden, wenn bestimmte Ereignisse innerhalb eines Systems (Herausgeber) auftreten.
Mit Power Automate und Azure Logic Apps können Entwickler Webhooks als Trigger verwenden. In diesem Szenario spielen Trigger die Rolle eines Abonnenten, der Webhooks im Namen eines Entwicklers registriert und die Registrierung aufhebt. Die Registrierung erfolgt, wenn ein Schritt in einem Cloud-Flow oder Logic Apps-Workflow erstellt oder aktualisiert wird. Wenn der Schritt entfernt wird, hebt die Plattform die Registrierung des Webhooks auf.
Der folgende Screenshot zeigt ein Beispiel für die Interaktion zwischen Abonnent und Herausgeber.
Die Verantwortlichkeiten der Parteien sind in der folgenden Tabelle aufgeführt.
| Herausgeber (benutzerdefinierter Konnektor OpenAPI) | Abonnent (Power Automate/Logic Apps) |
|---|---|
| Stellt den Endpunkt für die Abonnementregistrierung bereit | Ruft den Endpunkt der Abonnementregistrierung auf, wenn ein Trigger in einem Flow erstellt oder aktualisiert wird |
| Gibt den Benachrichtigungsvertrag an, d. h. welches Objekt bei jeder Benachrichtigung übergeben wird Muss den Standort-HTTP-Header zum Zeitpunkt der Erstellung eines Webhooks in die 201-Antwort aufnehmen | Gibt die URL des automatisch generierten Endpunkts an, der die Benachrichtigungsnachrichten akzeptiert |
| Verwaltet das Abonnentenregister und deren Benachrichtigungsendpunkte | Empfängt und speichert Standortinformationen, die zum Abmelden des Webhooks verwendet werden |
| Gibt eine POST-Anforderung an jeden registrierten Endpunkt aus und übergibt die relevanten Daten im Nachrichtentext | Empfängt Benachrichtigungen, validiert sie anhand des vom benutzerdefinierten Konnektor definierten Schemas und löst dann die Automatisierung aus |
| Hebt die Registrierung der Endpunkte als Antwort auf die DELETE-Nachricht auf bzw. entfernt sie | Gibt eine DELETE-Nachricht aus, um den Webhook abzumelden, wenn der Triggerschritt gelöscht wird |
Webhooks bieten nur den Benachrichtigungsmechanismus und unterstützen keine Manipulation der Daten. Häufig wird eine Webhook-Implementierung durch eine oder mehrere Aktionen ergänzt, die das Abrufen und Bearbeiten von Daten oder Objekten unterstützen.
API-Anforderungen
Um die von benutzerdefinierten Konnektoren erforderliche Webhook-Unterstützung bereitzustellen, muss die API-Implementierung die folgenden Parameter bereitstellen:
Ein Endpunkt, der die Registrierungsnachricht akzeptiert und Standortinformationen zurückgibt
Eine Definition des Nachrichtentexts, der mit den Benachrichtigungsnachrichten gesendet wird
Ein Endpunkt zum Akzeptieren der DELETE-Nachricht zum Entfernen der Webhook-Registrierung
Normalerweise verwaltet die API-Implementierung eine interne Liste aktiver Abonnenten, wobei jeder Abonnent durch eine eindeutige URL identifiziert wird. Um diese URL an den Abonnenten zurückzugeben, muss die erfolgreiche Webhook-Erstellung eine HTTP 201-Antwort zurückgeben und einen Ort-HTTP-Header enthalten. Der Wert dieses Speicherorts wird später vom Abonnenten verwendet, um die Webhook-Registrierung zu löschen.
Einen Webhooktrigger verwenden
Benutzerdefinierte Konnektoren verwenden OpenAPI, um die von Webhooks geforderte Herausgeber-API-Implementierung zu beschreiben. Um einen Webhook-Trigger in einem benutzerdefinierten Konnektor zu definieren, müssen Sie drei wesentliche Teile in die OpenAPI-Definition aufnehmen:
Eine POST-Nachricht, die die Registrierung von Webhooks beschreibt
Inhaltsdefinition für die Webhook-Antworten
Eine DELETE-Nachricht, die den Webhook-Abrissprozess beschreibt
Registrierungsnachricht
Die Triggerdefinition muss eine POST-Methode enthalten, mit der ein Webhook registriert wird. Sie ist ähnlich wie Aktionen definiert.
Die OpenAPI-Spezifikationsversion, die von Microsoft Power Platform verwendet wird, unterscheidet keine Aktionen und Trigger. Die benutzerdefinierte Konnektordefinition verwendet die benutzerdefinierte x-ms-Trigger-Erweiterung zum Deklarieren eines Triggers.
paths:
/webhooks:
post:
operationId: OrderCreated
x-ms-trigger: single
Die Anwesenheit der x-ms-Trigger-Erweiterung gibt an, dass die Methode ein Trigger und keine Aktion ist. Diese Erweiterung wird automatisch hinzugefügt, wenn mit dem Assistenten ein Trigger erstellt wird. Wenn jedoch aus den externen OpenAPI-Definitionen ein benutzerdefinierter Konnektor erstellt wird, werden beim Importvorgang immer Aktionen erstellt. In diesem Szenario müssen Sie Trigger mithilfe des Assistenten neu erstellen und dann die entsprechenden Aktionsdefinitionen entfernen.
Mögliche Werte für die x-ms-Trigger-Erweiterung sind einzeln oder als Batch, um zwischen einem Objekt und Array-Antworten zu unterscheiden. Ein einzelnes Objekt ist enthalten, wenn ein Webhook für jede Änderung eine Benachrichtigung auslöst. Dieser Ansatz ist bei Webhooks am gebräuchlichsten. Wenn mehrere Änderungen zu einer einzigen Benachrichtigung zusammengefasst werden, wird ein Array von Objekten gesendet. Dieser Ansatz wird normalerweise bei Abruftriggern verwendet und wird später in diesem Modul erläutert.
Webhook-Antwort
Definitionen zu benutzerdefinierten Konnektoren können den Inhalt der eingehenden Webhook-Antworten Ihres Dienstes beschreiben, wenn ein Ereignis auftritt. Diese Definition ist zwar nicht obligatorisch, identifiziert jedoch die dynamischen Werte, die dem Entwickler zur Entwurfszeit zur Verfügung stehen, in der Liste der dynamischen Inhalte.
Hinweis
Diese Antwort bezieht sich nicht auf die Anforderung, mit der der Webhook erstellt und registriert wird. Diese Daten werden von Ihrem Dienst gesendet, wenn ein Ereignis eintritt.
Die benutzerdefinierte Eigenschaft x-ms-Benachrichtigungsinhalt ist eine weitere Erweiterung, die in OpenAPI zum Definieren des Webhook-Antwortschemas verwendet wird.
paths:
/webhooks:
x-ms-notification-content:
description: Order
schema:
type: object
properties:
id: {type: integer, format: int32, description: id}
order_key: {type: string, description: order_key}
status: {type: string, description: status}
currency: {type: string, description: currency}
date_created: {type: string, description: date_created}
total: {type: number, description: total, format: decimal}
Tipp
Eine Webhook-Antwortdefinition muss nicht den gesamten Inhalt der Antwort enthalten, sondern nur die Teile, die Sie den Flowentwicklern zur Entwurfszeit in der dynamischen Inhaltsliste zur Verfügung stellen möchten.
Daten, die mit der Webhook-Antwort gesendet werden, müssen möglicherweise nicht alle Eigenschaften enthalten, und tun dies auch nicht, die Sie vom zugrunde liegenden Objekt benötigen. In diesen Situationen möchten Sie im benutzerdefinierten Konnektor andere Aktionen zum Abrufen von Informationen erstellen. Beispielsweise sendet ein Webshop möglicherweise nur eine neue Bestellkennung mit der Benachrichtigung „Wenn ein neuer Auftrag erstellt wird“. Anschließend kann der benutzerdefinierte Konnektor eine Aktion definieren, z. B. „Bestelldetails abrufen“, die eine Auftragskennung akzeptiert und erweiterte Informationen zum Auftrag zurückgibt.
Das Gegenteil ist auch der Fall. Webhook-Antworten enthalten möglicherweise übermäßige Informationen, die unter normalen Umständen nicht erforderlich oder benötigt sind. Sie müssen nur die Daten beschreiben, die Sie in den Entwickleroberflächen Power Automate oder Logic Apps anzeigen möchten. Wenn der Entwickler Zugriff auf weitere Daten benötigt, die in der Benachrichtigung gesendet werden, kann er JSON-Funktionen verwenden, um diese Eigenschaften direkt aus der empfangenen Nachricht zu extrahieren.
Nachricht löschen
Um für Power Automate oder Logic Apps einen Webhook zu löschen, muss die API einen Speicherort-HTTP-Header in der Antwort zum Zeitpunkt der Erstellung des Webhooks enthalten.
Wichtig
Sie müssen den Pfad der Anforderung zum Löschen von Webhooks als interne Aktion definieren. Diese Aktion sendet eine DELETE-Anforderung an die in der Kopfzeile des Speicherorts angegebene URL.
Wenn diese Aktion nicht definiert ist oder wenn die API die Kopfzeile für den Speicherort nicht enthält, werden Webhooks erstellt, aber nicht gelöscht. Dies kann zur Laufzeit zu Problemen bei der API-Implementierung führen.
Die Implementierung von Webhooks bietet einen flexiblen Mechanismus zur Unterstützung von Triggern in einem benutzerdefinierten Konnektor. Jedoch nicht jede API unterstützt Webhook-Integrationen. Die Abrufimplementierung bietet eine alternative Möglichkeit, Trigger in den benutzerdefinierten Konnektoren zu erstellen.