Webhook-Aktivität in Azure Data Factory

Artikel
10/20/2023

GILT FÜR: Azure Data Factory Azure Synapse Analytics

Tipp

Testen Sie Data Factory in Microsoft Fabric, eine All-in-One-Analyselösung für Unternehmen. Microsoft Fabric deckt alle Aufgaben ab, von der Datenverschiebung bis hin zu Data Science, Echtzeitanalysen, Business Intelligence und Berichterstellung. Erfahren Sie, wie Sie kostenlos eine neue Testversion starten!

Eine Webhook-Aktivität kann die Ausführung von Pipelines über benutzerdefinierten Code steuern. Mithilfe der Webhook-Aktivität kann Code einen Endpunkt aufrufen und eine Rückruf-URL an ihn übergeben. Die Pipelineausführung wartet, bis der Rückruf aufgerufen wurde, bevor sie mit der nächsten Aktivität fortfährt.

Wichtig

Mit der Webhook-Aktivität können Sie nun Fehlerstatus- und benutzerdefinierte Meldungen an die Aktivität und die Pipeline zurückgeben. Legen Sie reportStatusOnCallBack auf „true“ fest, und geben Sie StatusCode und Error in der Rückrufnutzlast an. Weitere Informationen finden Sie unter Weitere Hinweise.

Erstellen einer Webhookaktivität über die Benutzeroberfläche

Führen Sie die folgenden Schritte aus, um eine Webhookaktivität in einer Pipeline zu verwenden:

Suchen Sie im Bereich mit den Pipelineaktivitäten nach Webhook, und ziehen Sie eine Webhookaktivität in den Pipelinebereich.
Wählen Sie in diesem Bereich die neue Webhookaktivität aus (wenn sie noch nicht ausgewählt wurde), und wählen Sie anschließend die Registerkarte Einstellungen aus, um die Details zu bearbeiten.
Geben Sie eine URL für den Webhook an, die ein URL-Zeichenfolgenliteral oder eine beliebige Kombination aus dynamischen Ausdrücken, Funktionen, Systemvariablen oder Ausgaben aus anderen Aktivitäten sein kann. Geben Sie weitere Details an, die zusammen mit der Anforderung übermittelt werden sollen.
Verwenden Sie die Ausgabe aus der Aktivität als Eingabe für jede andere Aktivität, und verweisen Sie überall dort auf die Ausgabe, wo dynamischer Inhalt in der Zielaktivität unterstützt wird.

Syntax


{
    "name": "MyWebHookActivity",
    "type": "WebHook",
    "typeProperties": {
        "method": "POST",
        "url": "<URLEndpoint>",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": {
            "key": "value"
        },
        "timeout": "00:10:00",
        "reportStatusOnCallBack": false,
        "authentication": {
            "type": "ClientCertificate",
            "pfx": "****",
            "password": "****"
        }
    }
}

Typeigenschaften

Eigenschaft	BESCHREIBUNG	Zulässige Werte	Erforderlich
name	Der Name der Webhook-Aktivität.	String	Ja
type	Muss auf „WebHook“ festgelegt werden.	String	Ja
method	Die REST-API-Methode für den Zielendpunkt.	Eine Zeichenfolge. Der unterstützte Typ ist „POST“.	Ja
url	Der Zielendpunkt und Pfad.	Eine Zeichenfolge oder ein Ausdruck mit dem resultType-Wert einer Zeichenfolge.	Ja
headers	Header, die in der Anforderung gesendet werden. Hier sehen Sie ein Beispiel für das Festlegen von Sprache und Typ für eine Anforderung: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Eine Zeichenfolge oder ein Ausdruck mit dem resultType-Wert einer Zeichenfolge.	Ja. Ein `Content-Type`-Header wie `"headers":{ "Content-Type":"application/json"}` ist erforderlich.
body	Stellt die an den Endpunkt gesendete Nutzlast dar.	Gültiges JSON-Format oder ein Ausdruck mit dem resultType-JSON-Wert. Informationen zum Schema der Anforderungsnutzlast finden Sie unter Schema der Anforderungsnutzlast.	Ja
Authentifizierung	Die zum Aufrufen des Endpunkts verwendete Authentifizierungsmethode. Unterstützte Typen sind „Basic“ und „ClientCertificate“. Weitere Informationen finden Sie unter Authentifizierung. Wenn keine Authentifizierung erforderlich ist, schließen Sie diese Eigenschaft aus.	Eine Zeichenfolge oder ein Ausdruck mit dem resultType-Wert einer Zeichenfolge.	Nein
timeout	Legt fest, wie lange die Aktivität darauf warten soll, dass der mittels callBackUri festgelegte Rückruf aufgerufen wird. Der Standardwert ist 10 Minuten („00:10:00“). Werte haben das TimeSpan-Format t.hh:mm:ss.	String	Nein
Report status on callback	Ermöglicht einem Benutzer, den Fehlerstatus einer Webhook-Aktivität zu melden.	Boolesch	Nein

Authentifizierung

Eine Webhook-Aktivität unterstützt die folgenden Authentifizierungstypen.

Keine

Wenn keine Authentifizierung erforderlich ist, schließen Sie die Eigenschaft authentication nicht ein.

Basic

Geben Sie Benutzername und Kennwort für die Standardauthentifizierung an.

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

Clientzertifikat

Geben Sie die Base64-codierten Inhalte einer PFX-Datei und ein Kennwort an.

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

Verwaltete Identität

Verwenden Sie die verwaltete Identität für den Data Factory- oder Synapse-Arbeitsbereich, um den Ressourcen-URI anzugeben, für den das Zugriffstoken angefordert wird. Verwenden Sie zum Aufrufen der Azure-Ressourcenverwaltungs-API https://management.azure.com/. Weitere Informationen zur Funktion verwalteter Identitäten finden Sie unter Was sind verwaltete Identitäten für Azure-Ressourcen?.

"authentication": {
    "type": "MSI",
    "resource": "https://management.azure.com/"
}

Hinweis

Wenn der Dienst mit einem Git-Repository konfiguriert ist, müssen Sie Ihre Anmeldeinformationen in Azure Key Vault speichern, um die Standardauthentifizierung oder die Clientzertifikatauthentifizierung zu verwenden. Der Dienst speichert keine Kennwörter in Git.

Zusätzliche Hinweise

Der Dienst übergibt die zusätzliche Eigenschaft callBackUri in dem an den URL-Endpunkt gesendeten Text. Der Dienst erwartet, dass dieser URI vor dem angegebenen Timeoutwert aufgerufen wird. Wenn der URI nicht aufgerufen wird, tritt bei der Aktivität mit dem Status „TimedOut“ ein Fehler auf.

Bei der Webhook-Aktivität tritt ein Fehler auf, wenn beim Aufruf des benutzerdefinierten Endpunkts ein Fehler auftritt. Im Textkörper des Rückrufs kann jede beliebige Fehlermeldung hinzugefügt und in einer späteren Aktivität verwendet werden.

Bei jedem REST-API-Befehl kommt es zu einem Timeout des Clients, wenn der Endpunkt nicht innerhalb einer Minute antwortet. Dieses Verhalten ist die bewährte HTTP-Standardmethode. Um dieses Problem zu beheben, implementieren Sie ein 202-Muster. Im aktuellen Fall gibt der Endpunkt 202 (Akzeptiert) und die Clientabrufe zurück.

Das 1-Minute-Timeout für die Anforderung hat nichts mit dem Aktivitätstimeout zu tun. Letzteres wird verwendet, um auf den durch callbackUri angegeben Rückruf zu warten.

Der an den Rückruf-URI zurückgegebene Textkörper muss im gültigen JSON-Format vorliegen. Legen Sie den Header Content-Type auf application/json fest.

Wenn Sie die Eigenschaft Status bei Rückruf melden verwenden, müssen Sie dem Textkörper bei einem Rückruf den folgenden Code hinzufügen:

{
    "Output": {
        // output object is used in activity output
        "testProp": "testPropValue"
    },
    "Error": {
        // Optional, set it when you want to fail the activity
        "ErrorCode": "testErrorCode",
        "Message": "error message to show in activity error"
    },
    "StatusCode": "403" // when status code is >=400, activity is marked as failed
}

Weitere Informationen finden Sie in den folgenden unterstützten Ablaufsteuerungsaktivitäten: