Parametri per Data Factory in Microsoft Fabric

Questo documento descrive come usare i parametri nelle pipeline per Data Factory in Fabric.

Come usare parametri, espressioni e funzioni nelle pipeline per Data Factory in Fabric

In questo documento viene illustrato come apprendere concetti fondamentali con vari esempi per esplorare la possibilità di creare pipeline di dati con parametri all'interno di Data Factory in Fabric. La parametrizzazione e le espressioni dinamiche possono risparmiare una notevole quantità di tempo e consentire una soluzione estrazione, trasformazione, caricamento (ETL) o estrazione, caricamento, trasformazione (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.

Concetti relativi a parametri ed espressioni

È possibile usare i parametri per passare valori esterni nelle pipeline. 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 dei parametri nella definizione possono essere letterali o espressioni valutate in fase di esecuzione.

Le espressioni possono essere visualizzate ovunque in un valore stringa e generare sempre un altro valore stringa. In questo caso, la password è un parametro della pipeline nell'espressione. Se un valore di parametro è un'espressione, il corpo dell'espressione viene estratto rimuovendo il simbolo at-sign (@). 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 parametro	Risultato
"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, la stringa seguente include valori di parametro e valori stringa letterali:

"Nome: @{pipeline().parameters.firstName} Cognome: @{pipeline().parameters.lastName}"

Usando l'interpolazione delle stringhe, il risultato è sempre una stringa. Ad esempio, se è stato definito myNumber come 42 e myString come foo:

Valore parametro	Risultato
"@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

Creazione e uso di parametri

Per creare parametri, selezionare lo sfondo dell'area di disegno dell'editor della pipeline e quindi la scheda Parametri della finestra delle proprietà nella parte inferiore. Selezionare il pulsante + Nuovo per aggiungere un nuovo parametro alla pipeline, assegnare un nome, un tipo di dati e un valore predefinito:

È quindi possibile usare il parametro in qualsiasi punto della pipeline in cui è supportato il contenuto dinamico. In questo esempio, il parametro viene usato per fornire dinamicamente il nome di un archivio dati Lakehouse nella scheda Origine delle pagine delle proprietà di un'attività di copia.

Viene visualizzata la finestra Aggiungi contenuto dinamico, che consente di specificare qualsiasi tipo di contenuto dinamico, inclusi parametri, variabili di sistema, funzioni o variabili della pipeline. In questo esempio viene selezionato il parametro definito in precedenza e la finestra del contenuto dinamico viene popolata automaticamente con l'espressione corretta per fare riferimento al parametro.

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 una funzione di espressione:

@{toUpper('myData')}

L'editor di contenuto dinamico converte il contenuto precedente nell'espressione seguente:

MYDATA

Uso di funzioni e variabili nelle espressioni

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

Variabili di ambito della pipeline

È possibile fare riferimento a queste variabili di sistema in un punto qualsiasi della pipeline JSON.

Nome variabile	Descrizione
@pipeline().DataFactory	Nome dei dati o dell'area di lavoro di Synapse in cui è in esecuzione l'esecuzione della pipeline
@pipeline().Pipeline	Nome della pipeline
@pipeline().RunId	ID dell'esecuzione della pipeline specifica
@pipeline().TriggerId	ID del trigger che ha richiamato la pipeline
@pipeline().TriggerName	Nome del trigger che ha richiamato la pipeline
@pipeline().TriggerTime	Ora dell'esecuzione del trigger che ha richiamato la pipeline. Questo è il momento in cui il trigger viene effettivamente attivato per richiamare l'esecuzione della pipeline e può differire leggermente dall'ora pianificata del trigger.
@pipeline().GroupId	ID del gruppo a cui appartiene l'esecuzione della pipeline.
@pipeline()?. TriggeredByPipelineName	Nome della pipeline che attiva l'esecuzione della pipeline. Applicabile quando l'esecuzione della pipeline viene attivata da un'attività ExecutePipeline. Restituisce Null se usato in altre circostanze. Annotare il punto interrogativo dopo @pipeline()
@pipeline()?. TriggeredByPipelineRunId	ID esecuzione della pipeline che attiva l'esecuzione della pipeline. Applicabile quando l'esecuzione della pipeline viene attivata da un'attività ExecutePipeline. Restituisce Null se usato in altre circostanze. Annotare il punto interrogativo dopo @pipeline()

Nota

Le variabili di sistema di data/ora correlate al trigger (sia negli ambiti della pipeline che dei trigger) restituiscono date UTC in formato ISO 8601, 2017-06-01T22:20:00.4061448Zad esempio .

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.
oppure	Verifica se almeno un'espressione è true.

Funzioni di conversione

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

• string
• 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.

Contenuto correlato

• Linguaggio delle espressioni