Share via

Guide pratique pour utiliser des paramètres, des expressions et des fonctions dans Azure Data Factory

  • Article

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.