Attività webhook in Azure Data Factory

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 .

Un'attività webhook può controllare l'esecuzione delle pipeline tramite codice personalizzato. Con l'attività webhook, il codice può chiamare un endpoint e passarlo a un URL di callback. L'esecuzione della pipeline attende la chiamata di callback prima di procedere all'attività successiva.

Importante

L'attività WebHook consente ora di visualizzare lo stato degli errori e i messaggi personalizzati all'attività e alla pipeline. Impostare reportStatusOnCallBack su true e includere StatusCode e Error nel payload di callback. Per altre informazioni, vedere la sezione Note aggiuntive.

Creare un'attività webhook con l'interfaccia utente

Per usare un'attività webhook in una pipeline, seguire questa procedura:

Cercare Webhook nel riquadro Attività pipeline e trascinare un'attività webhook nell'area di disegno della pipeline.
Selezionare la nuova attività webhook nell'area di disegno se non è già selezionata e la relativa scheda Impostazioni per modificarne i dettagli.
Specificare un URL per il webhook, 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": "MyWebHookActivity",
    "type": "WebHook",
    "typeProperties": {
        "method": "POST",
        "url": "<URLEndpoint>",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": {
            "key": "value"
        },
        "timeout": "00:10:00",
        "reportStatusOnCallBack": false,
        "authentication": {
            "type": "ClientCertificate",
            "pfx": "****",
            "password": "****"
        }
    }
}

Proprietà del tipo

Proprietà	Descrizione	Valori consentiti	Obbligatorio
name	Nome dell'attività webhook.	Stringa	Sì
type	Deve essere impostato su "WebHook".	Stringa	Sì
method	Metodo DELL'API REST per l'endpoint di destinazione.	String. Il tipo supportato è "POST".	Sì
url	Endpoint e percorso di destinazione.	Stringa o espressione con il valore resultType di una stringa.	Sì
headers	Intestazioni che vengono inviate alla richiesta. Di seguito è riportato un esempio che imposta la lingua e il tipo in una richiesta: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Stringa o espressione con il valore resultType di una stringa.	Sì. Un'intestazione `Content-Type` come `"headers":{ "Content-Type":"application/json"}` è obbligatoria.
body	Rappresenta il payload inviato all'endpoint.	JSON valido o un'espressione con il valore resultType di JSON. Vedere Schema del payload della richiesta per lo schema del payload della richiesta.	Sì
autenticazione	Metodo di autenticazione usato per chiamare l'endpoint. I tipi supportati sono "Basic" e "ClientCertificate". Per altre informazioni, vedere Autenticazione. Se l'autenticazione non è necessaria, escludere questa proprietà.	Stringa o espressione con il valore resultType di una stringa.	No
timeout	Per quanto tempo l'attività attende che venga richiamato il callback specificato da callBackUri . Il valore predefinito è 10 minuti ("00:10:00"). I valori hanno il formato TimeSpan d.hh:mm:ss.	Stringa	No
Segnalare lo stato del callback	Consente a un utente di segnalare lo stato di errore di un'attività webhook.	Boolean	No

Authentication

Un'attività webhook supporta i tipi di autenticazione seguenti.

None

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

Di base

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

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

Certificato client

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

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

Identità gestita

Usare l'identità gestita per la data factory o l'area di lavoro di Synapse per specificare l'URI della risorsa per cui viene richiesto il token di accesso. Per chiamare l'API di gestione delle risorse di Azure, usare https://management.azure.com/. Per altre informazioni sul funzionamento delle identità gestite, vedere la panoramica delle identità gestite per le risorse di Azure.

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

Nota

Se il servizio è configurato con un repository Git, è necessario archiviare le credenziali in Azure Key Vault per usare l'autenticazione di base o del certificato client. Il servizio non archivia le password in Git.

Note aggiuntive

Il servizio passa la proprietà aggiuntiva callBackUri nel corpo inviato all'endpoint URL. Il servizio prevede che questo URI venga richiamato prima del valore di timeout specificato. Se l'URI non viene richiamato, l'attività non riesce con lo stato "TimedOut".

L'attività webhook ha esito negativo quando la chiamata all'endpoint personalizzato non riesce. Qualsiasi messaggio di errore può essere aggiunto al corpo del callback e usato in un'attività successiva.

Per ogni chiamata API REST, il client raggiunge il timeout se l'endpoint non risponde entro un minuto. Questo comportamento è la procedura consigliata HTTP standard. Per risolvere questo problema, implementare un modello 202. Nel caso corrente, l'endpoint restituisce 202 (accettato) e il client esegue il polling.

Il timeout di un minuto nella richiesta non ha nulla a che fare con il timeout dell'attività. Quest'ultimo viene usato per attendere il callback specificato da callbackUri.

Il corpo passato all'URI di callback deve essere JSON valido. Impostare l'intestazione Content-Type su application/json.

Quando si utilizza lo stato del report sulla proprietà di callback , è necessario aggiungere il codice seguente al corpo quando si effettua il callback:

{
    "Output": {
        // output object is used in activity output
        "testProp": "testPropValue"
    },
    "Error": {
        // Optional, set it when you want to fail the activity
        "ErrorCode": "testErrorCode",
        "Message": "error message to show in activity error"
    },
    "StatusCode": "403" // when status code is >=400, activity is marked as failed
}

Vedere le seguenti attività di flusso di controllo supportate: