Parametri per Data Factory in Microsoft Fabric
Questo documento descrive come usare i parametri 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.
È 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} . |
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.
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*
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
È 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.
È 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
.
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. |
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. |
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. |
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. |
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. |
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. |