Webaktivität in Azure Data Factory und Azure Synapse Analytics

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!

Die Webaktivität kann verwendet werden, um einen benutzerdefinierten REST-Endpunkt aus einer Azure Data Factory- oder Synapse-Pipeline aufzurufen. Sie können Datasets und verknüpfte Dienste zur Verwendung und für den Zugriff durch die Aktivität übergeben.

Hinweis

Webaktivitäten werden zum Aufrufen von URLs unterstützt, die in einem privaten virtuellen Netzwerk gehostet sind, sowie zum Nutzen selbstgehosteter Integration Runtimes. Die Integration Runtime sollte den URL-Endpunkt erreichen können.

Hinweis

Die maximal unterstützte Payloadgröße für die Ausgabe von Antworten beträgt 4 MB.

Erstellen einer Webaktivität mit Benutzeroberfläche

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

Suchen Sie im Bereich mit den Pipelineaktivitäten nach Web, und ziehen Sie eine Webaktivität in den Pipelinebereich.
Wählen Sie in diesem Bereich die neue Webaktivitä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 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":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

Typeigenschaften

Eigenschaft	BESCHREIBUNG	Zulässige Werte	Erforderlich
name	Name der Webaktivität	String	Ja
type	Muss auf WebActivity festgelegt sein.	String	Ja
method	REST-API-Methode für den Zielendpunkt.	Eine Zeichenfolge. Unterstützte Typen: „GET“, „POST“, „PUT“, „PATCH“, „DELETE“	Ja
url	Zielendpunkt und Pfad	Zeichenfolge (oder Ausdruck mit resultType der Zeichenfolge). Nach einer Minute tritt für die Aktivität ein Timeout mit einem Fehler auf, falls sie keine Antwort vom Endpunkt erhält. Sie können dieses Antworttimeout auf bis zu zehn Minuten erhöhen, indem Sie die httpRequestTimeout-Eigenschaft aktualisieren.	Ja
httpRequestTimeout	Dauer des Antworttimeouts	„hh:mm:ss“ mit dem maximalen Wert 00:10:00. Ohne explizite Angabe wird standardmäßig 00:01:00 festgelegt.	Nein
headers	Header, die in der Anforderung gesendet werden. Verwenden Sie beispielsweise Folgendes, um Sprache und Typ für eine Anforderung festzulegen: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Zeichenfolge (oder ein Ausdruck mit resultType der Zeichenfolge)	Nein
body	Stellt die an den Endpunkt gesendete Nutzlast dar.	Zeichenfolge (oder Ausdruck mit resultType der Zeichenfolge). Weitere Informationen finden Sie in den Details zum Schema der Anforderungsnutzlast im Abschnitt Schema der Anforderungsnutzlast.	Erforderlich für POST/PUT/PATCH-Methoden. Optional für DELETE-Methode.
authentication	Die zum Aufrufen des Endpunkts verwendete Authentifizierungsmethode. Unterstützte Typen: „Basic“, „Clientzertifikat“, „Systemseitig zugewiesene verwaltete Identität“, „Benutzerseitig zugewiesene verwaltete Identität“, „Dienstprinzipal“. Weitere Informationen finden Sie unter Authentifizierung. Wenn keine Authentifizierung erforderlich ist, schließen Sie diese Eigenschaft aus.	Zeichenfolge (oder ein Ausdruck mit resultType der Zeichenfolge)	Nein
turnOffAsync	Option zum Deaktivieren des Aufrufs von HTTP GET im Feld „Location“ im Antwortheader einer HTTP 202-Antwort. Wenn „true“ festgelegt ist, wird der Aufruf von HTTP GET an „Location“ im Antwortheader beendet. Wenn „false“ festgelegt ist, wird weiterhin in HTTP-Antwortheadern an „Location“ ein HTTP GET-Aufruf ausgegeben.	Zulässige Werte sind false (Standard) und true.	Nein
disableCertValidation	Entfernt die serverseitige Zertifikatüberprüfung (nur empfohlen, wenn Sie eine Verbindung zu einem vertrauenswürdigen Server herstellen, der kein Standardzertifikat der Zertifizierungsstelle verwendet).	Zulässige Werte sind false (Standard) und true.	Nein
datasets	Liste der Datasets, die an den Endpunkt übergeben werden.	Array von Datasetverweisen. Kann ein leeres Array sein.	Ja
linkedServices	Liste der verknüpften Dienste, die an den Endpunkt übergeben werden.	Array von Verweisen auf verknüpfte Dienste. Kann ein leeres Array sein.	Ja
connectVia	Die Integration Runtime, die zum Herstellen einer Verbindung mit dem Datenspeicher verwendet werden soll. Sie können die Azure Integration Runtime oder eine selbstgehostete Integration Runtime verwenden (sofern sich Ihr Datenspeicher in einem privaten Netzwerk befindet). Wenn diese Eigenschaft nicht angegeben ist, verwendet der Dienst die normale Azure Integration Runtime.	Der Verweis auf die Integration Runtime.	Nein

Hinweis

REST-Endpunkte, die die Webaktivität aufruft, müssen eine Antwort vom Typ JSON zurückgeben. Nach einer Minute tritt für die Aktivität ein Timeout mit einem Fehler auf, falls sie keine Antwort vom Endpunkt erhält. Für Endpunkte, die das asynchrones Anforderungs-Antwort-Muster unterstützen, wird die Webaktivität weiterhin warten, ohne dass (für bis zu 7 Tage) ein Timeout auftritt oder bis die Endpunkte den Abschluss des Auftrags signalisieren.

Die folgende Tabelle enthält die Anforderungen für JSON-Inhalt:

Werttyp	Anforderungstext	Antworttext
JSON-Objekt	Unterstützt	Unterstützt
JSON-Array	Unterstützung von (Derzeit funktionieren JSON-Arrays aufgrund eines Bugs nicht. Eine Korrektur ist in Arbeit.)	Nicht unterstützt
JSON-Wert	Unterstützt	Nicht unterstützt
Nicht-JSON-Typ	Nicht unterstützt	Nicht unterstützt

Authentifizierung

Im Folgenden finden Sie die unterstützten Authentifizierungstypen in der Webaktivität.

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 das Kennwort an.

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

Zertifikat muss ein x509-Zertifikat sein. Zum Konvertieren in eine PFX-Datei können Sie Ihr bevorzugtes Hilfsprogramm verwenden. Für die Base64-Codierung können Sie den folgenden PowerShell-Codeausschnitt verwenden.

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

Verwaltete Identität

Geben Sie den Ressourcen-URI an, für den das Zugriffstoken mithilfe der verwalteten Identität für die Data Factory- oder Synapse-Arbeitsbereichsinstanz 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 Ihr Data Factory- oder Synapse-Arbeitsbereich mit einem Git-Repository konfiguriert ist, müssen Sie Ihre Anmeldeinformationen in Azure Key Vault speichern, damit Sie die Standardauthentifizierung oder die Clientzertifikatauthentifizierung verwenden können. Der Dienst speichert Kennwörter nicht in Git.

Schema der Anforderungsnutzlast

Wenn Sie die POST/PUT-Methode verwenden, stellt die Eigenschaft „body“ die Nutzlast dar, die an den Endpunkt gesendet wird. Sie können verknüpfte Dienste und Datasets als Teil der Nutzlast übergeben. Dies ist das Schema für die Nutzlast:

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

Beispiel

In diesem Beispiel ruft die Webaktivität in der Pipeline einen REST-Endpunkt auf. Sie übergibt einen verknüpften Azure SQL-Dienst und ein Azure SQL-Dataset an den Endpunkt. Der REST-Endpunkt verwendet die Azure SQL-Verbindungszeichenfolge für die Verbindung mit dem logischen SQL-Server und gibt den Namen der SQL Server-Instanz zurück.

Definition der Pipeline

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

Parameterwerte der Pipeline

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

Webdienst-Endpunktcode


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

Informationen zu weiteren unterstützten Ablaufsteuerungsaktivitäten:

Webaktivität in Azure Data Factory und Azure Synapse Analytics

Erstellen einer Webaktivität mit Benutzeroberfläche

Syntax

Typeigenschaften

Authentifizierung

Keine

Basic

Clientzertifikat

Verwaltete Identität

Schema der Anforderungsnutzlast

Beispiel

Definition der Pipeline

Parameterwerte der Pipeline

Webdienst-Endpunktcode

Zugehöriger Inhalt

Zusätzliche Ressourcen