bundle 命令群組

注意

此資訊適用於 Databricks CLI 0.205 版和更新版本。 Databricks CLI 處於 公開預覽狀態。

Databricks CLI 使用受限於 Databricks 授權 和 Databricks 隱私權注意事項，包括任何使用量數據布建。

bundle 內的 命令群組可讓您以程式設計方式驗證、部署和執行 Azure Databricks 工作流程，例如 Azure Databricks 作業、差異即時資料表管線和 MLOps 堆疊。 請參閱什麼是 Databricks Asset Bundles？。

您可以將 bundle 命令附加至 databricks bundle 來執行這些命令。 若要顯示 bundle 命令的說明，請執行 databricks bundle -h。

從專案範本建立專案

若要使用適用於 Python 的預設 Databricks Asset Bundle 範本建立 Databricks 資產套件組合，請執行 bundle init 下列命令，然後回答螢幕上的提示：

databricks bundle init

若要使用自定義 Databricks Asset Bundle 範本建立 Databricks Asset Bundle，請執行 bundle init 命令，如下所示：

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

另請參閱：

• Databricks Asset Bundle 專案範本
• 使用 Databricks Asset Bundles 在 Azure Databricks 上開發工作
• 使用 Databricks Asset Bundles 開發差異即時資料表管線
• MLOps Stack 的 Databricks Asset Bundle

顯示套件組合組態結構描述

若要顯示套件組合組態架構，請執行 bundle schema 命令，如下所示：

databricks bundle schema

若要將 Databricks Asset Bundle 組態結構描述輸出為 JSON 檔案，請執行 bundle schema 命令並將輸出重新導向至 JSON 檔案。 例如，您可以在目前目錄中產生名為 bundle_config_schema.json 的檔案，如下所示：

databricks bundle schema > bundle_config_schema.json

驗證套件組合

若要驗證套件組合設定檔在語法上是否正確，請從套件組合專案根目錄執行 bundle validate 命令，如下所示：

databricks bundle validate

根據預設，此命令會傳回套件組合身分識別的摘要：

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

注意

如果在套件組合設定檔中定義的資源屬性在對應物件的結構描述中找不到，則 bundle validate 命令會輸出警告。

如果您只想要輸出套件組合身分識別和資源摘要，請使用 套件組合摘要。

將套件組合的樹狀目錄同步至工作區

使用 bundle sync 命令，將本機檔案系統目錄內套件組合的檔案變更單向同步至遠端 Azure Databricks 工作區內的目錄。

注意

bundle sync 命令無法同步處理遠端 Azure Databricks 工作區內目錄的檔案變更，回到本機文件系統內的目錄。

databricks bundle sync 命令的運作方式與 databricks sync 命令相同，且都用於提高工作效率。 如需命令使用方式資訊，請參閱 sync 命令群組。

產生套件組合設定檔

您可以使用 bundle generate 命令，為 Databricks 工作區中已存在的作業、 管線或 儀錶板 產生資源組態。 此命令會在 *.yml 套件組合專案的資料夾中產生作業、管線或儀錶板 resources 的檔案，並下載組態中所參考的任何檔案，例如筆記本。

產生作業或管線設定

重要

命令 bundle generate 為方便自動產生資源組態而提供。 不過，當此作業或管線組態包含在套件組合中並部署時，它會建立新的資源，而且除非 bundle deployment bind 已先使用，否則不會更新現有的資源。 請參閱 系結套件組合資源。

若要產生作業或管線的組態，請執行 bundle generate 命令，如下所示：

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

注意

目前，此命令僅支援具有筆記本工作的作業。

例如，下列命令在包含下方 YAML 的 hello_job.yml 套件組合專案檔案夾中產生一個新的 resources 檔案，並將 simple_notebook.py 下載至 src 專案檔案夾。

databricks bundle generate job --existing-job-id 6565621249

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    6565621249:
      name: Hello Job
      format: MULTI_TASK
      tasks:
        - task_key: run_notebook
          existing_cluster_id: 0704-xxxxxx-yyyyyyy
          notebook_task:
            notebook_path: ./src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

產生儀錶板設定

若要在工作區中產生現有儀錶板的組態，請執行 bundle generate，並指定儀錶板的標識碼或工作區路徑：

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

您可以從工作區 UI 複製儀錶板的工作區路徑。

例如，下列命令會在套件組合專案資料夾中產生包含下列 YAML 的新 baby_gender_by_county.dashboard.yml 檔案 resources ，並將檔案下載 baby_gender_by_county.lvdash.json 至 src 項目資料夾。

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: "Baby gender by county"
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

提示

若要在部署儀錶板之後更新.lvdash.json檔案，請在執行 --resource 時使用 bundle generate dashboard 選項，為現有的儀錶板資源產生該檔案。 若要持續輪詢並擷取儀錶板的更新，請使用 --force 和 --watch 選項。

繫結套件組合資源

bundle deployment bind 命令可讓您將套件組合定義的作業和管線連結至 Azure Databricks 工作區中的現有作業和管線，以便由 Databricks Asset Bundle 進行管理。 如果您繫結了某個資源，工作區中的現有 Azure Databricks 資源將基根據在下一次 bundle deploy 之後繫結的套件組合所定義的組態進行更新。

提示

在執行繫結之前，最好先在工作區中確認套件組合。

databricks bundle deployment bind [resource-key] [resource-id]

例如，下列命令會將資源 hello_job 繫結至工作區中的遠端對應項目。 此命令會輸出差異，並可讓您拒絕資源繫結，但如果確認，套件組合中對作業定義的任何更新會在下次部署套件組合時套用至對應的遠端作業。

databricks bundle deployment bind hello_job 6565621249

如果要移除套件組合中作業或管線與其工作區中遠端對應項目之間的連結，請使用 bundle deployment unbind。

databricks bundle deployment unbind [resource-key]

輸出套件組合摘要

命令 bundle summary 會輸出套件組合身分識別和資源摘要，包括資源的深層連結，讓您可以輕鬆地流覽至 Databricks 工作區中的資源。

databricks bundle summary

下列範例輸出是名為 my_pipeline_bundle 的套件組合摘要，可定義作業和管線：

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

提示

您也可以使用 bundle open 瀏覽至 Databricks 工作區中的資源。 請參閱 開啟套件組合資源。

部署套件組合

若要將套件組合部署至遠端工作區，請從套件組合專案根目錄執行 bundle deploy 命令。 如果未指定任何命令選項，則使用套件組合設定檔內宣告的預設目標。

databricks bundle deploy

若要將套件組合部署至特定目標，請設定 -t (或 --target) 選項以及套件組合設定檔內宣告的目標名稱。 例如，對於使用名稱 dev 宣告的目標：

databricks bundle deploy -t dev

套件組合可以部署至多個工作區，例如開發、預備和生產工作區。 基本上，root_path 屬性決定了套件組合的唯一身分識別，預設為 ~/.bundle/${bundle.name}/${bundle.target}。 因此，根據預設，套件組合的身分識別由部署者的身分識別、套件組合的名稱和套件組合的目標名稱組成。 如果這些屬性在不同的套件組合中都相同，則這些套件組合的部署會互相干擾。

此外，套件組合部署將追蹤透過識別碼在目標工作區中建立的資源，作為儲存在工作區檔案系統中的狀態。 資源名稱不會用於在套件組合部署與資源執行個體之間相互關聯，因此：

• 如果套件組合組態中的資源不存在於目標工作區中，則會建立此資源。
• 如果套件組合組態中的資源存在於目標工作區中，則會在工作區中更新此資源。
• 如果資源已從套件組合組態中移除，則會從目標工作區中移除該資源 (如果之前已部署)。
• 僅當您變更套件組合名稱、套件組合目標或工作區時，才能忘記資源與套件組合的關聯。 您可以執行 bundle validate 以輸出包含這些值的摘要。

執行作業或管線

若要執行特定作業或管線，請使用 bundle run 命令。 您必須指定套件組合設定檔內宣告的作業或管線的資源索引鍵。 根據預設，將使用套件組合設定檔內宣告的環境。 例如，若要在預設環境中執行作業 hello_job，請執行下列命令：

databricks bundle run hello_job

若要在以名稱 hello_job 宣告的目標內容中使用索引鍵 dev 執行作業：

databricks bundle run -t dev hello_job

如果您要進行管線驗證執行，請使用 --validate-only 選項，如下列範例所示：

databricks bundle run --validate-only my_pipeline

若要傳遞作業參數，請使用 --params 選項，後接逗號分隔的索引鍵/值組，其中索引鍵是參數名稱。 例如，下列命令會將作業 message 的名為 HelloWorld 的參數設定為 hello_job：

databricks bundle run --params message=HelloWorld hello_job

注意

您可以使用工作任務選項將參數傳遞給工作任務，但建議使用 --params 選項傳遞工作參數。 如果為未定義作業參數的作業指定了作業參數，或者為已定義作業參數的作業指定了工作參數，則會發生錯誤。

若要取消並重新啟動現有的作業執行或管線更新，請使用 --restart 選項：

databricks bundle run --restart hello_job

開啟套件組合資源

若要流覽至工作區中的套件組合資源，請從套件組合專案根目錄執行 bundle open 命令，並指定要開啟的資源。 如果未指定資源索引鍵，此命令會輸出套件組合的資源清單，以便從中選擇。

databricks bundle open [resource-key]

例如，下列命令會啟動瀏覽器，並流覽至針對套件組合設定之 Databricks 工作區中套件組合中的baby_gender_by_county儀錶板：

databricks bundle open baby_gender_by_county

終結套件組合

警告

終結套件組合會永久刪除套件組合先前部署的作業、管線和成品。 此動作無法復原。

若要刪除先前部署的作業、管線和成品，請執行 bundle destroy 命令。 下列命令會刪除套件組合設定檔中定義的所有先前部署的作業、管線和成品：

databricks bundle destroy

注意

套件組合的身分識別由套件組合名稱、套件組合目標和工作區組成。 如果您已變更其中任何一項，然後嘗試在部署之前終結套件組合，將發生錯誤。

根據預設，系統會提示您確認永久刪除先前部署的作業、管線和成品。 若要略過這些提示並執行自動永久刪除，請將 --auto-approve 選項新增至 bundle destroy 命令。