Databricks Asset Bundles 中的替代項和變數

Databricks Asset Bundles 支援替代和自訂變數，讓您的套件組合設定檔更加模組化且可重複使用。替代和自定義變數都能夠動態擷取值，以便在部署和執行套件組合時判斷設定。

提示

您也可以使用動態值引用作為工作參數值，將作業執行過程中的上下文資訊傳遞至工作任務。請參閱什麼是動態值參考？和參數化工作。

替代品

您可以使用替代來擷取可能根據套件組合部署和執行內容而變更的設定值。例如，子區可用來參考套件組合name、套件組合target和工作區欄位的值，以建構套件組合組態檔中的工作區userNameroot_path：

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

如果 someone@example.com 部署此套件組合，則會部署到根路徑 /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev。

您也可為具名資源建立替代項目。例如，針對下列管線定義，您可以針對管線目標的值使用 ${resources.pipelines.my_pipeline.target} ：

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

若要判斷有效的替代專案，請使用套件組合組態參考、資源組態參考或 REST API 參考中記載之對應物件的架構階層，或 bundle schema 命令的輸出。

提示

如需完整的資源替代清單，請參閱 Databricks CLI GitHub 倉庫 out.fields.txt

以下是一些常用的替代項目：

${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}

自訂變數

您可以在套件組合中定義簡單且複雜的自定義變數，以啟用許多案例所需的值動態擷取。自定義變數會在 variables 對應或 variable-overrides.json 檔案的套件組態檔中宣告。關於 variables 對應的資訊，請參閱變數。

下列範例組態會定義變數 my_cluster_id 和 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

如果您未在此宣告中提供 default 變數的值，則必須在執行套件組合命令、透過環境變數、套件組合組態檔內的其他地方，或在套件組合專案中的 .databricks/bundle/<target>/variable-overrides.json 檔案中設定它。請參閱設定變數的值。

參考變數

若要在套件組合設定中引用自訂變數，請使用變數替代。例如，下列組態會參考變數 my_cluster_id 和 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}

設定變數的值

如果您尚未設定 default 變數的值，或想要暫時覆寫 default 變數的值，請使用下列其中一種方法提供變數的新暫存值。

注意

配套變數是部署時間變數。當您部署軟體組時，會解譯它們。例如，當您執行工作時，系統會執行先前部署的工作以及為該部署配置的變數，因此在執行工作時，為變數傳遞不同的值將不會生效。相反地，請使用作業參數將值傳遞至作業運行。請參閱傳遞工作參數。

提供變數的值做為命令的一 bundle 部分，例如 validate、 deploy或 run。若要這樣做，請使用選項 --var="<key>=<value>"，其中 <key> 是變數的名稱，而 <value> 是變數的值。例如，在 bundle validate 命令中，若要將 1234-567890-abcde123 的值提供給名為 my_cluster_id 的變數，並將 ./hello.py 的值提供給名為 my_notebook_path 的變數，請執行：
```
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"
```
藉由設定環境變數來提供變數的值。環境變數的名稱必須以 BUNDLE_VAR_開頭。若要設定環境變數，請參閱作業系統的文件。例如，若要將 1234-567890-abcde123 的值提供給名為 my_cluster_id 的變數，並將 ./hello.py 的值提供給名為 my_notebook_path 的變數，請執行下列命令，然後再呼叫 bundle 命令，如 validate、deploy 或 run：

針對 Linux 與 macOS：
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
對於 Windows：
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
或者，提供變數的值作為命令的一部分，例如在 Linux 和 macOS 上的 bundle、validate、deploy 或 run。
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
或用於 Windows：
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```

請使用 variables 映射內的 targets 映射，以套件組態檔案格式提供變數值，請遵循下列格式：

variables:
  <variable-name>: <value>

例如，要為名為 my_cluster_id 和 my_notebook_path 的變數分別設定值以對應兩個不同的目標：

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

請使用下列格式在 .databricks/bundle/<target>/variable-overrides.json 檔案中提供變數的值：
```
{
  "<variable-name>": "<variable-value>"
}
```
例如，若要為名為 my_cluster_id 的變數提供值，並針對開發目標 my_notebook_path，請建立檔案 .databricks/bundle/dev/variable-overrides.json，並將其內容設定為：
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
您也可以在 variable-overrides.json 檔案中定義複雜的變數。

注意

無論您選擇哪一種方法提供變數值，在部署和執行階段都使用相同的方法。否則，您可能會在部署期間和以該現有部署為基礎的作業或管線運行之間得到非預期的結果。

優先順序順序

Databricks CLI 會依下列順序尋找變數的值，並在找到變數的值時停止：

在任何指定為 --var 命令一部分的 bundle 選項內。
在以 BUNDLE_VAR_開頭的任何環境變數集合內。
在 variables-overrides.json 檔案內，如果它存在的話。
在任何 variables 對應中，在套件組合設定檔內的 targets 對應之間。
該變數定義的任何 default 值，在套件組合組態檔內的最上層 variables 對應中。

定義複雜變數

除非您將自訂變數定義為複雜變數，否則會假設自訂變數的類型為字串。若要在套件組合元件中定義具有複雜類型的自訂變數，請將 type 設定為 complex。

注意

type 設定的唯一有效值為 complex。此外，如果 type 設定為 complex，且為變數定義的 default 是單一值，則套件組合驗證會失敗。

在下列範例中，叢集設定在名為 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

您也可以在 .databricks/bundle/<target>/variable-overrides.json 檔案中定義複雜變數，如下列範例所示：

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

擷取對象的標識碼值

alert、cluster_policy、cluster、dashboard、instance_pool、job、metastore、notification_destination、pipeline、query、service_principal 和 warehouse 物件類型，您可以為自訂變數定義一個 lookup，以使用此格式來擷取具名物件的識別碼：

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

如果為變數定義查閱，則會使用具有指定名稱的物件識別碼作為變數的值。這可確保物件的正確解析識別碼一律用於變數。

注意

如果具有指定名稱的物件不存在，或有多個具有指定名稱的物件，就會發生錯誤。

例如，在下列組態中，${var.my_cluster_id} 將會由 12.2 共用叢集的識別碼取代。

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}

輸出替代和變數值

若要確保您的替代項目和變數已由 Databricks 資產組合正確指定和剖析，請執行 databricks bundle validate。請參閱 databricks 套件組合驗證。若要檢視當您部署套件組合時將使用的值，請使用 --output json 選項：

databricks bundle validate --output json

例如，針對在工作任務中定義並使用的變數 my_cluster_id 的套件組合：

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

架構 databricks bundle validate 輸出如下：

{
  "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"
    }
  },
"..."
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-04