How to use parameters, expressions and functions in Azure Data Factory

APPLIES TO: Azure Data Factory Azure Synapse Analytics

Tip

Wypróbuj Data Factory in Microsoft Fabric, kompleksowe rozwiązanie analityczne dla przedsiębiorstw. Microsoft Fabric obejmuje wszystko, od przesyłania danych do nauki o danych, analityki w czasie rzeczywistym, inteligencji biznesowej i raportowania. Dowiedz się, jak rozpocząć nową wersję próbną za darmo!

In this document, we will primarily focus on learning fundamental concepts with various examples to explore the ability to create parameterized data pipelines within Azure Data Factory. Parameterization and dynamic expressions are such notable additions to ADF because they can save a tremendous amount of time and allow for a much more flexible Extract, Transform, Load (ETL) or Extract, Load, Transform (ELT) solution, which will dramatically reduce the cost of solution maintenance and speed up the implementation of new features into existing pipelines. Te zyski wynikają z tego, że parametryzacja minimalizuje ilość twardego kodowania i zwiększa liczbę obiektów i procesów wielokrotnego użytku w rozwiązaniu.

Interfejs użytkownika i parametry Azure Data Factory

Jeśli dopiero zaczynasz korzystać z parametrów w interfejsie użytkownika Azure Data Factory (ADF), zapoznaj się z interfejsem użytkownika Data Factory dla połączonych usług z parametrami i interfejsem użytkownika Data Factory dla potoków sterowanych metadanymi z parametrami w celu uzyskania wizualnego wyjaśnienia.

Koncepcje parametrów i wyrażeń

Możesz używać parametrów do przekazywania wartości zewnętrznych do potoków, zbiorów danych, połączonych usług i przepływów danych. Po przekazaniu parametru do zasobu nie można go zmienić. Poprzez parametryzację zasobów, możesz ponownie je wykorzystać za każdym razem z innymi wartościami. Parametry mogą być używane indywidualnie lub jako część wyrażeń. Wartości JSON w definicji mogą być literałami lub wyrażeniami, które są oceniane w czasie wykonania.

For example:

"name": "value"

lub

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

Wyrażenia mogą pojawiać się w dowolnym miejscu w wartości łańcucha znaków JSON i zawsze skutkują inną wartością JSON. Here, password is a pipeline parameter in the expression. Jeśli wartość JSON jest wyrażeniem, treść wyrażenia jest wyodrębniana poprzez usunięcie znaku małpy (@). Jeśli jest potrzebny dosłowny ciąg znaków zaczynający się od @, to musi być zabezpieczony przez użycie @@. Następujące przykłady pokazują, jak wyrażenia są oceniane.

JSON value	Result
parametry	Znaki 'parametry' są zwracane.
parametry[1]	Znaki 'parameters[1]' są zwracane.
"@@"	Zwrócono łańcuch o długości 1 znaku, który zawiera '@'.
" @"	A 2 character string that contains ' @' is returned.

Wyrażenia mogą również pojawiać się wewnątrz ciągów znaków, korzystając z funkcji zwanej interpolacją ciągów, gdzie wyrażenia są zamknięte w @{ ... }. Na przykład: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

Using string interpolation, the result is always a string. Powiedzmy, że zdefiniowałem myNumber jako 42 i myString jako foo:

wartość JSON	Wynik
"@pipeline().parameters.myString"	Returns `foo` as a string.
"@{pipeline().parameters.myString}"	Returns `foo` as a string.
"@pipeline().parameters.myNumber"	Zwraca `42` jako liczbę.
"@{pipeline().parameters.myNumber}"	Zwraca `42` jako ciąg znaków.
Odpowiedź to: @{pipeline().parameters.myNumber}	Zwraca ciąg `Answer is: 42`.
@concat('Answer is: ', string(pipeline().parameters.myNumber))	Zwraca ciąg znaków `Answer is: 42`
Odpowiedź to: @@{pipeline().parameters.myNumber}	Zwraca ciąg znaków `Answer is: @{pipeline().parameters.myNumber}`.

Przykłady użycia parametrów w wyrażeniach

Przykład złożonego wyrażenia

Poniższy przykład pokazuje złożony przypadek, który odnosi się do głębokiej poddziedziny wyników działalności. To reference a pipeline parameter that evaluates to a sub-field, use [] syntax instead of dot(.) operator (as in case of subfield1 and subfield2)

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

Edytor dynamicznej treści

Dynamic content editor automatically escapes characters in your content when you finish editing. Na przykład, poniższa zawartość w edytorze treści to interpolacja ciągów z dwiema funkcjami wyrażeń.

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

Edytor dynamicznej treści konwertuje powyższą treść na wyrażenie "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". Wynikiem tego wyrażenia jest ciąg formatu JSON pokazany poniżej.

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

Zestaw danych z parametrami

In the following example, the BlobDataset takes a parameter named path. Its value is used to set a value for the folderPath property by using the expression: dataset().path.

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

Potok z parametrami

W poniższym przykładzie pipeline przyjmuje parametry inputPath i outputPath. Ścieżka dla parametryzowanego zestawu danych blob jest ustawiana za pomocą wartości tych parametrów. The syntax used here is: 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"
            }
        }
    }
}

Wywoływanie funkcji w wyrażeniach

You can call functions within expressions. Następujące sekcje zawierają informacje o funkcjach, które mogą być używane w wyrażeniu.

Funkcje ciągów

Aby pracować z ciągami znaków, możesz używać tych funkcji dla ciągów znaków, a także niektórych funkcji kolekcji. Funkcje łańcuchowe działają tylko na łańcuchach znaków.

Funkcja łańcuchowa	Task
concat	Połącz dwie lub więcej ciągów znaków i zwróć połączony ciąg.
endsWith	Check whether a string ends with the specified substring.
guid	Wygeneruj globalnie unikalny identyfikator (GUID) jako ciąg znaków.
indexOf	Zwróć pozycję początkową dla podciągu.
lastIndexOf	Zwróć pozycję początkową ostatniego wystąpienia podciągu.
replace	Replace a substring with the specified string, and return the updated string.
split	Zwróć tablicę zawierającą podciągi, oddzielone przecinkami, z większego ciągu znaków, na podstawie określonego znaku delimitera w oryginalnym ciągu znaków.
startsWith	Sprawdź, czy ciąg znaków zaczyna się od określonego podciągu.
substring	Zwróć znaki z ciągu, zaczynając od określonej pozycji.
toLower	Return a string in lowercase format.
toUpper	Return a string in uppercase format.
trim	Remove leading and trailing whitespace from a string, and return the updated string.

Collection functions

To work with collections, generally arrays, strings, and sometimes, dictionaries, you can use these collection functions.

Collection function	Task
contains	Sprawdź, czy kolekcja zawiera określony element.
empty	Check whether a collection is empty.
first	Zwróć pierwszy element z kolekcji.
intersection	Return a collection that has only the common items across the specified collections.
join	Return a string that has all the items from an array, separated by the specified character.
last	Return the last item from a collection.
length	Zwróć liczbę elementów w ciągu znaków lub tablicy.
skip	Remove items from the front of a collection, and return all the other items.
take	Zwróć elementy z przodu kolekcji.
union	Zwróć kolekcję, która zawiera wszystkie elementy ze wskazanych kolekcji.

Logical functions

Funkcje te są przydatne w warunkach; można je używać do oceny dowolnej logiki.

Funkcja porównania logicznego	Task
and	Sprawdź, czy wszystkie wyrażenia są prawdziwe.
równa się	Check whether both values are equivalent.
większy	Check whether the first value is greater than the second value.
greaterOrEquals	Sprawdź, czy pierwsza wartość jest większa lub równa drugiej wartości.
if	Sprawdź, czy wyrażenie jest prawdziwe czy fałszywe. Na podstawie wyniku, zwróć określoną wartość.
mniej	Sprawdź, czy pierwsza wartość jest mniejsza od drugiej wartości.
lessOrEquals	Check whether the first value is less than or equal to the second value.
not	Sprawdź, czy wyrażenie jest fałszywe.
or	Sprawdź, czy co najmniej jedno wyrażenie jest prawdziwe.

Funkcje konwersji

Te funkcje są używane do konwersji między każdym z natywnych typów w języku.

string
liczba całkowita
float
boolean
tablice
słowniki

Conversion function	Task
array	Return an array from a single specified input. For multiple inputs, see createArray.
base64	Return the base64-encoded version for a string.
base64ToBinary	Zwróć wersję binarną dla ciągu kodowanego w base64.
base64ToString	Zwróć wersję tekstową dla ciągu zakodowanego w base64.
binary	Zwróć binarną wersję dla wartości wejściowej.
bool	Return the Boolean version for an input value.
coalesce	Return the first non-null value from one or more parameters.
createArray	Return an array from multiple inputs.
dataUri	Return the data URI for an input value.
dataUriToBinary	Zwróć wersję binarną dla URI danych.
dataUriToString	Zwróć wersję łańcuchową dla identyfikatora URI danych.
decodeBase64	Return the string version for a base64-encoded string.
decodeDataUri	Return the binary version for a data URI.
decodeUriComponent	Zwróć ciąg znaków, w którym znaki ucieczki są zastępowane ich zdekodowanymi wersjami.
encodeUriComponent	Return a string that replaces URL-unsafe characters with escape characters.
float	Zwróć liczbę zmiennoprzecinkową dla wartości wejściowej.
int	Zwróć wersję całkowitą dla łańcucha znaków.
json	Zwróć wartość typu JavaScript Object Notation (JSON) lub obiekt dla ciągu znaków lub XML.
string	Zwróć wersję łańcuchową dla wartości wejściowej.
uriComponent	Zwróć wersję kodowaną w URI dla wartości wejściowej, zastępując niebezpieczne dla URL znaki znakami ucieczki.
uriComponentToBinary	Zwróć wersję binarną dla ciągu zakodowanego jako URI.
uriComponentToString	Zwróć wersję w formie ciągu dla ciągu zakodowanego jako URI.
xml	Return the XML version for a string.
xpath	Sprawdź XML pod kątem węzłów lub wartości pasujących do wyrażenia XPath (XML Path Language) i zwróć pasujące węzły lub wartości.

Math functions

Te funkcje mogą być używane dla obu typów liczb: liczb całkowitych i liczb zmiennoprzecinkowych.

Funkcja matematyczna	Zadanie
add	Return the result from adding two numbers.
div	Zwróć wynik dzielenia dwóch liczb.
max	Zwróć najwyższą wartość z zestawu liczb lub tablicy.
min	Return the lowest value from a set of numbers or an array.
mod	Return the remainder from dividing two numbers.
mul	Zwróć wynik mnożenia dwóch liczb.
rand	Return a random integer from a specified range.
range	Zwróć tablicę liczb całkowitych, która zaczyna się od określonej liczby całkowitej.
sub	Zwróć wynik odejmowania drugiej liczby od pierwszej liczby.

Date functions

Funkcja daty lub czasu	Zadanie
addDays	Dodaj określoną liczbę dni do znaczniku czasowego.
addHours	Add a number of hours to a timestamp.
addMinutes	Dodaj określoną liczbę minut do znacznika czasu.
addSeconds	Add a number of seconds to a timestamp.
addToTime	Dodaj liczbę jednostek czasu do znacznika czasu. See also getFutureTime.
convertFromUtc (funkcja konwertująca czas z UTC)	Convert a timestamp from Universal Time Coordinated (UTC) to the target time zone.
convertTimeZone	Przekształć znacznik czasu z czasu źródłowego do czasu docelowego.
przekształćNaUtc	Przekształć znacznik czasu z czasu lokalnego na czas uniwersalny skoordynowany (UTC).
dayOfMonth	Zwróć składnik dnia miesiąca z sygnatury czasowej.
dayOfWeek	Zwróć komponent dnia tygodnia ze znacznika czasu.
dayOfYear	Zwróć dzień roku z sygnatury czasowej.
formatDateTime	Zwróć znacznik czasu jako ciąg znaków w opcjonalnym formacie.
getFutureTime	Zwróć bieżący znacznik czasu powiększony o określone jednostki czasu. See also addToTime.
getPastTime	Zwróć aktualny znacznik czasu pomniejszony o określone jednostki czasu. Zobacz także subtractFromTime.
startOfDay	Zwróć początek dnia dla znacznika czasu.
startOfHour	Zwróć początek godziny dla znacznika czasu.
startOfMonth	Return the start of the month for a timestamp.
subtractFromTime	Odejmij liczbę jednostek czasu od znacznika czasowego. Zobacz także getPastTime.
kleszcze	Zwróć wartość właściwości `ticks` dla określonego znacznika czasu.
utcNow	Zwróć aktualny znacznik czasu jako ciąg znaków.

Detailed examples for practice

Detailed Azure Data Factory copy pipeline with parameters

Ten samouczek dotyczący przekazywania parametrów w Azure Data Factory w kopii potoku wyjaśnia, jak przekazywać parametry między potokiem a aktywnością oraz między aktywnościami.

Szczegółowe mapowanie przepływu danych w rurociągu z parametrami

Proszę zapoznać się z Mapowaniem przepływu danych z parametrami, aby uzyskać pełny przykład wykorzystania parametrów w przepływie danych.

Szczegółowy potok danych napędzany metadanymi z parametrami

Proszę przejdź do Metadata driven pipeline with parameters aby dowiedzieć się więcej na temat używania parametrów do projektowania potoków napędzanych metadanymi. To jest popularne zastosowanie dla parametrów.

For a list of system variables you can use in expressions, see System variables.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-04-16