bundle 命令群組

備註

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

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

bundle Databricks CLI 內的命令群組可讓您以程式設計方式驗證、部署和執行 Azure Databricks 工作流程，例如 Azure Databricks 作業、Lakeflow 宣告式管線和 MLOps Stacks。 請參閱 什麼是 Databricks 資產套件組合？。

您可以將 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 資產包開發作業
• 使用 Databricks 資產套件組合開發 Lakeflow 宣告式管線
• MLOps Stack 的 Databricks 資產套件組合

顯示套件組合組態架構

若要顯示套件組合組態架構，請執行 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 命令相同，且都用於提高工作效率。 如需命令使用方式資訊，請參閱 命令群組。

產生套件組合組態檔

此命令 bundle generate 會產生已存在於 Databricks 工作區中的資源組態。 支援下列資源：

• 應用程式
• 儀表板
• 工作
• 管道

預設情況下，此命令會在套件組合專案的 *.yml 資料夾中生成資源的 resources 檔案，並下載在組態中參考的任何檔案，例如筆記本。

重要

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

產生應用程式設定

若要在工作區中產生現有應用程式的組態，請執行 bundle generate app，並在工作區中指定應用程式的名稱：

databricks bundle generate app --existing-app-name [app-name]

您可以從工作區 UI 的 [ 計算>應用程式 ] 索引標籤取得應用程式名稱。

例如，下列命令會在套件組合專案資料夾中產生新 hello_world.app.yml 檔案 resources ，並下載應用程式的程式代碼檔案，例如應用程式的命令組態檔 app.yaml 和主要 app.py。 根據預設，程式代碼檔案會複製到套件組合的資料夾 src 。

databricks bundle generate app --existing-app-name "hello_world"

# This is the contents of the resulting /resources/hello-world.app.yml file.
resources:
  apps:
    hello_world:
      name: hello-world
      description: A basic starter application.
      source_code_path: ../src/app

產生儀錶板設定

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

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 generate job 或 bundle generate pipeline 命令：

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:
    hello_job:
      name: 'Hello Job'
      tasks:
        - task_key: run_notebook
          email_notifications: {}
          notebook_task:
            notebook_path: ../src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

系結套件組合資源

bundle deployment bind 命令允許您將套件定義的資源連結到 Azure Databricks 工作區中現有的資源，使其由 Databricks 資產套件管理。 如果您系結資源，則工作區中現有的 Azure Databricks 資源會根據下一個 bundle deploy之後所系結的套件組合中所定義的組態來更新。

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

綁定不會重新建立資料。 例如，如果目錄中具有數據的管線已套用系結，您可以部署至該管線，而不會遺失現有的數據。 此外，您不需要重新計算具體化檢視，例如，這樣管線就不必重新執行。

bind 命令應該搭配 --target 標誌使用。 例如，使用 databricks bundle deployment bind --target prod my_pipeline 7668611149d5709ac9-2906-1229-9956-586a9zed8929 將您的生產部署綁定到生產管線

提示

在執行系結之前，請先確認工作區中的資源。

支援以下資源的綁定：

• 應用程式
• 叢集
• 儀表板
• 工作
• 模型服務端點
• 管道
• 質量監控
• 註冊模型
• 圖式
• 音量

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

databricks bundle deployment bind hello_job 6565621249

解綁套件資源

如果您要移除套件組合中資源與其工作區中遠端對應項目之間的連結，請使用 bundle deployment unbind：

databricks bundle deployment unbind [resource-key]

例如，若要解除 hello_job 系結資源：

databricks bundle deployment unbind hello_job

輸出套件組合摘要

命令 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 run （雙連字元），以使用套件組合設定的身份驗證憑證來執行腳本。 例如，下列命令會輸出目前使用者目前的工作目錄：

databricks bundle run -- python3 -c 'import os; print(os.getcwd())'

套件組合驗證資訊會使用環境變數傳遞至子進程。 請參閱 Databricks 用戶端整合驗證。

在工作區中開啟資源

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

databricks bundle open [resource-key]

例如，以下命令會啟動瀏覽器並導航至在 Databricks 工作區中已配置的 bundle 中的 baby_gender_by_county 儀表板。

databricks bundle open baby_gender_by_county

摧毀套件

警告

刪除套件會永久刪除先前部署的作業、管線和工件。 此動作無法復原。

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

databricks bundle destroy

備註

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

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