Attività Web in Azure Data Factory e Azure Synapse Analytics

Articolo
09/25/2024

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi all-in-one per le aziende. Microsoft Fabric copre tutto, dallo spostamento dati al data science, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Vedere le informazioni su come iniziare una nuova prova gratuita!

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 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 relativa 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	Obbligatoria
name	Nome dell'attività Web	String	Sì
type	Deve essere impostato su WebActivity.	String	Sì
metodo	Metodo 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.	Obbligatoria per i metodi POST, PUT e PATCH. Facoltativo per il metodo DELETE.
autenticazione	Metodo di autenticazione usato per chiamare l'endpoint. I tipi supportati sono "Basic, certificato client, identità gestita assegnata dal sistema, identità gestita assegnata dall'utente, entità servizio". 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 “vero”, interrompe la chiamata di HTTP GET nella posizione HTTP specificata nell'intestazione della risposta. Se impostato su “falso”, continua a richiamare la chiamata HTTP GET nel percorso specificato nelle intestazioni di risposta HTTP.	I valori consentiti sono false (predefinito) e true.	No
disableCertValidation	Rimuove la convalida del certificato sul lato server (non è consigliato, a meno che non ci si connetta a un server affidabile che non utilizza un certificato CA standard).	I valori consentiti sono false (predefinito) 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 Azure Integration Runtime o un 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 Richiesta/risposta asincrona, l'attività Web continuerà ad attendere senza timeout (fino a 7 giorni) o fino a quando gli endpoint segnalano il completamento del processo.

La tabella seguente indica i requisiti per il contenuto JSON:

Tipo di valore	Corpo della richiesta	Corpo della risposta
Oggetto JSON	Supportata	Supportata
Matrice JSON	Aggiunta del supporto per Al momento, le matrici JSON non funzionano per via di un bug. È in corso una correzione.	Non supportato
Valore JSON	Supportata	Non supportato
Tipo non JSON	Non supportato	Non supportato

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

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.

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

Vedere altre attività del flusso di controllo supportate:

Condividi tramite

Attività Web in Azure Data Factory e Azure Synapse Analytics

Creare un'attività Web con l'interfaccia utente

Sintassi

Proprietà del tipo

Autenticazione

None

Di base

Certificato client

Identità gestita

Entità servizio

Schema del payload della richiesta

Esempio

Definizione della pipeline

Valori dei parametri della pipeline

Codice endpoint del servizio Web

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Attività Web in Azure Data Factory e Azure Synapse Analytics

Creare un'attività Web con l'interfaccia utente

Sintassi

Proprietà del tipo

Autenticazione

None

Di base

Certificato client

Identità gestita

Entità servizio

Schema del payload della richiesta

Esempio

Definizione della pipeline

Valori dei parametri della pipeline

Codice endpoint del servizio Web

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive