Attività Web in Azure Data Factory e Azure Synapse Analytics

Articolo
12/09/2023

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi completa per le aziende. Microsoft Fabric copre tutti gli elementi, dallo spostamento dei dati all'analisi scientifica dei dati, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Scopri come avviare gratuitamente una nuova versione di valutazione .

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.

Nota

L'attività Web è supportata per chiamare gli URL ospitati in una rete virtuale privata nonché per sfruttare il runtime di integrazione self-hosted. Il runtime di integrazione deve avere una linea di visibilità per l'endpoint dell'URL.

Nota

La dimensione massima supportata del payload della risposta di output è 4 MB.

Creare un'attività Web con l'interfaccia utente

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

Cercare Il Web nel riquadro Attività pipeline e trascinare un'attività Web nell'area di disegno della pipeline.
Selezionare la nuova attività Web nell'area di disegno se non è già selezionata e la scheda Impostazioni per modificarne i dettagli.
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.
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

Proprietà	Descrizione	Valori consentiti	Obbligatorio
name	Nome dell'attività Web	Stringa	Sì
Tipo	Deve essere impostato su WebActivity.	Stringa	Sì
metodo	Metodo DELL'API REST per l'endpoint di destinazione.	String. Tipi supportati: "GET", "POST", "PUT", "PATCH", "DELETE"	Sì
URL	Endpoint e percorso di destinazione	Stringa (o espressione con l'elemento resultType della stringa). L'attività raggiungerà il timeout a 1 minuto con un errore se non riceve una risposta dall'endpoint. È possibile aumentare questo timeout di risposta fino a 10 minuti aggiornando la proprietà httpRequestTimeout	Sì
httpRequestTimeout	Durata del timeout della risposta	hh:mm:ss con il valore massimo come 00:10:00. Se non specificato in modo esplicito, il valore predefinito è 00:01:00	No
intestazioni	Intestazioni che vengono inviate alla richiesta. Ad esempio, per impostare il linguaggio e il tipo in una richiesta: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Stringa (o un'espressione con l'elemento resultType della stringa)	No
corpo	Rappresenta il payload inviato all'endpoint.	Stringa (o espressione con l'elemento resultType della stringa). Vedere lo schema del payload della richiesta nella sezione Schema del payload della richiesta.	Obbligatorio per i metodi POST/PUT/PATCH. Facoltativo per il metodo DELETE.
autenticazione	Metodo di autenticazione usato per chiamare l'endpoint. I tipi supportati sono "Basic, Client Certificate, System-Assigned Managed Identity, User-assigned Managed Identity, Service Principal". Per altre informazioni, vedere la sezione Autenticazione . Se l'autenticazione non è necessaria, escludere questa proprietà.	Stringa (o un'espressione con l'elemento resultType della stringa)	No
turnOffAsync	Opzione per disabilitare la chiamata del campo HTTP GET sul percorso nell'intestazione della risposta di una risposta HTTP 202. Se impostato su true, interrompe la chiamata di HTTP GET nella posizione HTTP specificata nell'intestazione della risposta. Se impostato su false, continua a richiamare la chiamata HTTP GET nel percorso specificato nelle intestazioni di risposta HTTP.	I valori consentiti sono false (impostazione predefinita) e true.	No
disableCertValidation	Rimuove la convalida del certificato lato server (scelta non consigliata, a meno che non ci si connetta a un server attendibile che non usi un certificato CA standard).	I valori consentiti sono false (impostazione predefinita) e true.	No
datasets	Elenco di set di dati passato all'endpoint.	Matrice di riferimenti a set di dati. Può essere una matrice vuota.	Sì
linkedServices	Elenco dei servizi collegati passato all'endpoint.	Matrice di riferimenti a servizi collegati. Può essere una matrice vuota.	Sì
connectVia	Runtime di integrazione da usare per la connessione all'archivio dati. È possibile usare il runtime di integrazione di Azure o il runtime di integrazione self-hosted (se l'archivio dati si trova in una rete privata). Se questa proprietà non è specificata, il servizio usa il runtime di integrazione di Azure predefinito.	Informazioni di riferimento sul runtime di integrazione.	No

Nota

Gli endpoint REST che l'attività Web richiama devono restituire una risposta di tipo JSON. L'attività raggiungerà il timeout a 1 minuto con un errore se non riceve una risposta dall'endpoint. Per gli endpoint che supportano il modello Request-Reply asincrono, l'attività Web continuerà ad attendere senza timeout (fino a 7 giorni) o fino al completamento del processo da parte degli endpoint.

La tabella seguente indica i requisiti per il contenuto JSON:

Tipo di valore	Corpo della richiesta	Corpo della risposta
Oggetto JSON	Supportato	Supportato
Matrice JSON	Aggiunta del supporto per Attualmente, le matrici JSON non funzionano a causa di un bug. È in corso una correzione.	Non supportato
Valore JSON	Supportato	Non supportato
Tipo non JSON	Non supportato	Non supportato

Authentication

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

Nota

Se la data factory o l'area di lavoro di Synapse è configurata con un repository Git, è necessario archiviare le credenziali in Azure Key Vault per usare l'autenticazione del certificato client o di base. Il servizio non archivia le password in Git.

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 il stringa di connessione SQL di Azure per connettersi al server SQL logico e restituisce il nome dell'istanza di SQL Server.

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

Vedere altre attività del flusso di controllo supportate:

Attività Web in Azure Data Factory e Azure Synapse Analytics

Creare un'attività Web con l'interfaccia utente

Sintassi

Proprietà del tipo

Authentication

None

Di base

Certificato client

Identità gestita

Schema del payload della richiesta

Esempio

Definizione della pipeline

Valori dei parametri della pipeline

Codice endpoint del servizio Web

Contenuto correlato

Risorse aggiuntive