Databricks Asset Bundles 中的替代和變數

發行項
12/20/2024

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

提示

您也可使用工作參數值的動態值參考，將工作執行的內容傳遞至工作任務。請參閱什麼是動態值參考？和參數化工作。

替代

您可使用替代項目來擷取根據套件組合部署和執行的內容而變更的設定值。

例如，當您執行 bundle validate --output json 命令時，可能會看到如下的圖表：

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

子區可用來參考套件組合 name、套件組合 target 和工作區 userName 欄位的值，以建構套件組合設定檔中的工作區 root_path：

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

您也可為具名資源建立替代項目。例如，對於設定為 my_pipeline 的管線，${resources.pipelines.my_pipeline.target} 是 my_pipeline 的目標值的替代項目。

若要判斷有效的替代項目，您可以使用 REST API 參考中記載的結構描述階層圖，或 bundle schema 命令輸出。

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

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

自訂變數

您可以在套件組合中定義簡單和複雜的自訂變數，以啟用許多案例所需的值的動態擷取。自訂變數會在 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 值，必須在執行套件組合命令時、透過環境變數，或在套件組合設定檔內的其他地方設定，如設定變數的值中所述。

若要參考套件組合設定內的自訂變數，請使用變更替代項目${var.<variable_name>}。例如，若要參考變數 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"
```
或者，提供變數的值作為 bundle、validate 或 deploy 等 run 命令的一部分，例如用於 Linux 和 macOS：
```
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 CLI 會依下列順序尋找變數 my_cluster_id 和 my_notebook_path 的值，並在找到每個相符變數的值時停止，略過該變數的任何其他位置：

在任何 --var 指定為 bundle 命令一部分的選項內。
在任何以 BUNDLE_VAR_ 開頭的環境變數集合內。
在任何 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

擷取物件識別碼值

針對 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 Asset Bundles 中的替代和變數

替代

自訂變數

取得變數的值

定義複雜變數

擷取物件識別碼值

意見反應

其他資源