Attività Web in Azure Data Factory e Azure Synapse Analytics

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

L'attività Web può essere usata per chiamare un endpoint REST personalizzato da una pipeline di Azure Data Factory o Synapse. È possibile passare set di dati e servizi collegati in modo che l'attività possa usarli e accedervi.

Creare un'attività Web con l'interfaccia utente

Per usare un'attività Web in una pipeline, completare la procedura seguente:

1. Cercare Web nel riquadro Attività pipeline e trascinare un'attività Web nell'area di disegno della pipeline.

2. Selezionare la nuova attività Web nell'area di disegno se non è già selezionata e la relativa scheda Impostazioni per modificarne i dettagli.

   

3. Specificare un URL, che può essere una stringa URL letterale o qualsiasi combinazione di espressioni dinamiche, funzioni, variabili di sistema o output di altre attività. Specificare altri dettagli da inviare con la richiesta.

4. Usare l'output dell'attività come input per qualsiasi altra attività e fare riferimento all'output in qualsiasi punto del contenuto dinamico supportato nell'attività di destinazione.

Sintassi

{
   "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"
         }
      ]
   }
}

Proprietà del tipo

La tabella seguente indica i requisiti per il contenuto JSON:

Autenticazione

Di seguito sono riportati i tipi di autenticazione supportati nell'attività Web.

None

Se l'autenticazione non è necessaria, non includere la proprietà "authentication".

Di base

Specificare il nome utente e la password da usare per l'autenticazione di base.

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

Certificato client

Specificare il contenuto con codifica Base64 di un file PFX e la password.

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

Il certificato deve essere un certificato x509. Per la conversione in file PFX, è possibile usare l'utilità preferita. Per la codifica base 64, è possibile usare il frammento di codice di PowerShell seguente.

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

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

Identità gestita

Specificare l'URI di risorsa per cui verrà richiesto il token di accesso usando l'identità gestita per la data factory o l'istanza dell'area di lavoro di Synapse. Per chiamare l'API di gestione delle risorse di Azure, usare https://management.azure.com/. Per altre informazioni sul funzionamento delle identità gestite, consultare la pagina di panoramica sulle identità gestite per le risorse di Azure.

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

Entità servizio

Specificare l'ID tenant, l'ID entità servizio e la chiave dell'entità servizio, usando una stringa sicura per il segreto client.

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

Schema del payload della richiesta

Quando si usa il metodo POST o PUT, la proprietà body rappresenta il payload che viene inviato all'endpoint. È possibile passare i servizi collegati e i set di dati come parte del payload. Di seguito è riportato lo schema per il payload:

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

Esempio

In questo esempio, l'attività Web della pipeline chiama un endpoint REST. Passa all'endpoint un servizio collegato SQL di Azure e un set di dati SQL di Azure. L'endpoint REST usa la stringa di connessione SQL di Azure per connettersi al server SQL logico e restituisce il nome dell'istanza del server SQL.

Definizione della 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"
            }
        }
    }
}

Valori dei parametri della pipeline

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

Codice endpoint del servizio Web

[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);
}

Contenuto correlato

Vedere altre attività del flusso di controllo supportate:

• Attività ExecutePipeline
• Attività ForEach
• Attività Get Metadata
• Attività Lookup