Parameter für Data Factory in Microsoft Fabric
In diesem Dokument wird beschrieben, wie Sie Parameter in Ihren Pipelines für Data Factory in Fabric verwenden.
Verwenden von Parametern, Ausdrücken und Funktionen in Pipelines für Data Factory in Fabric
In diesem Dokument konzentrieren wir uns auf das Erlernen grundlegender Konzepte mit verschiedenen Beispielen, um die Möglichkeit zum Erstellen von parametrisierten Datenpipelines in Data Factory in Fabric zu untersuchen. Parametrisierung und dynamische Ausdrücke können sehr viel Zeit sparen 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.
Parameter- und Ausdruckskonzepte
Sie können mit Parametern externe Werte an Pipelines ü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 Parameterwerten in der Definition kann es sich um Literalwerte oder um Ausdrücke handeln, die zur Laufzeit ausgewertet werden.
Ausdrücke können an beliebiger Stelle in einem Zeichenfolgenwert auftreten und generieren immer einen anderen Zeichenfolgenwert. Hier ist password ein Pipelineparameter im Ausdruck. Wenn ein Parameterwert ein Ausdruck ist, wird der Text des Ausdrucks durch Entfernen des at-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.
| Parameterwert | 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. Die folgende Zeichenfolge enthält beispielsweise Parameterwerte und Literalzeichenfolgenwerte:
"First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"
Bei der Verwendung einer Zeichenfolgeninterpolation ist das Ergebnis immer eine Zeichenfolge. Wenn Sie z. B. myNumber als 42 und myString als foo definiert haben:
| Parameterwert | 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
Erstellen und Verwenden von Parametern
Wählen Sie zum Erstellen von Parametern den Hintergrund der Canvas des Pipeline-Editors und dann unten im Eigenschaftenfenster die Registerkarte Parameter aus. Wählen Sie die Schaltfläche + Neu aus, um der Pipeline einen neuen Parameter hinzuzufügen, und geben Sie einen Namen, einen Datentyp und einen Standardwert an:
Sie können den Parameter dann überall dort in Ihrer Pipeline verwenden, wo dynamische Inhalte unterstützt werden. In diesem Beispiel wird der Parameter verwendet, um den Namen eines Lakehouse-Datenspeichers auf der Registerkarte Quelle der Eigenschaftenseiten einer Copy-Aktivität dynamisch anzugeben.
Das Fenster Dynamischen Inhalt hinzufügen wird angezeigt, sodass Sie jede Art von dynamischem Inhalt angeben können, einschließlich Parametern, Systemvariablen, Funktionen oder Pipelinevariablen. In diesem Beispiel wird der zuvor definierte Parameter ausgewählt, und das Fenster für dynamische Inhalte wird automatisch mit dem richtigen Ausdruck aufgefüllt, um auf den Parameter zu verweisen.
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 Sie die Bearbeitung abschließen. Der folgende Inhalt im Inhalts-Editor ist z. B. eine Zeichenfolgeninterpolation mit einer Ausdrucksfunktion:
@{toUpper('myData')}
Der Editor für dynamische Inhalte konvertiert den oben gezeigten Inhalt in den folgenden Ausdruck:
MYDATA
Verwenden von Funktionen und Variablen in Ausdrücken
Sie können Funktionen aufrufen und Variablen in Ausdrücken verwenden. Die folgenden Abschnitte enthalten Informationen zu den Funktionen, die in einem Ausdruck verwendet werden können.
Pipelinebereichsvariablen
Auf diese Systemvariablen kann überall im Pipeline-JSON verwiesen werden.
| Variablenname | BESCHREIBUNG |
|---|---|
| @pipeline().DataFactory | Name des Daten- oder Synapse-Arbeitsbereich, in dem die Pipelineausführung erfolgt |
| @pipeline().Pipeline | Name der Pipeline |
| @pipeline().RunId | ID der jeweiligen Pipelineausführung |
| @pipeline().TriggerId | ID des Triggers, der die Pipeline aufgerufen hat |
| @pipeline().TriggerName | Name des Triggers, der die Pipeline aufgerufen hat |
| @pipeline().TriggerTime | Zeitpunkt der Triggerausführung, durch die die Pipeline aufgerufen wurde. Dies ist der Zeitpunkt, zu dem der Trigger zum Aufrufen der Pipelineausführung tatsächlich ausgelöst wurde. Er kann vom geplanten Zeitpunkt für den Trigger geringfügig abweichen. |
| @pipeline().GroupId | ID der Gruppe, zu der die Pipelineausführung gehört. |
| @pipeline()?.TriggeredByPipelineName | Name der Pipeline, die die Pipelineausführung auslöst. Gilt, wenn die Pipelineausführung durch eine ExecutePipeline-Aktivität ausgelöst wird. Wird in anderen Fällen als Null ausgewertet. Beachten Sie das Fragezeichen nach @pipeline(). |
| @pipeline()?.TriggeredByPipelineRunId | Ausführungs-ID der Pipeline, die die Pipelineausführung auslöst. Gilt, wenn die Pipelineausführung durch eine ExecutePipeline-Aktivität ausgelöst wird. Wird in anderen Fällen als Null ausgewertet. Beachten Sie das Fragezeichen nach @pipeline(). |
Hinweis
Triggerbezogene Systemvariablen für Datum/Uhrzeit (in Pipeline- und Triggerbereichen) geben UTC-Datumsangaben im ISO 8601-Format zurück, z. B. 2017-06-01T22:20:00.4061448Z.
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 |
|---|---|
| und | Ü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. |