Nahrazení a proměnné v sadách prostředků Databricks

Článek
02/09/2025

Sady prostředků Databricks podporují náhrady a vlastní proměnné, díky kterým jsou konfigurační soubory sady modulární a opakovaně použitelné. Nahrazení i vlastní proměnné umožňují dynamické načítání hodnot, aby bylo možné určit nastavení v době nasazení a spuštění sady.

Tip

Můžete také použít odkazy na dynamické hodnoty pro hodnoty parametrů úlohy k předání kontextu o úloze spuštěné do úkolů úloh. Viz Co je odkaz na dynamickou hodnotu? a Parametrizovat úlohy.

Náhrady

Nahrazení můžete použít k načtení hodnot nastavení, která se mění v závislosti na kontextu nasazení sady a spuštění.

Například při spuštění bundle validate --output json příkazu se může zobrazit graf podobný tomuto:

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Nahrazení lze použít k odkazování na hodnoty sady name, sady targetprostředků a polí pracovního prostoru userName k vytvoření pracovního prostoru root_path v konfiguračním souboru sady:

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

Můžete také vytvořit náhrady pro pojmenované prostředky. Například pro kanál nakonfigurovaný s názvem my_pipeline${resources.pipelines.my_pipeline.target} je náhrada hodnoty cíle my_pipeline.

K určení platných náhrad můžete použít hierarchii schématu zdokumentovanou v odkazu na rozhraní REST API nebo výstup bundle schema příkazu.

Tady jsou některé běžně používané náhrady:

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}

Vlastní proměnné

V sadě můžete definovat jednoduché i složité vlastní proměnné, které umožňují dynamické načítání hodnot potřebných pro mnoho scénářů. Vlastní proměnné jsou deklarovány v konfiguračních souborech sady v rámci mapování variables nebo v variable-overrides.json souboru. Informace k mapování variables naleznete v části : proměnné.

Následující příklad konfigurace definuje proměnné my_cluster_id a my_notebook_path:

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

Pokud v rámci této deklarace nezadáte default hodnotu proměnné, musíte ji nastavit při provádění příkazů sady, prostřednictvím proměnné prostředí nebo jinde v konfiguračních souborech sady, jak je popsáno v části Nastavení hodnoty proměnné.

Můžete také definovat a nastavit hodnoty proměnných v souboru .databricks/bundle/<target>/variable-overrides.json v projektu sady, kde <target> je cíl pracovního prostoru, například dev. Viz Nastavení hodnoty proměnné.

Odkaz na proměnnou

Pokud chcete odkazovat na vlastní proměnnou v rámci konfigurace sady, použijte nahrazení. Pokud chcete například odkazovat na proměnné my_cluster_id a my_notebook_path:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

Nastavení hodnoty proměnné

Pokud jste nezadáli default hodnotu proměnné nebo pokud chcete dočasně přepsat default hodnotu proměnné, zadejte novou dočasnou hodnotu proměnné jedním z následujících přístupů:

Zadejte hodnotu proměnné jako součást bundle příkazu, například validate, deploynebo run. K tomu použijte možnost --var="<key>=<value>", kde <key> je název proměnné a <value> je hodnota proměnné. Například jako součást bundle validate příkazu zadejte hodnotu 1234-567890-abcde123 proměnné s názvem my_cluster_ida zadejte hodnotu ./hello.py proměnné s názvem my_notebook_path, spusťte:
```
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
```
Zadejte hodnotu proměnné nastavením proměnné prostředí. Název proměnné prostředí musí začínat na BUNDLE_VAR_. Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému. Pokud chcete například zadat hodnotu 1234-567890-abcde123 proměnné s názvem my_cluster_ida zadat hodnotu ./hello.py proměnné s názvem my_notebook_path, spusťte následující příkaz před voláním bundle příkazu, například validate, deploynebo run:

Pro Linux a macOS:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Pro Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
Nebo zadejte hodnotu proměnné jako součást bundle příkazu, například validate, deploynebo run, například pro Linux a macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Nebo pro Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Uveďte hodnotu proměnné v konfiguračních souborech sady pomocí mapování variables v rámci mapování targets, a to v tomto formátu:
```
variables:
  <variable-name>: <value>
```
Pokud chcete například nastavit hodnoty proměnných pojmenovaných my_cluster_id a my_notebook_path pro dva samostatné cíle:
```
targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py
```
Zadejte hodnotu proměnné v souboru .databricks/bundle/<target>/variable-overrides.json pomocí následujícího formátu:
```
{
  "<variable-name>": "<variable-value>"
}
```
Pokud chcete například zadat hodnoty proměnných pojmenovaných my_cluster_id a my_notebook_path pro vývojový cíl, vytvořte soubor .databricks/bundle/dev/variable-overrides.json a nastavte jeho obsah na:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
V souboru variable-overrides.json můžete také definovat složité proměnné.

Poznámka:

Bez ohledu na to, který přístup zvolíte k zadání hodnot proměnných, použijte stejný přístup při nasazení i ve fázích spuštění. V opačném případě se můžou zobrazit neočekávané výsledky mezi časem nasazení a spuštěním úlohy nebo kanálu, které je založené na daném existujícím nasazení.

Pořadí priorit

Rozhraní příkazového řádku Databricks hledá hodnoty proměnných v následujícím pořadí a zastaví se, když najde hodnotu proměnné:

V rámci všech --var možností zadaných jako součást bundle příkazu.
V libovolné sadě proměnných prostředí, které začínají BUNDLE_VAR_.
V souboru variables-overrides.json, pokud existuje.
V rámci všech variables mapování mezi targets mapováními v konfiguračních souborech sady.
Jakákoli default hodnota pro definici této proměnné, mezi mapováními nejvyšší úrovně variables v rámci konfiguračních souborů sady.

Definování komplexní proměnné

Předpokládá se, že vlastní proměnná je typu řetězec, pokud ji nedefinujete jako složitou proměnnou. Pokud chcete definovat vlastní proměnnou se složitým typem pro svůj balíček v jeho konfiguraci, nastavte type na complex.

Poznámka:

Jedinou platnou type hodnotou pro nastavení je complex. Kromě toho se ověření sady nezdaří, pokud type je nastaveno complex a default definované pro proměnnou je jedna hodnota.

V následujícím příkladu jsou nastavení clusteru definována v rámci vlastní komplexní proměnné s názvem my_cluster:

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

V souboru .databricks/bundles/<target>/variable-overrides.json můžete také definovat složitou proměnnou, jak je znázorněno v následujícím příkladu:

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

Načtení hodnoty ID objektu

Pro alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principala typy objektů warehouse můžete definovat lookup pro vlastní proměnnou a načíst ID pojmenovaného objektu pomocí tohoto formátu:

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Pokud je vyhledávání definováno pro proměnnou, ID objektu se zadaným názvem se použije jako hodnota proměnné. Tím se zajistí, že se pro proměnnou vždy použije správné vyřešené ID objektu.

Poznámka:

K chybě dojde, pokud neexistuje objekt se zadaným názvem nebo pokud existuje více než jeden objekt se zadaným názvem.

Například v následující konfiguraci ${var.my_cluster_id} se nahradí ID 12.2 sdíleného clusteru.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

Sdílet prostřednictvím

Nahrazení a proměnné v sadách prostředků Databricks

Náhrady

Vlastní proměnné

Odkaz na proměnnou

Nastavení hodnoty proměnné

Pořadí priorit

Definování komplexní proměnné

Načtení hodnoty ID objektu

Váš názor

Další materiály