Lire en anglais

Partager via


Paramètres pour Data Factory dans Microsoft Fabric

Ce document explique comment utiliser des paramètres dans vos pipelines pour Data Factory dans Fabric.

Guide pratique pour utiliser des paramètres, des expressions et des fonctions dans les pipelines pour Data Factory dans Fabric

Dans ce document, nous allons nous concentrer sur les concepts fondamentaux avec divers exemples pour explorer la possibilité de créer des pipelines de données paramétrables dans Data Factory dans Fabric. Le paramétrage et les expressions dynamiques permettent d’économiser beaucoup de temps et de tenir compte d’une solution ETL (extraction, transformation, chargement) ou ELT (extraction, chargement, transformation) bien plus souple, ce qui réduit considérablement le coût de maintenance des solutions et accélère l’implémentation de nouvelles fonctionnalités dans les pipelines existants. Ces gains sont liés au fait que la paramétrisation réduit la quantité de codage en dur et augmente le nombre d’objets et de processus réutilisables dans une solution.

Concepts des paramètres et des expressions

Vous pouvez utiliser des paramètres pour transmettre des valeurs externes dans les pipelines. Une fois que le paramètre a été transmis à la ressource, il ne peut pas être modifié. En paramétrisant des ressources, vous pouvez les réutiliser avec des valeurs différentes chaque fois. Les paramètres peuvent être utilisés individuellement ou dans le cadre d’expressions. Les valeurs de paramètre indiquées dans la définition peuvent être littérales. Il peut également s’agir d’expressions évaluées lors de l’exécution du runtime.

Les expressions peuvent apparaître n’importe où dans une valeur de chaîne et génèrent toujours une autre valeur de chaîne. Ici, password est un paramètre de pipeline dans l’expression. Si une valeur de paramètre est une expression, le corps de l’expression est extrait en supprimant le signe arobase (@). Si une chaîne littérale devant commencer par @ est nécessaire, elle doit être placée dans une séquence d’échappement en utilisant @@. Les exemples suivants montrent comment les expressions sont évaluées.

Valeur de paramètre Résultats
« parameters » Les caractères « parameters » sont retournés.
« parameters[1] » Les caractères « parameters[1] » sont retournés.
"@@" Une chaîne de 1 caractère contenant \«\@\» est retournée.
" @" Une chaîne de 2 caractères contenant \«  \@  \» est retournée.

Des expressions peuvent également apparaître dans des chaînes, qui utilisent une fonctionnalité appelée interpolation de chaîne où les expressions sont encapsulées dans @{ ... }. Par exemple, la chaîne suivante inclut des valeurs de paramètre et des valeurs de chaîne littérale :

"Prénom : @{pipeline().parameters.firstName} Nom de famille : @{pipeline().parameters.lastName}"

En utilisant une interpolation de chaîne, le résultat est toujours une chaîne. Par exemple, si vous avez défini myNumber comme 42 et myString comme foo :

Valeur de paramètre Résultats
"@pipeline().parameters.myString" Retourne foo en tant que chaîne.
"@{pipeline().parameters.myString}" Retourne foo en tant que chaîne.
"@pipeline().parameters.myNumber" Retourne 42 en tant que nombre.
"@{pipeline().parameters.myNumber}" Retourne 42 en tant que chaîne.
"Answer is: @{pipeline().parameters.myNumber}" Retourne la chaîne Answer is: 42.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))" Retourne la chaîne Answer is: 42.
"Answer is: @@{pipeline().parameters.myNumber}" Retourne la chaîne Answer is: @{pipeline().parameters.myNumber}.

Exemples d’utilisation de paramètres dans les expressions

Création et utilisation de paramètres

Pour créer des paramètres, sélectionnez l’arrière-plan du canevas de l’éditeur de pipeline, puis l’onglet Paramètres de la fenêtre des propriétés en bas. Sélectionnez le bouton + Nouveau pour ajouter un nouveau paramètre au pipeline, donnez-lui un nom, un type de données et une valeur par défaut :

Screenshot showing the Parameters editor on the properties pages for a pipeline.

Vous pouvez ensuite utiliser le paramètre n’importe où dans votre pipeline où le contenu dynamique est pris en charge. Dans cet exemple, le paramètre est utilisé pour fournir de façon dynamique le nom d’un magasin de données Lakehouse sous l’onglet Source des pages de propriétés d’une activité Copy.

Screenshot showing the Source tab of a copy activity's property pages, highlighting the Add dynamic content option.

La fenêtre Ajouter du contenu dynamique s’affiche, ce qui vous permet de spécifier n’importe quel type de contenu dynamique, y compris des paramètres, des variables système, des fonctions ou des variables de pipeline. Dans cet exemple, le paramètre précédemment défini est sélectionné et la fenêtre de contenu dynamique est automatiquement remplie avec l’expression correcte pour référencer le paramètre.

Screenshot showing the Add dynamic content window with a pipeline parameter selected.

Exemple d’expression complexe

L’exemple ci-dessous montre un exemple complexe qui fait référence à un sous-champ profond d’une sortie d’activité. Pour faire référence à un paramètre de pipeline qui prend la valeur d’un sous-champ, utilisez la syntaxe [] au lieu de l’opérateur point(.) (comme dans le cas de subfield1 et subfield2)

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

Éditeur de contenu dynamique

L'éditeur de contenu dynamique échappe automatiquement les caractères de votre contenu lorsque vous avez terminé l'édition. Par exemple, le contenu suivant dans l’éditeur de contenu est une interpolation de chaîne avec une fonction d’expression :

@{toUpper('myData')}

L’éditeur de contenu dynamique convertit le contenu ci-dessus en l’expression suivante :

MYDATA

Utilisation de fonctions et de variables dans des expressions

Vous pouvez appeler des fonctions et utiliser des variables dans des expressions. Les sections suivantes fournissent des informations sur les fonctions qui peut être utilisées dans une expression.

Variables d'étendue du pipeline

Ces variables système peuvent être référencées n’importe où dans le code JSON de pipeline.

Nom de la variable Description
@pipeline().DataFactory Nom de la fabrique de données ou de l’espace de travail Synapse dans lequel s’effectue l’exécution de pipeline
@pipeline().Pipeline Nom du pipeline
@pipeline().RunId ID de l’exécution du pipeline spécifique
@pipeline().TriggerId ID du déclencheur qui a appelé le pipeline.
@pipeline().TriggerName Nom du déclencheur qui a appelé le pipeline.
@pipeline().TriggerTime Heure de l’exécution du déclencheur qui a appelé le pipeline. Il s’agit de l’heure à laquelle le déclencheur s’est réellement déclenché pour appeler l’exécution du pipeline. Elle peut différer légèrement de l’heure planifiée du déclencheur.
@pipeline().GroupId ID du groupe auquel appartient l’exécution du pipeline.
@pipeline()?.TriggeredByPipelineName Nom du pipeline qui déclenche l’exécution du pipeline. Applicable lorsque l’exécution du pipeline est déclenchée par une activité ExecutePipeline. Donne la valeur Null lorsqu’elle est utilisée dans d’autres circonstances. Notez le point d’interrogation après @pipeline()
@pipeline()?.TriggeredByPipelineRunId ID d’exécution du pipeline qui déclenche l’exécution du pipeline. Applicable lorsque l’exécution du pipeline est déclenchée par une activité ExecutePipeline. Donne la valeur Null lorsqu’elle est utilisée dans d’autres circonstances. Notez le point d’interrogation après @pipeline()

Notes

Les variables système de date/heure liées aux déclencheurs (dans la portée du pipeline ou dans celle du déclencheur) retournent des dates UTC au format ISO 8601, par exemple 2017-06-01T22:20:00.4061448Z.

Fonctions de chaînes

Pour travailler avec des chaînes, vous pouvez utiliser ces fonctions de chaîne, ainsi que certaines fonctions de collection. Les fonctions de chaîne sont uniquement utilisables sur des chaînes.

Fonction de chaîne Tâche
concat Combine au moins deux chaînes et retourne la chaîne combinée.
endsWith Vérifier si une chaîne se termine par la sous-chaîne spécifiée.
guid Générer un identificateur global unique (GUID) sous forme de chaîne.
indexOf Renvoyer la position de départ d’une sous-chaîne.
lastIndexOf Retourne la position de départ de la dernière occurrence d’une sous-chaîne.
replace Remplacer une sous-chaîne par la chaîne spécifiée et renvoyer la chaîne mise à jour.
split Retourne un tableau qui contient des sous-chaînes, séparées par des virgules, extraites à partir d’une chaîne plus grande sur la base d’un caractère délimiteur spécifié dans la chaîne d’origine.
startsWith Vérifie si une chaîne commence par une sous-chaîne spécifique.
substring Renvoyer les caractères d’une chaîne, en commençant à partir de la position spécifiée.
toLower Retourne une chaîne en minuscules.
toUpper Retourne une chaîne en majuscules.
trim Supprime les espaces blancs de début et de fin d’une chaîne et retourne la chaîne mise à jour.

Fonctions de collection

Pour travailler avec des collections, généralement des tableaux, des chaînes et parfois, des dictionnaires, vous pouvez utiliser ces fonctions de collection.

Fonction de collection Tâche
contains Vérifie si une collection contient un élément spécifique.
empty Vérifie si une collection est vide.
first Renvoyer le premier élément d’une collection.
intersection Retourne une collection qui contient uniquement les éléments communs aux collections spécifiées.
join Renvoyer une chaîne qui contient tous les éléments d’un tableau, séparés par le caractère spécifié.
last Retourne le dernier élément d’une collection.
length Renvoyer le nombre d’éléments d’une chaîne ou d’un tableau.
skip Supprime des éléments du début d’une collection et retourne tous les autres éléments.
take Retourne des éléments du début d’une collection.
union Retourne une collection qui contient tous les éléments des collections spécifiées.

Fonctions logiques

Ces fonctions sont utiles à l’intérieur de conditions, et permettent d’évaluer tout type de logique.

Fonction de comparaison logique Tâche
and Vérifie si toutes les expressions sont vraies.
equals Vérifier si les deux valeurs sont équivalentes.
greater Vérifie si la première valeur est supérieure à la seconde.
greaterOrEquals Vérifie si la première valeur est supérieure ou égale à la seconde.
if Vérifie si une expression est vraie ou fausse. En fonction du résultat, retourne une valeur spécifiée.
less Vérifie si la première valeur est inférieure à la seconde.
lessOrEquals Vérifie si la première valeur est inférieure ou égale à la seconde.
not Vérifie si une expression est fausse.
or Vérifie si au moins une expression est vraie.

Fonctions de conversion

Ces fonctions permettent de convertir chacun des types natifs du langage :

  • string
  • entier
  • float
  • boolean
  • tableaux
  • dictionnaires
Fonction de conversion Tâche
array Retourne un tableau à partir d’une entrée spécifique unique. Pour des entrées multiples, consultez createArray.
base64 Retourne la version encodée en Base64 d’une chaîne.
base64ToBinary Retourne la version binaire d’une chaîne encodée en Base64.
base64ToString Renvoyer la version de type chaîne d’une chaîne encodée en base 64.
binary Renvoyer la version binaire d’une valeur d’entrée.
bool Renvoyer la version booléenne d’une valeur d’entrée.
coalesce Retourne la première valeur autre que Null d’un ou plusieurs paramètres.
createArray Retourne un tableau à partir de plusieurs entrées.
dataUri Renvoyer l’URI de données d’une valeur d’entrée.
dataUriToBinary Renvoyer la version binaire d’un URI de données.
dataUriToString Renvoyer la version de type chaîne d’un URI de données.
decodeBase64 Renvoyer la version de type chaîne d’une chaîne encodée en base 64.
decodeDataUri Renvoyer la version binaire d’un URI de données.
decodeUriComponent Retourne une chaîne qui remplace les caractères d’échappement par des versions décodées.
encodeUriComponent Renvoyer une chaîne qui remplace les caractères non sécurisés pour les URL par des caractères d'échappement.
float Renvoyer un nombre à virgule flottante pour une valeur d’entrée.
int Retourne la version de type entier d’une chaîne.
json Retourne la valeur ou l’objet de type JavaScript Object Notation (JSON) d’une chaîne ou d’un élément XML.
string Renvoyer la version de type chaîne d’une valeur d’entrée.
uriComponent Renvoyer la version encodée dans un URI d’une valeur d’entrée en remplaçant les caractères non sécurisés pour les URL par des caractères d’échappement.
uriComponentToBinary Renvoyer la version binaire d’une chaîne encodée dans un URI.
uriComponentToString Renvoyer la version de type chaîne d’une chaîne encodée dans un URI.
xml Renvoyer la version de type entier d’une chaîne.
xpath Vérifie si le code XML contient des valeurs ou des nœuds qui correspondent à une expression de langage XPath et retourne les valeurs ou les nœuds correspondants.

Fonctions mathématiques

Ces fonctions peuvent être utilisées pour les deux types de nombre : entiers et flottants.

Fonction mathématique Tâche
add Retourne le résultat de l’addition de deux nombres.
div Renvoyer le résultat de la division de deux nombres.
max Renvoyer la valeur la plus élevée d’un ensemble de nombres ou d’un tableau.
min Retourne la plus petite valeur d’un ensemble de nombres ou d’un tableau.
mod Retourne le reste de la division de deux nombres.
mul Retourne le produit de la multiplication de deux nombres.
rand Renvoyer un entier aléatoire à partir d’une plage spécifique.
range Retourne un tableau d’entiers qui commence par un entier spécifique.
sub Retourne le résultat de la soustraction du second nombre du premier.

Fonctions de date

Fonction de date ou heure Tâche
addDays Ajoute un nombre de jours à un horodatage.
addHours Ajoute un nombre d’heures à un horodatage.
addMinutes Ajoute un nombre de minutes à un horodatage.
addSeconds Ajoute un nombre de secondes à un horodatage.
addToTime Ajoute un nombre d’unités de temps à un horodatage. Voir aussi getFutureTime.
convertFromUtc Convertit un horodatage du temps universel coordonné (UTC) au fuseau horaire cible.
convertTimeZone Convertit un horodatage du fuseau horaire source au fuseau horaire cible.
convertToUtc Convertit un horodatage du fuseau horaire source en temps universel coordonné (UTC).
dayOfMonth Renvoyer le jour du composant mois d’un timestamp.
dayOfWeek Renvoyer le jour du composant semaine d’un timestamp.
dayOfYear Renvoyer le jour du composant année d’un timestamp.
formatDateTime Retourner l’horodatage sous forme de chaîne dans un format facultatif.
getFutureTime Retourne l’horodatage actuel plus les unités de temps spécifiées. Voir aussi addToTime.
getPastTime Retourne l’horodatage actuel moins les unités de temps spécifiées. Voir aussi subtractFromTime.
startOfDay Retourne le début du jour d’un horodatage.
startOfHour Retourne le début de l’heure d’un horodatage.
startOfMonth Retourne le début du mois pour un horodatage.
subtractFromTime Soustrait un nombre d’unités de temps d’un horodatage. Voir aussi getPastTime.
ticks Retourne la valeur de la propriété ticks pour un horodatage spécifique.
utcNow Renvoyer le timestamp actuel sous forme de chaîne.