Come usare parametri, espressioni e funzioni in Azure Data Factory

  • Articolo

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 .

In questo documento ci si concentrerà principalmente sull'apprendimento dei concetti fondamentali con vari esempi per esplorare la possibilità di creare pipeline di dati con parametri all'interno di Azure Data Factory. La parametrizzazione e le espressioni dinamiche sono tali aggiunte significative ad ADF, perché possono risparmiare una notevole quantità di tempo e consentire una soluzione extract, transform, load (ETL) molto più flessibile o Extract, Load, Transform (ELT), che ridurrà notevolmente il costo della manutenzione della soluzione e velocizza l'implementazione di nuove funzionalità nelle pipeline esistenti. Questi vantaggi sono causati dal fatto che la parametrizzazione riduce al minimo la quantità di hardcoded e aumenta il numero di oggetti e processi riutilizzabili in una soluzione.

Interfaccia utente e parametri di Azure Data Factory

Se non si ha esperienza con l'utilizzo dei parametri di Azure Data Factory nell'interfaccia utente di Azure Data Factory, vedere Interfaccia utente di Data Factory per i servizi collegati con parametri e interfaccia utente di Data Factory per la pipeline basata sui metadati con parametri per una spiegazione visiva.

Concetti relativi a parametri ed espressioni

È possibile usare i parametri per passare valori esterni in pipeline, set di dati, servizi collegati e flussi di dati. Dopo aver passato il parametro alla risorsa, non può essere modificato. Parametrizzando le risorse, è possibile riutilizzarle con valori diversi ogni volta. I parametri possono essere usati singolarmente o come parte delle espressioni. I valori JSON nella definizione possono essere letterali o espressioni che vengono valutate in fase di esecuzione.

Ad esempio:

"name": "value"

o

"name": "@pipeline().parameters.password"

Le espressioni possono trovarsi in qualsiasi punto in un valore stringa JSON e restituiscono sempre un altro valore JSON. In questo caso, la password è un parametro della pipeline nell'espressione. Se un valore JSON è un'espressione, il corpo dell'espressione viene estratto rimuovendo il simbolo di chiocciola (@). Se è necessaria una stringa letterale che inizia con @, deve essere preceduta da un carattere di escape tramite @@. L'esempio seguente illustra la modalità di valutazione delle espressioni.

Valore JSON Result
"parameters" Vengono restituiti i caratteri di tipo 'parameters'.
"parameters[1]" Vengono restituiti i caratteri di tipo 'parameters[1]'.
"@@" Viene restituita una stringa da 1 carattere che contiene \'\@\'.
" @" Viene restituita una stringa da 2 caratteri che contiene '\@\'.

Tramite una funzionalità denominata interpolazione delle stringhe, è possibile inserire le espressioni anche all'interno delle stringhe in cui viene eseguito il wrapping delle espressioni in @{ ... }. Ad esempio: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

Usando l'interpolazione delle stringhe, il risultato è sempre una stringa. Si supponga di aver definito myNumber come 42 e myString come foo:

Valore JSON Result
"@pipeline().parameters.myString" Restituisce foo come stringa.
"@{pipeline().parameters.myString}" Restituisce foo come stringa.
"@pipeline().parameters.myNumber" Restituisce 42 come numero.
"@{pipeline().parameters.myNumber}" Restituisce 42 come stringa.
"Answer is: @{pipeline().parameters.myNumber}" Restituisce la stringa Answer is: 42.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))" Restituisce la stringa Answer is: 42.
"Answer is: @@{pipeline().parameters.myNumber}" Restituisce la stringa Answer is: @{pipeline().parameters.myNumber}.

Esempi di utilizzo di parametri nelle espressioni

Esempio di espressione complessa

Nell'esempio seguente viene illustrato un esempio complesso che fa riferimento a un campo secondario avanzato dell'output dell'attività. Per fare riferimento a un parametro della pipeline che restituisce un campo secondario, usare la sintassi [] anziché l'operatore punto (.) (come nel caso di subfield1 e subfield2)

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

Editor di contenuto dinamico

L'editor di contenuto dinamico esegue automaticamente l'escape dei caratteri nel contenuto al termine della modifica. Ad esempio, il contenuto seguente nell'editor di contenuto è un'interpolazione di stringhe con due funzioni di espressione.

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

L'editor di contenuto dinamico converte il contenuto precedente in espressione "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". Il risultato di questa espressione è una stringa di formato JSON illustrata di seguito.

{
  "type": "Table",
  "name": "MYDATA"
}

Set di dati con parametri

Nell'esempio seguente BlobDataset accetta un parametro denominato path. Questo valore viene usato per impostare un valore per la proprietà folderPath usando l'espressione seguente: dataset().path.

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

Una pipeline con parametri

Nell'esempio seguente la pipeline accetta i parametri inputPath e outputPath. Il parametro path per il set di dati del BLOB con parametri viene impostato usando i valori di questi parametri. La sintassi usata è: pipeline().parameters.parametername.

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

Chiamata di funzioni all'interno di espressioni

È possibile chiamare le funzioni all'interno delle espressioni. Le sezioni seguenti forniscono informazioni sulle funzioni che è possibile usare in un'espressione.

Funzioni di stringa

Per eseguire operazioni con le stringhe, è possibile usare queste funzioni di stringa e alcune funzioni di raccolta. Le funzioni di stringa funzionano solo sulle stringhe.

Funzione di stringa Attività
concat Combina due o più stringhe e restituisce la stringa combinata.
endsWith Verifica se una stringa termina con la sottostringa specificata.
guid Generare un identificatore univoco globale (GUID) sotto forma di stringa.
indexOf Restituisce la posizione iniziale di una sottostringa.
lastIndexOf Restituisce la posizione iniziale o il valore di indice per l'ultima occorrenza di una sottostringa.
replace Sostituisce una sottostringa con la stringa specificata e restituisce la stringa aggiornata.
split Restituisce una matrice che contiene le sottostringhe, separate da virgole, da una stringa più grande in base al carattere delimitatore specificato nella stringa originale.
startsWith Verifica se una stringa inizia con una sottostringa specifica.
substring Restituisce i caratteri di una stringa, partendo dalla posizione specificata.
toLower Restituisce una stringa in formato minuscolo.
toUpper Restituisce una stringa in formato maiuscolo.
Trim Rimuove gli spazi iniziali e finali da una stringa e restituisce la stringa aggiornata.

Funzioni di raccolta

Per eseguire operazioni con le raccolte, generalmente matrici, stringhe e talvolta dizionari, è possibile usare queste funzioni di raccolta.

Funzione di raccolta Attività
contains Verifica se una raccolta include un elemento specifico.
empty Verifica se una raccolta è vuota.
first Restituisce il primo elemento di una raccolta.
intersection Restituisce una raccolta che contiene solo gli elementi comuni alle raccolte specificate.
join Restituisce una stringa con tutti gli elementi di una matrice, separati dal carattere specificato.
last Restituisce l'ultimo elemento di una raccolta.
length Restituisce il numero di elementi in una stringa o matrice.
skip Rimuove gli elementi dall'inizio di una raccolta e restituisce tutti gli altri elementi.
take Restituisce gli elementi dall'inizio di una raccolta.
union Restituisce una raccolta che contiene tutti gli elementi delle raccolte specificate.

Funzioni logiche

Queste funzioni sono utili all'interno delle condizioni e possono essere usate per valutare qualsiasi tipo di logica.

Funzione di confronto logico Attività
e Verifica se tutte le espressioni sono true.
equals Verifica se entrambi i valori sono equivalenti.
greater Verifica se il primo valore è maggiore del secondo valore.
greaterOrEquals Verifica se il primo valore è maggiore o uguale al secondo valore.
if Verifica se un'espressione è true o false. In base al risultato, restituisce un valore specificato.
less Verifica se il primo valore è minore del secondo valore.
lessOrEquals Verifica se il primo valore è minore o uguale al secondo valore.
not Verifica se un'espressione è false.
or Verifica se almeno un'espressione è true.

Funzioni di conversione

Queste funzioni vengono usate per la conversione tra ogni tipo nativo nel linguaggio:

  • stringa
  • integer
  • float
  • boolean
  • matrici
  • dizionari
Funzione di conversione Attività
array Restituisce una matrice da un singolo input specificato. Per più input, vedere createArray.
base64 Restituisce la versione di una stringa con codifica base64.
base64ToBinary Restituisce la versione binaria di una stringa con codifica base64.
base64ToString Restituisce la versione stringa di una stringa con codifica base64.
binary Restituisce la versione binaria di un valore di input.
bool Restituisce la versione booleana di un valore di input.
coalesce Restituisce il primo valore non Null da uno o più parametri.
createArray Restituisce una matrice da più input.
dataUri Restituisce l'URI dati di un valore di input.
dataUriToBinary Restituisce la versione binaria di un URI dati.
dataUriToString Restituisce la versione stringa di un URI dati.
decodeBase64 Restituisce la versione stringa di una stringa con codifica base64.
decodeDataUri Restituisce la versione binaria di un URI dati.
decodeUriComponent Restituisce una stringa che sostituisce i caratteri di escape con le versioni decodificate.
encodeUriComponent Restituisce una stringa che sostituisce i caratteri non sicuri dell'URL con caratteri di escape.
float Restituisce un numero a virgola mobile per un valore di input.
int Restituisce la versione integer di una stringa.
json Restituisce il valore o l'oggetto di tipo JSON (JavaScript Object Notation ) per una stringa o un elemento XML.
string Restituisce la versione stringa di un valore di input.
uriComponent Restituisce la versione codificata in formato URI per un valore di input sostituendo i caratteri non sicuri dell'URL con caratteri di escape.
uriComponentToBinary Restituisce la versione binaria di una stringa con codifica URI.
uriComponentToString Restituisce la versione stringa di una stringa con codifica URI.
xml Restituisce la versione XML di una stringa.
xpath Verifica nel codice XML la presenza di nodi o valori che corrispondono a un'espressione XPath (XML Path Language) e restituisce i nodi o i valori corrispondenti.

Funzioni matematiche

Queste funzioni possono essere usate per qualsiasi tipo di numero, ovvero numeri interi e numeri a virgola mobile.

Funzione matematica Attività
add Restituisce il risultato della somma di due numeri.
div Restituisce il risultato della divisione di due numeri.
max Restituisce il valore più alto di un set di numeri o una matrice.
min Restituisce il valore più basso di un set di numeri o una matrice.
mod Restituisce il resto della divisione di due numeri.
mul Restituisce il prodotto della moltiplicazione di due numeri.
rand Restituisce un numero intero casuale da un intervallo specificato.
range Restituisce una matrice di valori interi che inizia da un valore intero specificato.
sub Restituisce il risultato della sottrazione del secondo numero dal primo.

Funzioni di data

Funzione di data e ora Attività
addDays Aggiunge un numero di giorni a un timestamp.
addHours Aggiunge un numero di ore a un timestamp.
addMinutes Aggiunge un numero di minuti a un timestamp.
addSeconds Aggiunge un numero di secondi a un timestamp.
addToTime Aggiunge un numero di unità di tempo a un timestamp. Vedere anche getFutureTime.
convertFromUtc Converte un timestamp da UTC (Universal Time Coordinated) al fuso orario di destinazione.
convertTimeZone Converte un timestamp dal fuso orario di origine al fuso orario di destinazione.
convertToUtc Converte un timestamp dal fuso orario di origine a UTC (Universal Time Coordinated).
dayOfMonth Restituisce il giorno del componente di mese di un timestamp.
dayOfWeek Restituisce il giorno del componente settimana di un timestamp.
dayOfYear Restituisce il giorno del componente anno di un timestamp.
formatDateTime Restituisce il timestamp come stringa in formato facoltativo.
getFutureTime Restituisce il timestamp corrente più le unità di tempo specificate. Vedere anche addToTime.
getPastTime Restituisce il timestamp corrente meno le unità di tempo specificate. Vedere anche subtractFromTime.
startOfDay Restituisce l'inizio del giorno per un timestamp.
startOfHour Restituisce l'inizio dell'ora per un timestamp.
startOfMonth Restituisce l'inizio del mese per un timestamp.
subtractFromTime Sottrae un numero di unità di tempo da un timestamp. Vedere anche getPastTime.
ticks Restituisce il valore della proprietà ticks per un timestamp specificato.
utcNow Restituisce il timestamp corrente come stringa.

Esempi dettagliati per la pratica

Pipeline di copia dettagliata di Azure Data Factory con parametri

Questa esercitazione sul passaggio del parametro della pipeline di copia di Azure Data Factory illustra come passare parametri tra una pipeline e un'attività e tra le attività.

Pipeline dettagliata del flusso di dati per mapping con parametri

Per un esempio completo su come usare i parametri nel flusso di dati, seguire Mapping del flusso di dati con parametri .

Pipeline dettagliata basata sui metadati con parametri

Seguire la pipeline basata sui metadati con i parametri per altre informazioni su come usare i parametri per progettare pipeline guidate dai metadati. Questo è un caso d'uso comune per i parametri.

Contenuto correlato

Per un elenco di variabili di sistema che è possibile usare nelle espressioni, vedere Variabili di sistema.