Guide pratique pour utiliser des paramètres, des expressions et des fonctions dans Azure Data Factory
S’APPLIQUE À :
Azure Data Factory Azure Synapse Analytics
Conseil
Essayez Data Factory dans Microsoft Fabric, une solution d’analyse tout-en-un pour les entreprises. Microsoft Fabric couvre tous les aspects, du déplacement des données à la science des données, en passant par l’analyse en temps réel, l’aide à la décision et la création de rapports. Découvrez comment démarrer un nouvel essai gratuitement !
Dans ce document, nous allons essentiellement nous concentrer sur les concepts fondamentaux avec divers exemples pour explorer la possibilité de créer des pipelines de données paramétrisables dans Azure Data Factory. La paramétrisation et les expressions dynamiques sont des ajouts notables pour ADF, car ils 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.
Interface utilisateur et paramètres Azure Data Factory
Si vous n’êtes pas familier avec l’utilisation des paramètres Azure Data Factory dans l’interface utilisateur ADF, consultez Interface utilisateur Data Factory pour les services liés avec les paramètres et Interface utilisateur Data Factory pour le pipeline piloté par les métadonnées avec les paramètres afin d’obtenir une explication visuelle.
Concepts des paramètres et des expressions
Vous pouvez utiliser des paramètres pour transmettre des valeurs externes dans des pipelines, des jeux de données, des services liés et des flux de données. 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 JSON 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.
Par exemple :
"name": "value"
or
"name": "@pipeline().parameters.password"
Les expressions peuvent apparaître n’importe où dans une valeur de chaîne JSON, et entraînent toujours une autre valeur JSON. Ici, password est un paramètre de pipeline dans l’expression. Si une valeur JSON est une expression, le corps de celle-ci est extrait en supprimant l’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 JSON | 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 : "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"
En utilisant une interpolation de chaîne, le résultat est toujours une chaîne. Supposons que j’ai défini myNumber sur 42 et myString sur foo :
| Valeur JSON | 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
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 des caractères de votre contenu quand vous avez fini de l’éditer. Par exemple, le contenu suivant dans l’éditeur de contenu est une interpolation de chaîne avec deux fonctions d’expression.
{
"type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
"name": "@{toUpper('myData')}"
}
L’éditeur de contenu dynamique convertit le contenu ci-dessus en expression "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". Le résultat de cette expression est une chaîne de format JSON illustrée ci-dessous.
{
"type": "Table",
"name": "MYDATA"
}
Jeu de données avec des paramètres
Dans l’exemple suivant, BlobDataset prend un paramètre nommé path. Sa valeur est utilisée pour donner une valeur à la propriété folderPath à l’aide de l’expression : dataset().path.
{
"name": "BlobDataset",
"properties": {
"type": "AzureBlob",
"typeProperties": {
"folderPath": "@dataset().path"
},
"linkedServiceName": {
"referenceName": "AzureStorageLinkedService",
"type": "LinkedServiceReference"
},
"parameters": {
"path": {
"type": "String"
}
}
}
}
Pipeline avec des paramètres
Dans l’exemple suivant, le pipeline prend les paramètres inputPath et outputPath. Le path du jeu de données blob paramétrable est défini par les valeurs de ces paramètres. Voici la syntaxe utilisée : pipeline().parameters.parametername.
{
"name": "Adfv2QuickStartPipeline",
"properties": {
"activities": [
{
"name": "CopyFromBlobToBlob",
"type": "Copy",
"inputs": [
{
"referenceName": "BlobDataset",
"parameters": {
"path": "@pipeline().parameters.inputPath"
},
"type": "DatasetReference"
}
],
"outputs": [
{
"referenceName": "BlobDataset",
"parameters": {
"path": "@pipeline().parameters.outputPath"
},
"type": "DatasetReference"
}
],
"typeProperties": {
"source": {
"type": "BlobSource"
},
"sink": {
"type": "BlobSink"
}
}
}
],
"parameters": {
"inputPath": {
"type": "String"
},
"outputPath": {
"type": "String"
}
}
}
}
Appel de fonctions dans des expressions
Vous pouvez appeler des fonctions dans des expressions. Les sections suivantes fournissent des informations sur les fonctions qui peut être utilisées dans une expression.
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. |
Exemples détaillés pour vous entraîner
Pipeline de copie Azure Data Factory détaillé avec paramètres
Ce tutoriel sur la transmission de paramètres de pipeline de copie Azure Data Factory vous montre comment transmettre des paramètres entre un pipeline et une activité ainsi qu’entre les activités.
Pipeline de flux de données de mappage détaillé avec des paramètres
Pour obtenir un exemple complet d’utilisation des paramètres dans le flux de données, suivez Flux de données de mappage avec paramètres.
Pipeline piloté par les métadonnées détaillé avec paramètres
Pour en savoir plus sur l’utilisation des paramètres afin de concevoir des pipelines pilotés par les métadonnées, suivez Pipeline piloté par les métadonnées avec paramètres. Il s’agit d’un cas d’usage courant pour les paramètres.
Contenu connexe
Pour la liste des variables système que vous pouvez utiliser dans des expressions, voir variables système.