Parametri per Data Factory in Microsoft Fabric

Questo articolo illustra come usare i parametri nelle pipeline di Data Factory in Fabric in modo da poter creare flussi di lavoro flessibili e riutilizzabili.

Usare parametri, espressioni e funzioni nelle pipeline di Data Factory

Questa sezione illustra le nozioni di base sulla creazione di pipeline con parametri in Data Factory per Fabric, usando esempi chiari lungo il percorso. I parametri e le espressioni dinamiche fanno risparmiare tempo e consentono di creare soluzioni flessibili ETL (Extract, Transform, Load) o ELT (Extract, Load, Transform). Riducono il hardcoded e consentono di riutilizzare oggetti e processi, semplificando la manutenzione delle pipeline e consentendo di distribuire più rapidamente nuove funzionalità.

Concetti relativi a parametri ed espressioni

È possibile usare i parametri per passare valori esterni nelle pipeline. Dopo aver impostato un parametro, il relativo valore rimane invariato durante l'esecuzione. I parametri consentono di riutilizzare la stessa pipeline con valori diversi ogni volta. È possibile usare parametri personalizzati o all'interno di espressioni, con valori fissi o calcolati durante l'esecuzione della pipeline.

Le espressioni possono essere posizionate ovunque in un valore stringa e restituire sempre un altro valore stringa. Ad esempio, se si usa @password, la pipeline considera la password come parametro. Se il valore è un'espressione, rimuovere @ per ottenere il contenuto effettivo. Per usare una stringa che inizia con @, eseguire l'escape digitando @@. Negli esempi seguenti viene illustrato come funziona in pratica.

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

Le espressioni possono essere visualizzate anche all'interno di stringhe tramite l'interpolazione di stringhe, in cui si esegue 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}"

L'interpolazione di stringhe restituisce sempre una stringa. Ad esempio, se si definisce myNumber come 42 e myString come foo:

Valore del parametro 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 sotto forma di stringa.
"La risposta è: @{pipeline().parameters.myNumber}" Restituisce la stringa Answer is: 42.
"@concat('La risposta è: ', string(pipeline().parameters.myNumber))" Restituisce la stringa Answer is: 42.
La risposta è: @@{pipeline().parameters.myNumber} Restituisce la stringa Answer is: @{pipeline().parameters.myNumber}.

Esempi di espressioni di parametro

Creare e usare parametri

Per creare parametri, selezionare lo sfondo dell'area di disegno dell'editor della pipeline e quindi selezionare la scheda Parametri della finestra delle proprietà nella parte inferiore. Selezionare + Nuovo per aggiungere un parametro alla pipeline e 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 ovunque la pipeline supporti il contenuto dinamico. In questo esempio il parametro fornisce dinamicamente il nome di un archivio dati lakehouse nella scheda Origine delle pagine delle proprietà di un attività Copy.

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

Verrà visualizzata la finestra di Aggiungi contenuto dinamico. Usarlo per specificare qualsiasi tipo di contenuto dinamico, inclusi parametri, variabili di sistema, funzioni o variabili della pipeline. In questo esempio si seleziona il parametro definito in precedenza e la finestra del contenuto dinamico viene popolata automaticamente con l'espressione corretta per farvi riferimento.

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

Parametrizzare le connessioni

Per parametrizzare le connessioni nelle pipeline, usare l'identificatore univoco globale (GUID) della connessione che si vuole sostituire in modo dinamico.

  1. Prima di modificare dinamicamente la connessione nella pipeline, ottenere il GUID della connessione che si vuole impostare.
  2. Passare a Impostazioni>Gestisci connessioni e gateway.
  3. Individua il nome della connessione e seleziona i puntini di sospensione (...) accanto ad esso.
  4. Selezionare Impostazioni e copiare l'ID connessione.
  5. Incollare il GUID in un parametro stringa e fare riferimento a tale parametro nell'espressione dinamica.

Esempio di espressione complessa

L'espressione seguente fa riferimento a un sottocampo profondo dell'output dell'attività. Per fare riferimento a un parametro della pipeline che viene valutato come un sottocampo, usare la sintassi [] anziché l'operatore punto (.), come in 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

Usare 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 ovunque nella pipeline JSON.

Nome variabile Description
@pipeline().DataFactory Nome dell'area di lavoro 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'attivazione del trigger che ha richiamato la pipeline. Questo valore è l'ora in cui il trigger è stato effettivamente attivato per richiamare l'esecuzione della pipeline e potrebbe differire leggermente dall'ora pianificata del trigger.
@pipeline().GroupId ID del gruppo a cui è associata l'esecuzione della pipeline. In Microsoft Fabric un gruppo è una raccolta di risorse correlate gestite insieme. I gruppi organizzano e controllano l'accesso alle risorse, semplificando la gestione delle autorizzazioni e il monitoraggio delle attività tra più pipeline.
@pipeline()?.TriggeredByPipelineName Nome della pipeline che attiva l’esecuzione della pipeline. Si applica quando un'attività Execute Pipeline avvia l'esecuzione della pipeline. Restituisce Null in altri casi. Prendere nota del punto interrogativo dopo @pipeline().
@pipeline()?.TriggeredByPipelineRunId L'ID di esecuzione della pipeline che avvia l'esecuzione della pipeline. Si applica quando un'attività 'Execute Pipeline' avvia l'esecuzione della pipeline. Viene valutato come Null negli altri casi. Prendere nota del punto interrogativo dopo @pipeline().

Note

Le variabili di sistema relative alla data e all'ora del trigger (sia nell'ambito della pipeline sia in quello del trigger) restituiscono date UTC (Coordinated Universal Time) nel formato ISO 8601, ad esempio 2017-06-01T22:20:00.4061448Z.

Funzioni stringa

Per lavorare con le stringhe, usa queste funzioni per le stringhe e anche alcune funzioni per le collezioni. Le funzioni di stringa funzionano solo sulle stringhe.

Funzione di stringa Task
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 usare raccolte come matrici, stringhe e dizionari, usare queste funzioni di raccolta.

Funzione di raccolta Task
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

Usare queste funzioni all'interno di condizioni per valutare qualsiasi tipo di logica.

Funzione di confronto logico Task
and 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 è vera.

Funzioni di conversione

Usare queste funzioni per eseguire la conversione tra ognuno dei tipi nativi nel linguaggio:

  • string
  • integer
  • float
  • boolean
  • arrays
  • dictionaries
Funzione di conversione Task
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 dei dati di un valore di input.
dataUriToBinary Restituisce la versione binaria di un URI dati.
dataUriToString Restituisce la versione in stringa di un URI di 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

Usare queste funzioni con entrambi i tipi di numeri: numeri interi e float.

Funzione matematica Task
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 e ora

Funzione di data e ora Task
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 Convertire un timestamp dall'ora UTC (Coordinated Universal Time) al fuso orario di destinazione.
convertTimeZone Converte un timestamp dal fuso orario di origine al fuso orario di destinazione.
convertToUtc Converti un timestamp dal fuso orario di origine al Tempo coordinato universale (UTC).
dayOfMonth Restituisce la componente giorno del mese da un timestamp.
dayOfWeek Restituisce il giorno del componente settimana di un timestamp.
dayOfYear Restituisce il giorno dell'anno da 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.

Contenuti correlati

  • Last updated on