Verwenden von Parametern, Ausdrücken und Funktionen in Azure Data Factory

  • Artikel

GILT FÜR: Azure Data Factory Azure Synapse Analytics

Tipp

Testen Sie Data Factory in Microsoft Fabric, eine All-in-One-Analyselösung für Unternehmen. Microsoft Fabric deckt alle Aufgaben ab, von der Datenverschiebung bis hin zu Data Science, Echtzeitanalysen, Business Intelligence und Berichterstellung. Erfahren Sie, wie Sie kostenlos eine neue Testversion starten!

In diesem Dokument konzentrieren wir uns in erster Linie auf das Erlernen grundlegender Konzepte mit verschiedenen Beispielen, um die Möglichkeit zum Erstellen von parametrisierten Datenpipelines in Azure Data Factory zu untersuchen. Parametrisierung und dynamische Ausdrücke sind solche bedeutenden Ergänzungen von ADF, da sie sehr viel Zeit sparen können und eine viel flexiblere Lösung zum Extrahieren, Transformieren und Laden (Extract, Transform, Load, ETL) oder Extrahieren, Laden und Transformieren (Extract, Load, Transform, ELT) ermöglichen, wodurch die Kosten für die Wartung der Lösung drastisch gesenkt werden und die Implementierung neuer Features in vorhandene Pipelines beschleunigt wird. Diese Vorteile basieren darauf, dass die Parametrisierung die Hartcodierung minimiert und die Anzahl der wiederverwendbaren Objekte und Prozesse in einer Lösung erhöht.

Benutzeroberfläche und Parameter von Azure Data Factory

Wenn Sie noch nicht mit der Verwendung von Azure Data Factory-Parametern auf der ADF-Benutzeroberfläche vertraut sind, nutzen Sie die visuelle Erläuterung in den Artikeln zur Data Factory-Benutzeroberfläche für verknüpfte Dienste mit Parametern und Data Factory-Benutzeroberfläche für metadatengesteuerte Pipelines mit Parametern.

Parameter- und Ausdruckskonzepte

Sie können mit Parametern externe Werte an Pipelines, Datasets, verknüpfte Dienste und Datenflüsse übergeben. Nachdem der Parameter an die Ressource übergeben wurde, kann er nicht mehr geändert werden. Indem Sie Ressourcen parametrisieren, können Sie sie jedes Mal mit unterschiedlichen Werten wiederverwenden. Parameter können einzeln oder als Teil von Ausdrücken verwendet werden. Bei den JSON-Werten in der Definition kann es sich um Literalwerte oder um Ausdrücke handeln, die zur Laufzeit ausgewertet werden.

Beispiel:

"name": "value"

oder

"name": "@pipeline().parameters.password"

Ausdrücke können an beliebiger Stelle in einem JSON-Zeichenfolgenwert verwendet werden und ergeben immer einen anderen JSON-Wert. Hier ist password ein Pipelineparameter im Ausdruck. Wenn ein JSON-Wert ein Ausdruck ist, wird der Text des Ausdrucks durch Entfernen des @-Zeichens extrahiert. Falls Sie ein Zeichenfolgenliteral benötigen, das mit @ beginnt, muss es wie folgt mit einem Escapezeichen versehen werden: @@. Die folgenden Beispiele veranschaulichen die Auswertung von Ausdrücken.

JSON-Wert Ergebnis
"parameters" Die Zeichenfolge „parameters“ wird zurückgegeben.
"parameters[1]" Die Zeichenfolge „parameters[1]“ wird zurückgegeben.
"@@" Eine Zeichenfolge, die \„\@\“ enthält, wird zurückgegeben (einzelnes Zeichen).
" @" Eine Zeichenfolge, die \„ \@ \“ enthält, wird zurückgegeben (zwei Zeichen).

Mit der Zeichenfolgeninterpolation können Ausdrücke auch innerhalb von Zeichenfolgen verwendet werden. Dabei werden die Ausdrücke in @{ ... } eingeschlossen. Beispiel: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

Bei der Verwendung einer Zeichenfolgeninterpolation ist das Ergebnis immer eine Zeichenfolge. Angenommen, ich habe myNumber als 42 und myString als foo definiert:

JSON-Wert Ergebnis
"@pipeline().parameters.myString" Gibt foo als Zeichenfolge zurück.
"@{pipeline().parameters.myString}" Gibt foo als Zeichenfolge zurück.
"@pipeline().parameters.myNumber" Gibt 42 als Zahl zurück.
"@{pipeline().parameters.myNumber}" Gibt 42 als Zeichenfolge zurück.
"Answer is: @{pipeline().parameters.myNumber}" Gibt die Zeichenfolge Answer is: 42 zurück.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))" Gibt die Zeichenfolge Answer is: 42 zurück.
"Answer is: @@{pipeline().parameters.myNumber}" Gibt die Zeichenfolge Answer is: @{pipeline().parameters.myNumber} zurück.

Beispiele für die Verwendung von Parametern in Ausdrücken

Beispiel für komplexen Ausdruck

Das folgende Beispiel zeigt einen komplexen Ausdruck, der auf ein tiefes Unterfeld der Aktivitätsausgabe verweist. Wenn Sie auf einen Pipelineparameter verweisen möchten, der als ein Unterfeld ausgewertet wird, verwenden Sie die Syntax „[]“ statt des Punktoperators „(.)“ (wie bei „subfield1“ und „subfield2“).

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

Editor für dynamische Inhalte

Der Editor für dynamische Inhalte versieht automatisch Zeichen in ihrem Inhalt mit Escapezeichen, wenn die Bearbeitung abgeschlossen ist. Der folgende Inhalt im Inhalts-Editor ist z. B. eine Zeichenfolgeninterpolation mit zwei Ausdrucksfunktionen.

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

Der Editor für dynamische Inhalte konvertiert oben Inhalt in einen Ausdruck "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". Das Ergebnis dieses Ausdrucks ist eine Zeichenfolge im JSON-Format, die unten gezeigt wird.

{
  "type": "Table",
  "name": "MYDATA"
}

Ein Dataset mit Parametern

Im folgenden Beispiel nutzt „BlobDataset“ einen Parameter namens path. Der Wert wird unter Verwendung des folgenden Ausdrucks zum Festlegen eines Werts für die Eigenschaft folderPath verwendet: dataset().path.

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

Eine Pipeline mit Parametern

Im folgenden Beispiel nutzt die Pipeline die Parameter inputPath und outputPath. Der Parameter path für das parametrisierte Blobdataset wird mithilfe der Werte dieser Parameter festgelegt. Die hier verwendete Syntax lautet 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"
            }
        }
    }
}

Aufrufen von Funktionen innerhalb von Ausdrücken

Sie können Funktionen innerhalb von Ausdrücken aufrufen. Die folgenden Abschnitte enthalten Informationen zu den Funktionen, die in einem Ausdruck verwendet werden können.

Zeichenfolgenfunktionen

Für die Arbeit mit Zeichenfolgen können Sie folgende Zeichenfolgenfunktionen und auch einige Sammlungsfunktionen verwenden. Zeichenfolgenfunktionen können nur in Zeichenfolgen verwendet werden.

Zeichenfolgenfunktion Aufgabe
concat Kombiniert mindestens zwei Zeichenfolgen miteinander und gibt die kombinierte Zeichenfolge zurück.
endsWith Überprüft, ob eine Zeichenfolge mit der angegebenen Teilzeichenfolge endet.
guid Generiert einen global eindeutigen Bezeichner (Globally Unique Identifier, GUID) als Zeichenfolge.
indexOf Gibt die Anfangsposition für eine Teilzeichenfolge zurück.
lastIndexOf Gibt die Anfangsposition des letzten Vorkommens einer Teilzeichenfolge zurück.
replace Ersetzt eine Teilzeichenfolge durch die angegebene Zeichenfolge und gibt die aktualisierte Zeichenfolge zurück.
split Gibt ein Array mit Teilzeichenfolgen, die durch Trennzeichen getrennt sind, aus einer größeren Zeichenfolge basierend auf einem angegebenen Trennzeichen in der ursprünglichen Zeichenfolge zurück.
startsWith Überprüft, ob eine Zeichenfolge mit einer bestimmten Teilzeichenfolge beginnt.
substring Gibt Zeichen aus einer Zeichenfolge zurück, beginnend mit der angegebenen Position.
toLower Gibt eine Zeichenfolge in Kleinbuchstaben zurück.
toUpper Gibt eine Zeichenfolge in Großbuchstaben zurück.
trim Entfernt führende und nachfolgende Leerzeichen aus einer Zeichenfolge und gibt die aktualisierte Zeichenfolge zurück.

Auflistungsfunktionen

Für die Arbeit mit Sammlungen (in der Regel Arrays, Zeichenfolgen und manchmal auch Bibliotheken) können Sie folgende Sammlungsfunktionen verwenden.

Sammlungsfunktion Aufgabe
contains Überprüft, ob eine Sammlung ein bestimmtes Element enthält.
empty Überprüft, ob eine Sammlung leer ist.
first Gibt das erste Element aus einer Sammlung zurück.
intersection Gibt eine Sammlung zurück, die nur die gängigen Elemente aus den angegebenen Sammlungen enthält.
join Gibt eine Zeichenfolge zurück, die alle Elemente aus einem Array enthält, getrennt durch das angegebene Zeichen.
last Gibt das letzte Element aus einer Sammlung zurück.
length Gibt die Anzahl der Elemente in einer Zeichenfolge oder einem Array zurück.
skip Entfernt Elemente vom Anfang einer Sammlung und gibt alle anderen Elemente zurück.
take Gibt Elemente vom Anfang einer Sammlung zurück.
union Gibt eine Sammlung zurück, die sämtliche Elemente aus den angegebenen Sammlungen enthält.

Logische Funktionen

Diese Funktionen können innerhalb von Bedingungen zur Auswertung einer beliebigen Art von Logik verwendet werden.

Logische Vergleichsfunktion Aufgabe
and Überprüft, ob für sämtliche Ausdrücke der Wert „TRUE“ festgelegt ist.
equals Überprüft, ob beide Werte identisch sind.
greater Überprüft, ob der erste Wert größer als der zweite ist.
greaterOrEquals Überprüft, ob der erste Wert größer als oder gleich dem zweiten ist.
if Überprüft, ob ein Ausdruck gleich „true“ oder „false“ ist. Gibt abhängig vom Ergebnis einen angegebenen Wert zurück.
less Überprüft, ob der erste Wert kleiner als der zweite ist.
lessOrEquals Überprüft, ob der erste Wert kleiner als oder gleich dem zweiten ist.
not Überprüft, ob ein Ausdruck gleich „false“ ist.
or Überprüft, ob mindestens ein Ausdruck gleich „true“ ist.

Konvertierungsfunktionen

Diese Funktionen dienen zum Konvertieren zwischen den einzelnen nativen Typen in der Sprache:

  • Zeichenfolge
  • integer
  • float
  • boolean
  • Arrays
  • Wörterbücher
Konvertierungsfunktion Aufgabe
array Gibt ein Array aus einer einzelnen angegebenen Eingabe zurück. Für mehrere Eingaben siehe createArray.
base64 Gibt die base64-codierte Version für eine Zeichenfolge zurück.
base64ToBinary Gibt die Binärversion für eine base64-codierte Zeichenfolge zurück.
base64ToString Gibt die Zeichenfolgenversion für eine base64-codierte Zeichenfolge zurück.
binary Gibt die Binärversion für einen Eingabewert zurück.
bool Gibt die Version des booleschen Werts für einen Eingabewert zurück.
coalesce Gibt den ersten Wert ungleich NULL aus mindestens einem Parameter zurück.
createArray Gibt ein Array aus mehreren Eingaben zurück.
dataUri Gibt den Daten-URI für einen Eingabewert zurück.
dataUriToBinary Gibt die Binärversion für einen Daten-URI zurück.
dataUriToString Gibt die Zeichenfolgenversion für einen Daten-URI zurück.
decodeBase64 Gibt die Zeichenfolgenversion für eine base64-codierte Zeichenfolge zurück.
decodeDataUri Gibt die Binärversion für einen Daten-URI zurück.
decodeUriComponent Gibt eine Zeichenfolge zurück, in der Escapezeichen durch decodierte Versionen ersetzt sind.
encodeUriComponent Gibt eine Zeichenfolge zurück, die URL-unsichere Zeichen durch Escapezeichen ersetzt.
float Gibt eine Gleitkommazahl für einen Eingabewert zurück.
int Gibt die Ganzzahlversion für eine Zeichenfolge zurück.
json Gibt den JSON-Typwert oder das JSON-Objekt (JSON = JavaScript Object Notation) für eine Zeichenfolge oder XML zurück.
string Gibt die Zeichenfolgenversion für einen Eingabewert zurück.
uriComponent Gibt die URI-codierte Version für einen Eingabewert zurück, indem URL-unsichere Zeichen durch Escapezeichen ersetzt werden.
uriComponentToBinary Gibt die Binärversion für eine URI-codierte Zeichenfolge zurück.
uriComponentToString Gibt die Zeichenfolgenversion für eine URI-codierte Zeichenfolge zurück.
xml Gibt die XML-Version für eine Zeichenfolge zurück.
xpath Überprüft die XML auf Knoten oder Werte, die mit einem XPath-Ausdruck (XML Path Language) übereinstimmen, und gibt die übereinstimmenden Knoten oder Werte zurück.

Mathematische Funktionen

Diese Funktionen können für folgende Arten von Zahlen verwendet werden: ganze Zahlen und Gleitkommazahlen.

Mathematische Funktion Aufgabe
add Gibt das Ergebnis der Addition zweier Zahlen zurück.
div Gibt das Ergebnis der Division zweier Zahlen zurück.
max Gibt den höchsten Wert aus einer Reihe von Zahlen oder einem Array zurück.
min Gibt den niedrigsten Wert aus einer Reihe von Zahlen oder einem Array zurück.
mod Gibt den Restwert aus der Division zweier Zahlen zurück.
mul Gibt das Produkt aus der Multiplikation zweier Zahlen zurück.
rand Gibt eine beliebige ganze Zahl aus einem angegebenen Bereich zurück.
range Gibt ein Array mit ganzen Zahlen zurück, das mit einer angegebenen ganzen Zahl beginnt.
sub Gibt das Ergebnis aus der Subtraktion der zweiten Zahl von der ersten Zahl zurück.

Datumsfunktionen

Datums- oder Zeitfunktion Aufgabe
addDays Fügt eine Anzahl von Tagen zu einem Zeitstempel hinzu.
addHours Fügt eine Anzahl von Stunden zu einem Zeitstempel hinzu.
addMinutes Fügt eine Anzahl von Minuten zu einem Zeitstempel hinzu.
addSeconds Fügt eine Anzahl von Sekunden zu einem Zeitstempel hinzu.
addToTime Fügt eine Anzahl von Zeiteinheiten zu einem Zeitstempel hinzu. Siehe auch getFutureTime.
convertFromUtc Konvertiert einen Zeitstempel von der UTC-Zeitzone (UTC = Universal Time, Coordinated) in die Zielzeitzone.
convertTimeZone Konvertiert einen Zeitstempel von der Quellzeitzone in die Zielzeitzone.
convertToUtc Konvertiert einen Zeitstempel von der Quellzeitzone in die UTC-Zeitzone (UTC = Universal Time, Coordinated).
dayOfMonth Gibt den Tag der Monatskomponente eines Zeitstempels zurück.
dayOfWeek Gibt den Tag der Wochenkomponente eines Zeitstempels zurück.
dayOfYear Gibt den Tag der Jahreskomponente eines Zeitstempels zurück.
formatDateTime Gibt den Zeitstempel als Zeichenfolge in optionalem Format zurück.
getFutureTime Gibt den aktuellen Zeitstempel plus der angegebenen Zeiteinheiten zurück. Siehe auch addToTime.
getPastTime Gibt den aktuellen Zeitstempel abzüglich der angegebenen Zeiteinheiten zurück. Siehe auch subtractFromTime.
startOfDay Gibt den Beginn des Tages für einen Zeitstempel zurück.
startOfHour Gibt den Beginn der Stunde für einen Zeitstempel zurück.
startOfMonth Gibt den Beginn des Monats für einen Zeitstempel zurück.
subtractFromTime Subtrahiert eine Anzahl von Zeiteinheiten von einem Zeitstempel. Siehe auch getPastTime.
ticks Gibt den Eigenschaftswert ticks für einen angegebenen Zeitstempel zurück.
utcNow Gibt den aktuellen Zeitstempel als Zeichenfolge zurück.

Ausführliche Beispiele für die Praxis

Azure Data Factory-Kopierpipeline mit Parametern im Detail

In diesem Tutorial zur Übergabe von Azure Data Factory-Kopierpipeline-Parametern erfahren Sie, wie Sie Parameter zwischen einer Pipeline und einer Aktivität sowie zwischen den Aktivitäten übergeben können.

Zuordnungsdatenfluss-Pipeline mit Parametern im Detail

Ein ausführliches Beispiel zum Verwenden von Parametern im Datenfluss finden Sie unter Parametrisieren von Zuordnungsdatenflüssen.

Metadatengesteuerte Pipeline mit Parametern im Detail

Unter Verweisen auf Triggermetadaten in Pipelineausführungen finden Sie weitere Informationen zur Verwendung von Parametern zum Entwerfen metadatengesteuerter Pipelines. Dies ist ein beliebter Anwendungsfall für Parameter.

Zugehöriger Inhalt

Eine Liste der Systemvariablen, die Sie in Ausdrücken verwenden können, finden Sie unter Systemvariablen.