Použití parametrů s kanály

Parametry kanálu umožňují opakovaně používat stejný zdrojový kód kanálu napříč prostředími nebo datovými sadami. Můžete například spustit stejné transformace pro dev a prod katalogy nebo ingestovat z jiné zdrojové cesty při každém spuštění. Parametry definujete v pipeline (nebo při spuštění aktualizace přepíšete jejich hodnoty) a odkazujete na ně ze zdrojového kódu SQL.

Důležité

Tato funkce je v beta verzi. Správci pracovního prostoru můžou řídit přístup k této funkci ze stránky Previews . Viz Manage Azure Databricks preview.

Parametry kanálu jsou dostupné pouze ve zdrojovém kódu SQL. Chcete-li parametrizovat zdrojový kód v jazyce Python v pipeline, použijte pole Configuration, jak je popsáno v části Odkazování na parametry pomocí pole konfigurace. Konfigurace se používá také k nastavení hodnot konfigurace Sparku, které kanály čtou za běhu. Podrobnosti o nastavení konfigurace Sparku najdete v referenčních informacích o vlastnostech kanálu.

Co jsou parametry kanálu?

Parametry kanálu pipeline jsou dvojice klíč–hodnota, které můžete:

Deklarujte jako výchozí hodnoty v nastavení kanálu.
Přepsat při spuštění aktualizace z uživatelského rozhraní pipeline, rozhraní API Spustit aktualizaci nebo dialogu Spustit s jiným nastavením
Přepsání u úlohy kanálu v jobu s volitelným předáním parametrů na úrovni jobu.
Odkaz ze zdrojového kódu SQL pomocí syntaxe pojmenovaného parametru

Hodnoty parametrů jsou vždy řetězce. Klíče můžou obsahovat alfanumerické znaky, podtržítka (_), pomlčky (-) a tečky (.).

Parametry kanálu a pole Konfigurace slouží k různým účelům:

Použijte Parameters pro...	Použijte Konfiguraci pro...
Hodnoty, které se mění mezi aktualizacemi (cílový katalog, zdrojová cesta, rozsah kalendářních dat).	Konfigurace Sparku, která řídí chování kanálu (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Hodnoty, které chcete přesunout z úlohy nebo úkolu,	Statické, strukturální vlastnosti kanálu.
Hodnoty, na které odkazujete v SQL s pojmenovanou syntaxí parametrů.	Hodnoty, na které odkazujete pomocí syntaxe `${key}` v JAZYCE SQL nebo `spark.conf.get("key")` v Python

Definování parametrů kanálu

Výchozí hodnoty parametrů můžete definovat v nastavení kanálu. Když se aktualizace spustí bez přepsání výchozích nastavení, pipeline použije tato výchozí nastavení.

Použití uživatelského rozhraní pipeline

V pracovním prostoru klikněte na Úlohy a kanály na bočním panelu a vyberte kanál.
Klikněte na Nastavení.
Na bočním panelu nastavení kanálu najděte oddíl Parametry a klikněte na Upravit.
Přidejte položky klíč a hodnota a potom klikněte na Uložit.

Použijte rozhraní JSON nebo REST API

parameters Přidejte mapu do definice JSON kanálu, a to buď v nastavení kanálu, nebo při použití rozhraní REST API:

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

Úplné referenční informace k kódu JSON kanálu najdete v tématu Konfigurace kanálu.

Použijte YAML nebo svazky deklarativní automatizace

Definujte parametry v parameters mapování definice YAML kanálu, a to buď v nastavení kanálu, nebo v deklarativních balíčcích automatizace (co jsou deklarativní balíčky automatizace?):

resources:
  pipelines:
    my_pipeline:
      name: Sales pipeline
      parameters:
        source_catalog: dev_catalog
        source_schema: sales
        start_date: '2026-01-01'

Referenční parametry ve zdrojovém kódu SQL

Na parametr odkažte tak, že před klíč přidáte dvojtečku. Azure Databricks váže hodnotu jako řetězec v době aktualizace:

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

Chcete-li použít parametr v pozici identifikátoru, například katalog, schéma nebo název tabulky, zabalte ho do 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;

Pokud zdrojový kód odkazuje na parametr, který nemá v době aktualizace žádnou hodnotu, aktualizace selže s chybou. Kanál ignoruje další parametry, na které kód neodkazuje.

Přepsat parametry při aktualizaci

Hodnoty parametrů pro jednu aktualizaci můžete přepsat beze změny uložených výchozích hodnot.

V uživatelském rozhraní pipeline klikněte na Spustit s jiným nastavením a upravte sekci Parametry.
V úloze kanálu v rámci úlohy nastavte přepsání parametrů v poli Parametry této úlohy. Viz parametry.
Z rozhraní API předejte parameters mapu v požadavku Na zahájení aktualizace .

Azure Databricks zaznamenává parametry konkrétní aktualizace do historie aktualizací a zobrazuje je ve sloupci Parametry spuštění v seznamu spuštění kanálu.

Priorita parametru

Když definujete stejný klíč na více než jednom místě, hodnota s nejvyšší prioritou vyhraje. Od nejvyšších po nejnižší:

Parametry spuštění úlohy: hodnoty zadané pro konkrétní spuštění úlohy (přepisují výchozí hodnoty).
Parametry úlohy: výchozí hodnoty definované v nadřazené úloze.
Parametry úlohy kanálu: hodnoty nastavené pro úlohu kanálu.
Parametry kanálu: výchozí hodnoty definované v nastavení kanálu

To odpovídá pořadí přednosti používanému u jiných typů úloh parametrů jobu.

Parametry kanálu v úlohách Lakeflow

Když v rámci úlohy naplánujete pipeline jako úlohu pipeline, může tato úloha předat parametry, které přepíšou výchozí nastavení pipeline. Hodnoty parametrů mohou používat dynamické odkazy na hodnoty k vložení hodnot za běhu úlohy, například {{job.trigger.time.iso_date}} nebo {{job.parameters.region}}. Chcete-li odkazovat na hodnotu nastavenou upstreamovým úkolem, použijte {{tasks.<task_name>.values.<value_name>}}. Viz Použití hodnot úkolů k předávání informací mezi úkoly.

Úlohy Lakeflow také automaticky předávají všechny parametry úlohy do úloh kanálu, stejně jako do notebookových úloh a úloh SQL. Zdrojový kód kanálu může odkazovat na libovolnou předanou hodnotu pomocí syntaxe pojmenovaných parametrů. Deklarace parametru v nastavení pipeline je volitelná a pouze nastaví výchozí hodnotu pro spuštění bez přepsání.

Upozornění a známá omezení

Kanály spouští jednu aktualizaci najednou: Kanál může spustit pouze jednu aktualizaci najednou. Pokud chcete zabránit selhání úloh v případě, že by se jinak překrývalo více aktualizací, Azure Databricks v dvou scénářích omezí souběžnost na 1:
- Úloha, která obsahuje úlohu kanálu a je nakonfigurovaná s více úlohami max_concurrent_runs .
- Úloha v kanálu zabalená do úlohy for-each, bez ohledu na počet iterací.
Uživatelské rozhraní úlohy zobrazí oznámení, když se tento limit projeví. Při navrhování parametrizovaných pipeline, které chcete spouštět s mnoha kombinacemi parametrů, berte v úvahu tento limit.
Filtry kalendářních dat můžou aktivovat úplné aktualizace: Běžným případem použití parametrizace je filtrování dat podle data. Pozor na predikáty: Filtrování na obou hranicích datumového rozmezí znemožňuje přírůstkové zpracování u materializovaných zobrazení a při každé aktualizaci spustí úplné obnovení.
```
-- 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;
```
Pojmenované parametry jsou pouze SQL: V této beta verzi lze pojmenovanou syntaxi parametrů použít pouze ve zdrojovém kódu SQL. Chcete-li parametrizovat zdrojový kód v jazyce Python, pokračujte v používání pole Configuration s spark.conf.get(). Viz Referenční parametry pomocí konfiguračního pole.

Referenční parametry pomocí konfiguračního pole

Pole Konfigurace v rámci kanálu přijímá libovolné páry klíč–hodnota, které jsou k dispozici jako konfigurační hodnoty Sparku. Jedná se o starší mechanismus parametrizace a pokračuje v práci s parametry kanálu. Použijte ho pro Python zdrojový kód a pro klíče, které chcete číst pomocí spark.conf.get() místo pojmenované syntaxe parametrů.

Následující příklad používá mypipeline.start_date konfigurační hodnotu k omezení vývojového kanálu na podmnožinu vstupních dat:

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)

Hodnoty konfigurace nastavíte v části Konfigurace nastavení kanálu nebo v configuration poli JSON kanálu. Vyhněte se klíčům, které jsou v konfliktu s hodnotami konfigurace rezervovaného kanálu nebo Apache Sparku.

Dodatečné zdroje

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-06-25