Freigeben über


Webaktivität in Azure Data Factory und Azure Synapse Analytics

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:

  1. Suchen Sie im Bereich mit den Pipelineaktivitäten nach Web, und ziehen Sie eine Webaktivität in den Pipelinebereich.

  2. 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.

    Benutzeroberfläche für eine Webaktivität.

  3. 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.

  4. 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 1 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.

Dienstprinzipal

Geben Sie die Mandanten-ID, die Dienstprinzipal-ID und den Dienstprinzipalschlüssel mithilfe einer sicheren Zeichenfolge für den geheimen Clientschlüssel an.

"authentication": {
            "type": "ServicePrincipal",
            "tenant": "your_tenant_id",
            "servicePrincipalId": "your_client_id",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "your_client_secret"
            },
            "resource": "https://management.azure.com/"
}

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: