Parametry usługi Data Factory w usłudze Microsoft Fabric
W tym dokumencie opisano sposób używania parametrów w potokach dla usługi Data Factory w sieci szkieletowej.
Jak używać parametrów, wyrażeń i funkcji w potokach dla usługi Data Factory w sieci szkieletowej
W tym dokumencie skupimy się na poznaniu podstawowych pojęć z różnymi przykładami, aby poznać możliwość tworzenia sparametryzowanych potoków danych w usłudze Data Factory w sieci szkieletowej. Parametryzacja i wyrażenia dynamiczne mogą zaoszczędzić ogromny czas i pozwolić na znacznie bardziej elastyczne wyodrębnianie, przekształcanie, ładowanie (ETL) lub wyodrębnianie, ładowanie, przekształcanie (ELT), co znacznie zmniejszy koszty konserwacji rozwiązania i przyspieszy implementację nowych funkcji w istniejących potokach. Te zyski są spowodowane tym, że parametryzacja minimalizuje ilość kodowania twardego i zwiększa liczbę obiektów i procesów wielokrotnego użytku w rozwiązaniu.
Pojęcia dotyczące parametrów i wyrażeń
Parametry umożliwiają przekazywanie wartości zewnętrznych do potoków. Po przekazaniu parametru do zasobu nie można go zmienić. Parametryzując zasoby, można użyć ich ponownie z różnymi wartościami za każdym razem. Parametry mogą być używane indywidualnie lub jako część wyrażeń. Wartości parametrów w definicji mogą być literałami lub wyrażeniami, które są oceniane w czasie wykonywania.
Wyrażenia mogą być wyświetlane w dowolnym miejscu w wartości ciągu i zawsze generować inną wartość ciągu. Tutaj hasło jest parametrem potoku w wyrażeniu. Jeśli wartość parametru jest wyrażeniem, treść wyrażenia jest wyodrębniona przez usunięcie znaku at-sign (@). Jeśli potrzebny jest ciąg literału rozpoczynający się od @, należy go użyć przy użyciu @@. W poniższych przykładach pokazano, jak są oceniane wyrażenia.
| Wartość parametru | Result |
|---|---|
| "parameters" (parametry) | Zwracane są znaki "parameters". |
| "parameters[1]" | Zwracane są znaki "parameters[1]". |
| "@@" | Zwracany jest 1 ciąg znaków zawierający znak "@". |
| " @" | Zwracany jest 2-znakowy ciąg zawierający znak @. |
Wyrażenia mogą również pojawiać się wewnątrz ciągów przy użyciu funkcji nazywanej interpolacją ciągów, w której wyrażenia są opakowane w @{ ... }. Na przykład następujący ciąg zawiera wartości parametrów i wartości ciągu literału:
"Imię: @{pipeline().parameters.firstName} Nazwisko: @{pipeline().parameters.lastName}"
Przy użyciu interpolacji ciągów wynik jest zawsze ciągiem. Na przykład jeśli zdefiniowano myNumber jako 42 i myString jako foo:
| Wartość parametru | Result |
|---|---|
| "@pipeline().parameters.myString" | Zwraca foo jako ciąg. |
| "@{pipeline().parameters.myString}" | Zwraca foo jako ciąg. |
| "@pipeline().parameters.myNumber" | Zwraca 42 jako liczbę. |
| "@{pipeline().parameters.myNumber}" | Zwraca 42 jako ciąg. |
| "Odpowiedź brzmi: @{pipeline().parameters.myNumber}" | Zwraca ciąg Answer is: 42. |
| "@concat('Odpowiedź brzmi: ', string(pipeline().parameters.myNumber))" | Zwraca ciąg Answer is: 42 |
| "Odpowiedź brzmi: @@{pipeline().parameters.myNumber}" | Zwraca ciąg Answer is: @{pipeline().parameters.myNumber}. |
Przykłady użycia parametrów w wyrażeniach
Tworzenie i używanie parametrów
Aby utworzyć parametry, wybierz tło kanwy edytora potoków, a następnie kartę Parametry okna właściwości u dołu. Wybierz przycisk + Nowy, aby dodać nowy parametr do potoku, nadaj mu nazwę, typ danych i wartość domyślną:
Następnie możesz użyć parametru w dowolnym miejscu w potoku, w którym jest obsługiwana zawartość dynamiczna. W tym przykładzie parametr jest używany do dynamicznego podawania nazwy magazynu danych usługi Lakehouse na karcie Źródło stron właściwości działania kopiowania.
Zostanie wyświetlone okno Dodawanie zawartości dynamicznej, umożliwiające określenie dowolnego rodzaju zawartości dynamicznej, w tym parametrów, zmiennych systemowych, funkcji lub zmiennych potoku. W tym przykładzie wybrano wcześniej zdefiniowany parametr, a okno zawartości dynamicznej jest automatycznie wypełniane poprawnym wyrażeniem w celu odwołania się do parametru.
Przykład wyrażenia złożonego
Poniższy przykład przedstawia złożony przykład, który odwołuje się do głębokiego pola podrzędnego danych wyjściowych działań. Aby odwołać się do parametru potoku, który oblicza pole podrzędne, użyj składni [] zamiast operatora dot(.) (tak jak w przypadku podpola1 i podpola2)
@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*
Edytor zawartości dynamicznej
Edytor zawartości dynamicznej automatycznie uniknie znaków w zawartości po zakończeniu edycji. Na przykład następująca zawartość w edytorze zawartości to interpolacja ciągów z funkcją wyrażenia:
@{toUpper('myData')}
Edytor zawartości dynamicznej konwertuje powyższą zawartość na następujące wyrażenie:
MYDATA
Używanie funkcji i zmiennych w wyrażeniach
Funkcje można wywoływać i używać zmiennych w wyrażeniach. Poniższe sekcje zawierają informacje o funkcjach, które mogą być używane w wyrażeniu.
Zmienne zakresu potoku
Do tych zmiennych systemowych można odwoływać się w dowolnym miejscu w formacie JSON potoku.
| Nazwa zmiennej | opis |
|---|---|
| @pipeline().DataFactory | Nazwa danych lub obszaru roboczego usługi Synapse, w którym działa przebieg potoku |
| @pipeline().Pipeline | Nazwa potoku |
| @pipeline().RunId | Identyfikator określonego uruchomienia potoku |
| @pipeline().TriggerId | Identyfikator wyzwalacza, który wywołał potok |
| @pipeline().TriggerName | Nazwa wyzwalacza, który wywołał potok |
| @pipeline().TriggerTime | Czas uruchomienia wyzwalacza, który wywołał potok. Jest to czas, w którym wyzwalacz rzeczywiście został wyzwolony w celu wywołania uruchomienia potoku i może się nieco różnić od zaplanowanego czasu wyzwalacza. |
| @pipeline().GroupId | Identyfikator grupy, do której należy uruchomienie potoku. |
| @pipeline()?. TriggeredByPipelineName | Nazwa potoku, który wyzwala uruchomienie potoku. Ma zastosowanie, gdy uruchomienie potoku jest wyzwalane przez działanie ExecutePipeline. Oblicz wartość null , jeśli jest używana w innych okolicznościach. Zanotuj znak zapytania po @pipeline() |
| @pipeline()?. TriggeredByPipelineRunId | Identyfikator uruchomienia potoku, który wyzwala uruchomienie potoku. Ma zastosowanie, gdy uruchomienie potoku jest wyzwalane przez działanie ExecutePipeline. Oblicz wartość null , jeśli jest używana w innych okolicznościach. Zanotuj znak zapytania po @pipeline() |
Uwaga
Zmienne systemowe daty/godziny związane z wyzwalaczem (w zakresach potoku i wyzwalacza) zwracają daty UTC w formacie ISO 8601, na przykład 2017-06-01T22:20:00.4061448Z.
Funkcje ciągów
Aby pracować z ciągami, możesz użyć tych funkcji ciągów, a także niektórych funkcji kolekcji. Funkcje ciągów działają tylko na ciągach.
| Funkcja ciągu | Zadanie |
|---|---|
| Concat | Połącz co najmniej dwa ciągi i zwróć połączony ciąg. |
| Endswith | Sprawdź, czy ciąg kończy się określonym podciągem. |
| Identyfikator guid | Wygeneruj unikatowy identyfikator globalny (GUID) jako ciąg. |
| Indexof | Zwróć pozycję początkową dla podciągów. |
| Lastindexof | Zwróć pozycję początkową ostatniego wystąpienia podciągów. |
| replace | Zastąp podciąg określonym ciągiem i zwróć zaktualizowany ciąg. |
| split | Zwraca tablicę zawierającą podciągi oddzielone przecinkami od większego ciągu na podstawie określonego znaku ogranicznika w oryginalnym ciągu. |
| Startswith | Sprawdź, czy ciąg rozpoczyna się od określonego podciągu. |
| Podciąg | Zwraca znaki z ciągu, zaczynając od określonej pozycji. |
| Tolower | Zwraca ciąg w formacie małych liter. |
| Toupper | Zwraca ciąg w formacie wielkiej litery. |
| Przycinanie | Usuń białe znaki wiodące i końcowe z ciągu i zwróć zaktualizowany ciąg. |
Funkcje odbioru
Aby pracować z kolekcjami, zazwyczaj tablicami, ciągami, a czasami słownikami, można użyć tych funkcji kolekcji.
| Funkcja Collection | Zadanie |
|---|---|
| Zawiera | Sprawdź, czy kolekcja ma określony element. |
| empty | Sprawdź, czy kolekcja jest pusta. |
| Pierwszym | Zwróć pierwszy element z kolekcji. |
| Przecięcia | Zwróć kolekcję zawierającą tylko wspólne elementy w określonych kolekcjach. |
| join | Zwróć ciąg zawierający wszystkie elementy z tablicy oddzielone określonym znakiem. |
| Ostatnio | Zwróć ostatni element z kolekcji. |
| length | Zwraca liczbę elementów w ciągu lub tablicy. |
| Pominąć | Usuń elementy z przodu kolekcji i zwróć wszystkie inne elementy. |
| take | Zwracanie elementów z przodu kolekcji. |
| Unii | Zwróć kolekcję zawierającą wszystkie elementy z określonych kolekcji. |
Funkcje logiczne
Te funkcje są przydatne wewnątrz warunków, mogą służyć do oceny dowolnego typu logiki.
| Funkcja porównania logicznego | Zadanie |
|---|---|
| and | Sprawdź, czy wszystkie wyrażenia są prawdziwe. |
| equals | Sprawdź, czy obie wartości są równoważne. |
| greater | Sprawdź, czy pierwsza wartość jest większa niż druga wartość. |
| greaterOrEquals | Sprawdź, czy pierwsza wartość jest większa, czy równa drugiej wartości. |
| Jeśli | Sprawdź, czy wyrażenie ma wartość true, czy false. Na podstawie wyniku zwróć określoną wartość. |
| less | Sprawdź, czy pierwsza wartość jest mniejsza niż druga wartość. |
| lessOrEquals | Sprawdź, czy pierwsza wartość jest mniejsza, czy równa drugiej wartości. |
| nie | Sprawdź, czy wyrażenie jest fałszywe. |
| or | Sprawdź, czy co najmniej jedno wyrażenie ma wartość true. |
Funkcje konwersji
Te funkcje są używane do konwertowania między poszczególnymi typami natywnymi w języku:
- string
- integer
- liczba zmiennoprzecinkowa
- boolean
- Tablice
- Słowniki
| Funkcja konwersji | Zadanie |
|---|---|
| Tablicy | Zwraca tablicę z jednego określonego danych wejściowych. Aby uzyskać wiele danych wejściowych, zobacz createArray. |
| base64 | Zwróć wersję zakodowaną w formacie base64 dla ciągu. |
| base64ToBinary | Zwróć wersję binarną dla ciągu zakodowanego w formacie base64. |
| base64ToString | Zwraca wersję ciągu dla ciągu zakodowanego w formacie base64. |
| Binarnym | Zwraca wersję binarną dla wartości wejściowej. |
| bool | Zwróć wersję logiczną dla wartości wejściowej. |
| Łączonej | Zwraca pierwszą wartość inną niż null z co najmniej jednego parametru. |
| createArray | Zwraca tablicę z wielu danych wejściowych. |
| dataUri | Zwraca identyfikator URI danych dla wartości wejściowej. |
| dataUriToBinary | Zwróć wersję binarną identyfikatora URI danych. |
| dataUriToString | Zwróć wersję ciągu dla identyfikatora URI danych. |
| dekodujBase64 | Zwraca wersję ciągu dla ciągu zakodowanego w formacie base64. |
| decodeDataUri | Zwróć wersję binarną identyfikatora URI danych. |
| decodeUriComponent | Zwraca ciąg, który zastępuje znaki ucieczki dekodowanym wersjami. |
| Encodeuricomponent | Zwróć ciąg, który zastępuje znaki niebezpieczne adresu URL znakami ucieczki. |
| float | Zwraca liczbę zmiennoprzecinkową dla wartości wejściowej. |
| int | Zwróć wersję całkowitą dla ciągu. |
| Json | Zwróć wartość typu JavaScript Object Notation (JSON) lub obiekt dla ciągu lub XML. |
| string | Zwraca wersję ciągu dla wartości wejściowej. |
| uriComponent | Zwróć wersję zakodowaną w formacie URI dla wartości wejściowej, zastępując znaki niebezpieczne adresu URL znakami ucieczki. |
| uriComponentToBinary | Zwróć wersję binarną dla ciągu zakodowanego identyfikatorem URI. |
| uriComponentToString | Zwróć wersję ciągu dla ciągu zakodowanego identyfikatorem URI. |
| xml | Zwróć wersję XML dla ciągu. |
| Xpath | Sprawdź kod XML dla węzłów lub wartości, które są zgodne z wyrażeniem XPath (XML Path Language) i zwraca pasujące węzły lub wartości. |
Funkcje matematyczne
Te funkcje mogą być używane w przypadku obu typów liczb: liczb całkowitych i zmiennoprzecinkowych.
| Math, funkcja | Zadanie |
|---|---|
| add | Zwróć wynik z dodania dwóch liczb. |
| div | Zwróć wynik z dzielenia dwóch liczb. |
| Max | Zwraca najwyższą wartość z zestawu liczb lub tablicy. |
| Min | Zwraca najniższą wartość z zestawu liczb lub tablicy. |
| Mod | Zwróć resztę z dzielenia dwóch liczb. |
| Mul | Zwróć produkt z mnożenia dwóch liczb. |
| rand | Zwraca losową liczbę całkowitą z określonego zakresu. |
| range | Zwraca tablicę całkowitą rozpoczynającą się od określonej liczby całkowitej. |
| Sub | Zwróć wynik odejmowania drugiej liczby z pierwszej liczby. |
Funkcje daty
| Funkcja daty lub godziny | Zadanie |
|---|---|
| Adddays | Dodaj liczbę dni do znacznika czasu. |
| Addhours | Dodaj liczbę godzin do znacznika czasu. |
| Addminutes | Dodaj liczbę minut do znacznika czasu. |
| Addseconds | Dodaj liczbę sekund do znacznika czasu. |
| addToTime | Dodaj liczbę jednostek czasu do znacznika czasu. Zobacz również getFutureTime. |
| convertFromUtc | Przekonwertuj znacznik czasu z uniwersalnego czasu koordynowanego (UTC) na docelową strefę czasową. |
| convertTimeZone | Przekonwertuj znacznik czasu ze źródłowej strefy czasowej na docelową strefę czasową. |
| convertToUtc | Przekonwertuj znacznik czasu ze źródłowej strefy czasowej na uniwersalny czas koordynowany (UTC). |
| dayOfMonth | Zwróć dzień składnika miesiąca ze znacznika czasu. |
| Dayofweek | Zwróć dzień składnika tygodnia ze znacznika czasu. |
| Dayofyear | Zwraca dzień składnika roku ze znacznika czasu. |
| formatDateTime | Zwróć znacznik czasu jako ciąg w formacie opcjonalnym. |
| getFutureTime | Zwróć bieżący znacznik czasu oraz określoną liczbę jednostek czasu. Zobacz również addToTime. |
| getPastTime | Zwróć bieżący znacznik czasu minus określoną liczbę jednostek czasu. Zobacz również odejmowanieFromTime. |
| startOfDay | Zwróć początek dnia dla znacznika czasu. |
| startOfHour | Zwróć początek godziny dla znacznika czasu. |
| startOfMonth | Zwróć początek miesiąca dla znacznika czasu. |
| odejmowanieFromTime | Odejmij liczbę jednostek czasu z znacznika czasu. Zobacz również getPastTime. |
| Kleszcze | ticks Zwraca wartość właściwości dla określonego znacznika czasu. |
| Utcnow | Zwraca bieżący znacznik czasu jako ciąg. |