Leggere in inglese

Condividi tramite


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 che vengono valutate in fase di esecuzione.

Le espressioni possono trovarsi in qualsiasi punto in un valore stringa e generano sempre un altro valore stringa. In questo caso, la password è un parametro della pipeline nell'espressione. Se un valore del parametro è un'espressione, il corpo dell'espressione viene estratto rimuovendo il simbolo di chiocciola (@). Se è necessaria una stringa letterale che inizia con @, occorre che la stringa sia preceduta da un carattere di escape usando @@. 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:

"First Name: @{pipeline().parameters.firstName} Last Name: @{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:

Screenshot che mostra l'editor di parametri nelle pagine delle proprietà per una pipeline.

È 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.

Screenshot che mostra la scheda Origine delle pagine delle proprietà di un'attività di copia, evidenziando l'opzione Aggiungi contenuto dinamico.

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.

Screenshot che mostra la finestra Aggiungi contenuto dinamico con un parametro della pipeline selezionato.

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 dell'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 Synapse in cui è in esecuzione la 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 richiama 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. Notare il punto interrogativo dopo @pipeline()
@pipeline()?.TriggeredByPipelineRunId Eseguire l’ID 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. Notare 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, ad esempio 2017-06-01T22:20:00.4061448Z.

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:

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