Nahrazení a proměnné v balíčcích prostředků Databricks

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.

Návod

Můžete také použít odkazy na dynamické hodnoty pro parametry úloh, abyste předali kontext spuštění úlohy jednotlivým úkolům. Viz Co je odkaz na dynamickou hodnotu? a Parametrizace úloh.

Náhrady

Nahrazení můžete použít k načtení hodnot nastavení, která se můžou změnit v závislosti na kontextu nasazení sady a spuštění. Například substituce lze použít k odkazování na hodnoty polí balíčků name, target a pracovního prostoru userName pro vytvoření pracovního prostoru root_path v konfiguračním souboru balíčku.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Pokud by someone@example.com nasadil tento balíček, byl by nasazen do kořenové cesty /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Můžete také vytvořit náhrady pro pojmenované prostředky. Například pro následující definici kanálu můžete použít ${resources.pipelines.my_pipeline.target} hodnotu cíle kanálu:

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

Pokud chcete určit platné náhrady, použijte odkaz na konfiguraci sady, odkaz na konfiguraci prostředku nebo hierarchii schématu příslušných objektů zdokumentovaných v odkazu na rozhraní REST API nebo výstup bundle schema příkazu.

Návod

Úplný seznam substitucí dostupných pro prostředky najdete v GitHub úložišti Databricks CLI out.fields.txt

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.domain_friendly_name}
${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í, jinde v konfiguračních souborech sady nebo v .databricks/bundle/<target>/variable-overrides.json souboru v projektu sady. Viz Nastavení hodnoty proměnné.

Odkaz na proměnnou

Pokud chcete odkazovat na vlastní proměnnou v rámci konfigurace sady, použijte nahrazení. Například následující konfigurace odkazuje 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 nenastavili default hodnotu proměnné nebo chcete dočasně přepsat default hodnotu proměnné, zadejte novou dočasnou hodnotu proměnné pomocí jednoho z následujících přístupů.

Poznámka:

Proměnné sady jsou proměnné času nasazení. Interpretují se při nasazení balíčku. Když například spustíte úlohu, spustí dříve nasazenou úlohu a nakonfigurované proměnné pro toto nasazení, takže předání různých hodnot proměnných pro spuštění úlohy se nepoužije. Místo toho předejte hodnoty spuštění úlohy pomocí parametrů úlohy. Viz Parametry předávané úlohy.

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"
```
Poskytněte 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"
```
Zadejte hodnotu proměnné v konfiguračních souborech sady pomocí variables mapování v rámci targets mapování, a to v následujícím 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 .databricks/bundle/<target>/variable-overrides.json souboru 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 jakékoli sadě proměnných prostředí, které začínají na 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 je pro proměnnou definována jako 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/bundle/<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 typy objektů alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal a warehouse můžete definovat lookup pro vaši vlastní proměnnou k načtení 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}

Nahrazení výstupu a hodnoty proměnných

Pokud chcete zajistit správné zadání a parsování substitucí a proměnných pomocí Databricks Asset Bundles, spusťte databricks bundle validate. Podívejte se na ověření sady databricks. Pokud chcete zobrazit hodnoty, které se použijí při nasazení sady, použijte --output json tuto možnost:

databricks bundle validate --output json

Například pro sadu s proměnnou my_cluster_id definovanou a použitou v úloze úlohy:

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

Výstup databricks bundle validate schématu by byl následující:

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}

Váš názor

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

Last updated on 2026-01-16

Sdílet prostřednictvím

Nahrazení a proměnné v balíčcí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

Nahrazení výstupu a hodnoty proměnných

Váš názor

Další materiály