Używanie parametrów z potokami

Parametry potoku umożliwiają ponowne użycie tego samego kodu źródłowego potoku w środowiskach lub zestawach danych. Na przykład można uruchamiać te same przekształcenia na katalogach dev i prod lub przy każdym uruchomieniu pobierać dane z innej ścieżki źródłowej. Definiujesz parametry w potoku (lub nadpisujesz je podczas uruchamiania aktualizacji) i odwołujesz się do nich w kodzie źródłowym SQL.

Ważne

Ta funkcja jest dostępna w wersji beta. Administratorzy obszaru roboczego mogą kontrolować dostęp do tej funkcji ze strony Podglądy . Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Na tej stronie opisano funkcję parametrów potoku dostępną dla kodu źródłowego SQL. Aby parametryzować kod źródłowy w języku Python w potoku, nadal używaj pola Configuration, zgodnie z opisem w sekcji Odwoływanie się do parametrów za pomocą pola konfiguracji. Konfiguracja służy również do ustawiania wartości konfiguracji Spark, które potoki odczytują w czasie wykonywania. Aby uzyskać szczegółowe informacje na temat ustawień konfiguracji platformy Spark, zobacz Dokumentacja właściwości potoku.

Czym są parametry pipeline'u?

Parametry potoku to pary klucz-wartość, które można:

Ustaw jako domyślne w ustawieniach potoku przetwarzania.
Nadpisz podczas uruchamiania aktualizacji z poziomu interfejsu użytkownika potoku, API „Uruchom aktualizację” lub okna dialogowego Uruchom z innymi ustawieniami.
Zastąp zadanie potoku w zadaniu za pomocą opcjonalnego wypychania parametrów na poziomie zadania.
Odwołuj się do kodu źródłowego SQL przy użyciu składni parametru nazwanego.

Wartości parametrów są zawsze ciągami. Klucze mogą zawierać znaki alfanumeryczne, podkreślenia (_), łączniki (-) i kropki (.).

Parametry potoku i pole Konfiguracja służą do różnych celów:

Użyj parametrów dla...	Użyj konfiguracji dla...
Wartości zmieniające się między aktualizacjami (katalog docelowy, ścieżka źródłowa, zakres dat).	Konfiguracja Spark, która steruje zachowaniem potoku przetwarzania (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Wartości, które mają być przekazywane w dół z zadania zbiorczego lub zadania.	Statyczne właściwości strukturalne pipeline’u.
Wartości, do których odwołujesz się w języku SQL z nazwaną składnią parametrów.	Wartości, do których odwołujesz się za pomocą składni `${key}` w języku SQL lub `spark.conf.get("key")` w języku Python.

Definiowanie parametrów potoku

Domyślne wartości parametrów można zdefiniować w ustawieniach potoku. Gdy aktualizacja jest uruchamiana bez przesłonięć, potok używa tych wartości domyślnych.

Użyj interfejsu użytkownika potoku

W obszarze roboczym na pasku bocznym kliknij Zadania i potoki i wybierz swój potok.
Kliknij przycisk Ustawienia.
Na pasku bocznym Ustawienia potoku znajdź sekcję Parametry i kliknij pozycję Edytuj.
Dodaj wpisy Klucz i Wartość , a następnie kliknij przycisk Zapisz.

Korzystanie z interfejsu API REST lub JSON

parameters Dodaj mapę do definicji potoku:

{
  "name": "Sales pipeline",
  "parameters": {
    "source_catalog": "dev_catalog",
    "source_schema": "sales",
    "start_date": "2026-01-01"
  }
}

Pełne informacje referencyjne dotyczące kodu JSON potoku można znaleźć w artykule Konfiguracje potoku.

Parametry referencyjne w kodzie źródłowym SQL

Odwołuj się do parametru, prefiksując klucz dwukropkiem. Azure Databricks wiąże wartość jako ciąg w czasie aktualizacji:

CREATE OR REFRESH MATERIALIZED VIEW transaction_summary AS
SELECT account_id,
  COUNT(txn_id) AS txn_count,
  SUM(txn_amount) AS account_revenue
FROM :source_catalog.sales.transactions
WHERE txn_date >= :start_date
GROUP BY account_id

Aby użyć parametru w pozycji identyfikatora, takiej jak wykaz, schemat lub nazwa tabeli, zawiń go w pliku IDENTIFIER():

USE CATALOG IDENTIFIER(:source_catalog);
USE SCHEMA IDENTIFIER(:source_schema);

CREATE OR REFRESH MATERIALIZED VIEW daily_sales AS
SELECT date(timestamp) AS date,
  SUM(price) AS total_sales
FROM transactions
GROUP BY date;

Jeśli kod źródłowy odwołuje się do parametru, który nie ma wartości w czasie aktualizacji, aktualizacja kończy się niepowodzeniem z powodu błędu. Potok przetwarzania ignoruje dodatkowe parametry, do których kod się nie odwołuje.

Przesłanianie parametrów w czasie aktualizacji

Można zastąpić wartości parametrów dla pojedynczej aktualizacji bez zmiany zapisanych wartości domyślnych.

W interfejsie potoku kliknij Uruchom z różnymi ustawieniami i edytuj sekcję Parametry.
Z zadania potoku w zadaniu ustaw przesłonięcia parametrów w polu Parametry zadania. Zobacz Parametry.
Z poziomu interfejsu API przekaż parameters mapę w żądaniu rozpoczęcia aktualizacji .

Azure Databricks rejestruje parametry określonej aktualizacji w historii aktualizacji i wyświetla je w kolumnie Parametry uruchomienia na liście uruchomień potoku.

Pierwszeństwo parametrów

Jeśli zdefiniujesz ten sam klucz w więcej niż jednym miejscu, wartość o najwyższym pierwszeństwie wygrywa. Od najwyższego do najniższego:

Parametry przebiegu zadania: wartości podane dla pojedynczego uruchomienia zadania (przesłonięcia).
Parametry zadania: wartości domyślne zdefiniowane w zadaniu nadrzędnym.
Parametry zadania potoku: wartości ustawione dla zadania potoku.
Parametry potoku: wartości domyślne zdefiniowane w ustawieniach potoku.

Jest to zgodne z priorytetem stosowanym przez inne typy zadań parametrów zadania.

Parametry potoku w Lakeflow Jobs

Gdy zaplanujesz potok jako zadanie potoku w zadaniu, to zadanie może przekazywać parametry, które zastąpią domyślne wartości potoku. Wartości parametrów mogą korzystać z dynamicznych odwołań do wartości, aby wstawiać wartości dostępne w czasie wykonywania zadania, takie jak {{job.trigger.time.iso_date}} lub {{job.parameters.region}}.

Lakeflow Jobs również automatycznie przekazuje wszystkie parametry zadania do zadań potoku, tak samo jak do zadań notebooków i SQL. Kod źródłowy potoku może odwoływać się do dowolnej wartości przekazanej niżej przy użyciu składni nazwanych parametrów. Deklarowanie parametru w ustawieniach potoku jest opcjonalne i służy jedynie do ustawienia wartości domyślnej dla uruchomień, jeśli nie podano wartości zastępującej.

Zastrzeżenia i znane ograniczenia

Potoki uruchamiają jedną aktualizację jednocześnie: potok może uruchamiać tylko jedną aktualizację jednocześnie. Aby zapobiec niepowodzeniu zadań, gdy w przeciwnym razie wiele aktualizacji nakładałoby się na siebie, Azure Databricks ogranicza współbieżność do 1 w dwóch scenariuszach:
- Zadanie, które zawiera zadanie potoku i jest skonfigurowane z max_concurrent_runs więcej niż jednym.
- Zadanie potoku opakowane w zadanie for-each, niezależnie od liczby iteracji.
Interfejs użytkownika zadania wyświetla powiadomienie, gdy ten limit zostanie zastosowany. Uwzględnij limit podczas projektowania sparametryzowanych potoków, które zamierzasz uruchamiać dla wielu kombinacji parametrów.
Filtry dat mogą wyzwalać pełne odświeżanie: typowym przypadkiem użycia parametryzacji jest filtrowanie danych według daty. Zachowaj ostrożność przy użyciu predykatów: filtrowanie po obu stronach zakresu dat powoduje unieważnienie przetwarzania przyrostowego w zmaterializowanych widokach i wyzwala pełne odświeżanie każdej aktualizacji.
```
-- Triggers a full refresh on each update
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date AND order_date < :end_date;
```
```
-- Processes incrementally
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date;
```
Parametry nazwane są dostępne tylko w SQL: W tej wersji beta składnia nazwanych parametrów może być używana tylko w kodzie źródłowym SQL. Aby sparametryzować kod źródłowy w języku Python, nadal używaj pola Configuration z spark.conf.get(). Zobacz Parametry referencyjne za pomocą pola konfiguracji.

Odwołuj się do parametrów za pomocą pola konfiguracji

Pole Konfiguracja w potoku akceptuje dowolne pary klucz-wartość, które są widoczne jako wartości konfiguracji platformy Spark. Jest to starszy mechanizm parametryzacji i nadal działa równolegle z parametrami potoku. Użyj go w przypadku kodu źródłowego Python oraz kluczy, które chcesz odczytywać za pomocą spark.conf.get(), a nie składni nazwanych parametrów.

W poniższym przykładzie użyto mypipeline.start_date wartości konfiguracji, aby ograniczyć potok programowania do podzestawu danych wejściowych:

SQL

CREATE OR REFRESH MATERIALIZED VIEW customer_events
AS SELECT * FROM source_table WHERE date > '${mypipeline.start_date}';

Python

from pyspark import pipelines as dp
from pyspark.sql.functions import col

@dp.table
def customer_events():
  start_date = spark.conf.get("mypipeline.start_date")
  return spark.read.table("source_table").where(col("date") > start_date)

Wartości konfiguracji można ustawić w sekcji Konfiguracja ustawień potoku lub w configuration polu potoku JSON. Unikaj kluczy, które powodują konflikt z wartościami konfiguracji potoku zarezerwowanego lub platformy Apache Spark.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-06-01