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

Článek
12/06/2024

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é se deklarují v konfiguračních souborech sady v rámci variables mapování. Viz 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é.

Pokud chcete odkazovat na vlastní proměnnou v rámci konfigurace sady, použijte nahrazení${var.<variable_name>}. 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"
```
Zadejte hodnotu proměnné v konfiguračních souborech sady. K tomu použijte variables mapování v rámci targets mapování, které následuje v tomto formátu:
```
variables:
  <variable-name>: <value>
```
Pokud například chcete zadat hodnoty pro pojmenované my_cluster_id proměnné 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
```

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í.

V předchozích příkladech rozhraní příkazového řádku Databricks vyhledá hodnoty proměnných my_cluster_id a my_notebook_path v následujícím pořadí se zastaví, když najde hodnotu pro každou odpovídající proměnnou, přeskočí všechna ostatní umístění pro danou proměnnou:

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 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 sady, nastavte type ji complex v konfiguraci sady.

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

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é

Nastavení hodnoty proměnné

Definování komplexní proměnné

Načtení hodnoty ID objektu

Váš názor

Další materiály