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