Verwenden von Webhooks mit Microsoft Flow

Webhooks sind einfache HTTP-Rückrufe, mit denen Ereignisbenachrichtigungen bereitgestellt werden. Mit Microsoft Flow können Sie Webhooks verwenden, um Flows auszulösen. Dieses Tutorial veranschaulicht das Erstellen eines Flows, der durch einen Webhook ausgelöst wird.

Hinweis

Dabei wird GitHub als Beispiel für einen Dienst verwendet, der Benachrichtigungen über Webhooks senden kann. Die hier beschriebenen Methoden können aber auf jeden Dienst übertragen werden, der Webhooks verwendet.

Voraussetzungen

Um das Tutorial abzuschließen, benötigen Sie Folgendes:

Die OpenAPI-Datei

Webhooks werden in Microsoft Flow als eine Art benutzerdefinierter Connector implementiert. Daher muss eine OpenAPI-JSON-Datei bereitgestellt werden, um das Format des Webhooks zu definieren. Die OpenAPI-Datei enthält drei Definitionen, die für die Funktion des Webhooks benötigt werden:

  1. Erstellen des Webhooks
  2. Definieren der eingehenden Hook-Anforderung über die API (in diesem Fall GitHub)
  3. Löschen des Webhooks

Erstellen des Webhooks

Der Webhook wird auf der GitHub-Seite durch HTTP POST an /repos/{owner}/{repo}/hooks erstellt. Microsoft Flow muss einen POST an diese URL durchführen, wenn ein neuer Flow mit dem in der OpenAPI-Datei definierten Trigger erstellt wird oder wenn der Trigger geändert wird. Im folgenden Beispiel enthält die post-Eigenschaft das Schema der Anforderung, die an GitHub gesendet wird.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
    "description": "Details for Webhook",
    "schema": {
        "$ref": "#/definitions/WebhookPushResponse"
    }
    },
    "post": {
    "description": "Creates a Github webhook",
    "summary": "Triggers when a PUSH event occurs",
    "operationId": "webhook-trigger",
    "x-ms-trigger": "single",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targetted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "Request body of webhook",
        "in": "body",
        "description": "This is the request body of the Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookRequestBody"
        }
        }
    ],
    "responses": {
        "201": {
        "description": "Created",
        "schema": {
            "$ref": "#/definitions/WebhookCreationResponse"
        }
        }
    }
    }
},

Wichtig

Die "x-ms-trigger": "single"-Eigenschaft ist eine Schemaerweiterung, die angibt, dass Microsoft Flow diesen Webhook in der Liste der verfügbaren Trigger im Flow-Designer anzeigen soll. Sie muss daher angegeben werden.

Definieren der eingehenden Hook-Anforderung über die API

Das Format der eingehenden Hook-Anforderung (die Benachrichtigung von GitHub an Microsoft Flow) wird in der benutzerdefinierten x-ms-notification-content-Eigenschaft definiert, wie im Beispiel oben gezeigt. Darin muss nicht der gesamte Inhalt der Anforderung enthalten sein, nur die Teile, die Sie in Ihren Flows verwenden möchten.

Löschen des Webhooks

Es ist sehr wichtig, eine Definition in der OpenAPI-Datei einzuschließen, in der Microsoft Flow mitgeteilt wird, wie der Webhook gelöscht werden soll. Microsoft Flow versucht jedes Mal, den Webhook zu löschen, wenn Sie den Trigger in Ihrem Flow aktualisieren oder den Flow löschen.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
    "description": "Deletes a Github webhook",
    "operationId": "DeleteTrigger",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targetted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "hook_Id",
        "in": "path",
        "description": "ID of the Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

Wichtig

Damit Microsoft Flow einen Webhook löschen kann, muss die API einen Location-HTTP-Header in der 201-Antwort enthalten, wenn der Webhook erstellt wird. Der Location-Header sollte den Pfad zu dem Webhook enthalten, der mit HTTP DELETE verwendet wird. Das Format der Location in der Antwort von GitHub folgt z.B. dem folgenden Format: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Authentifizierung

Die API, die die Webhook-Anforderung an Microsoft Flow sendet, verwendet normalerweise eine Authentifizierung. Dies gilt auch für GitHub. Es werden mehrere Arten der Authentifizierung unterstützt. Für dieses Tutorial werden die persönlichen Zugriffstoken von GitHub verwendet.

  1. Navigieren Sie zu GitHub, und melden Sie sich an, sofern Sie dies noch nicht getan haben.
  2. Klicken Sie in der oberen rechten Ecke auf Ihr Profilfoto, und klicken Sie im Menü auf Settings (Einstellungen).

    Einstellungen

  3. Klicken Sie im Menü auf der linken Seite unter Developer settings (Entwicklereinstellungen) auf Personal access tokens (Persönliche Zugriffstoken).

    Persönliche Zugriffstoken

  4. Klicken Sie auf die Schaltfläche Generate new token (Neues Token generieren).

    Neues Token generieren

  5. Geben Sie im Feld Token description (Tokenbeschreibung) eine Beschreibung ein.
  6. Aktivieren Sie das Kontrollkästchen admin:repo_hook.

    admin:repo_hook

  7. Klicken Sie auf die Schaltfläche Generate token (Token generieren).
  8. Notieren Sie sich das neue Token.

    Neues Token

    Wichtig

    Sie können auf dieses Token nicht noch einmal zugreifen. Sie sollten es kopieren und z.B. in Editor einfügen, um es später in diesem Tutorial verwenden zu können.

Hinzufügen des Webhooks in Microsoft Flow

Jetzt können wir den Webhook in Microsoft Flow als benutzerdefinierten Connector hinzufügen.

  1. Navigieren Sie zum Microsoft Flow-Webportal, und melden Sie sich, sofern noch nicht geschehen.
  2. Klicken Sie auf das Einstellungssymbol, und klicken Sie dann auf Benutzerdefinierte Connectors.

    Benutzerdefinierte Connectors

  3. Klicken Sie auf die Schaltfläche Benutzerdefinierten Connector erstellen.
  4. Klicken Sie auf das Dateiordnersymbol im Feld OpenAPI importieren, und wählen Sie die OpenAPI-Beispieldatei aus.
  5. Klicken Sie auf das Symbol Hochladen im Bereich Allgemeine Informationen, und wählen Sie dann eine Bilddatei aus, die als Symbol verwendet werden soll.
  6. Klicken Sie auf Weiter.

    Importieren der OpenAPI

  7. Auf dem nächsten Bildschirm werden die Sicherheitseinstellungen konfiguriert. Wählen Sie unter Authentifizierungstyp die Option Standardauthentifizierung aus.
  8. Geben Sie im Abschnitt Standardauthentifizierung für die Bezeichnungsfelder den Text Benutzername und Kennwort ein. Beachten Sie, dass dies nur Bezeichnungen sind, die angezeigt werden, wenn der Trigger in einem Flow verwendet wird.

    Standardauthentifizierung

  9. Geben Sie oben auf der Seite einen Namen für den Flow ein, und klicken Sie auf Connector erstellen.

    API erstellen

Der neue benutzerdefinierte Connector sollte nun in der Liste auf der Seite mit den benutzerdefinierten Connectors angezeigt werden.

Erstellen von Webhook-Triggern über die Benutzeroberfläche

  1. Nachdem Sie die OpenAPI-Baselinedatei hochgeladen bzw. erstellt haben, navigieren Sie im Assistenten für benutzerdefinierte Connectors zur Registerkarte Definition.
  2. Klicken Sie im linken Bereich auf + Neuer Trigger, und geben Sie für den Trigger eine Beschreibung ein. In diesem Beispiel erstellen wir einen Trigger, der bei einer Pullanforderung an ein Repository ausgelöst wird.

    Erstellen des Triggers (1)

  3. Jetzt definieren wir die Anforderung zum Erstellen des Webhook-Triggers. Hierfür können Sie eine Beispielanforderung zum Erstellen eines Webhook-Triggers importieren. Informationen zum Erstellen von Webhooks finden Sie in der Github-API-Referenz.
  4. In Microsoft Flow werden Standard-content-type-Header und Sicherheitsheader automatisch hinzugefügt, sie müssen daher beim Importieren eines Beispiels nicht definiert werden.

    Erstellen des Triggers (2)

  5. Nachdem Sie die Anforderung zum Erstellen eines Webhooks importiert haben, müssen Sie die Webhook-Antwort definieren. Dazu importieren Sie jetzt eine Beispielantwort. Informationen zu Pullanforderungsereignissen finden Sie in der Github-API-Referenz.

    Hinweis: Es ist nicht erforderlich, die vollständige Antwort einzufügen. Definieren Sie nur die Felder, die wirklich benötigt werden. In diesem Beispiel werden nur die URL der Pullanforderung sowie die Informationen des Benutzers, der die Pullanforderung stellt, extrahiert.

    Erstellen des Triggers (3)

  6. Im letzten Schritt wählen wir einen Parameter in der Anforderung zum Erstellen des Webhooks aus, der dem Wert entspricht, mit dem Microsoft Flow die Rückruf-URL für Github ausfüllen soll. In diesem Fall ist das die URL-Eigenschaft des config-Objekts.

    Erstellen des Triggers (4)

Verwenden des Webhooks als Trigger

Nachdem alles konfiguriert wurde, kann der Webhook in einem Flow verwendet werden. Wir erstellen einen Flow, der jedes Mal eine Pushbenachrichtigung an die mobile Microsoft Flow-App sendet, wenn das GitHub-Repository einen Git-Push empfängt.

  1. Klicken Sie im Microsoft Flow-Webportal oben auf der Seite auf Meine Flüsse.
  2. Wählen Sie Ohne Vorlage neu erstellen aus.
  3. Suchen Sie im Designer für Microsoft Flow nach dem benutzerdefinierten Connector, den wir bereits registriert haben.

    Neuer Trigger

    Klicken Sie auf das Element in der Liste, um es als Trigger zu verwenden.

  4. Da dieser benutzerdefinierte Connector zum ersten Mal verwendet wird, muss eine Verbindung mit diesem hergestellt werden. Geben Sie unter Verbindungsname einen beschreibenden Namen ein. Geben Sie als Benutzername Ihren GitHub-Benutzernamen ein. Verwenden Sie als Kennwort das persönliche Zugriffstoken, das Sie zuvor erstellt haben.

    Neue Verbindung

    Klicken Sie auf Erstellen.

  5. Nun müssen wir Microsoft Flow Informationen über das Repository bereitstellen, das überwacht werden soll. Möglicherweise erkennen Sie die Felder aus dem WebhookRequestBody-Objekt in der OpenAPI-Datei wieder. Geben Sie unter Besitzer und Repo den Besitzer und den Repositorynamen eines GitHub-Repositorys ein, das Sie überwachen möchten.

    Repository-Informationen

    Wichtig

    In diesem Beispiel verwende ich das Repository für Visual Studio-Code. Sie sollten ein Repository verwenden, für das Ihr Konto über Berechtigungen verfügt. Die einfachste Möglichkeit hierzu ist die Verwendung eines eigenen-Repositorys.

  6. Wählen Sie + Neuer Schritt und dann Aktion hinzufügen aus.
  7. Suchen Sie die Aktion Push notification (Pushbenachrichtigung), und wählen Sie sie aus.

    Pushbenachrichtigung

  8. Geben Sie Text im Feld Text ein. Beachten Sie, dass das WebhookPushResponse-Objekt in der OpenAPI-Datei die Liste der Parameter definiert, die Sie verwenden können.

    Details der Pushbenachrichtigung

  9. Geben Sie oben auf der Seite einen Namen für den Flow ein, und klicken Sie auf Fluss erstellen.

    Flow-Name

Überprüfung und Problembehandlung

Um zu überprüfen, ob alles ordnungsgemäß eingerichtet wurde, klicken Sie auf Meine Flüsse und dann auf das Symbol Info neben dem neuen Flow, um den Ausführungsverlauf anzuzeigen. Es sollte mindestens eine erfolgreiche Ausführung vom Erstellen des Webhooks angezeigt werden. Dies gibt an, dass der Webhook auf der GitHub-Seite erfolgreich erstellt wurde. Wenn das Ausführen fehlgeschlagen ist, können Sie Details zur Ausführung anzeigen, um die Fehlerursache zu ermitteln. Wenn der Fehler aufgrund der Antwort „404 Nicht gefunden“ aufgetreten ist, verfügt das GitHub-Konto wahrscheinlich nicht über die richtigen Berechtigungen zum Erstellen von Webhooks im verwendeten Repository.

Zusammenfassung

Wenn alles richtig konfiguriert ist, erhalten Sie jetzt Pushbenachrichtigungen in der mobilen App für Microsoft Flow, sobald ein Git-Push im ausgewählten GitHub-Repository erfolgt. Mit dem oben beschriebenen Prozess können Sie jeden Webhook-fähigen Dienst als Trigger in Ihren Flows verwenden.

Weitere Schritte