bundle 命令群組

Note

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

Databricks CLI 的使用受限於 Databricks 授權 和 Databricks 隱私權聲明，包括任何使用數據條款。

bundle Databricks CLI 內的命令群組包含用來管理 Databricks 資產套件組合的命令。 Databricks 資產套件組合可讓您將專案表示為程式碼，並以程式設計方式驗證、部署和執行 Azure Databricks 工作流程，例如 Azure Databricks 作業、 Lakeflow Spark 宣告式管線和 MLOps 堆疊。 請參閱 什麼是 Databricks 資產套件組合？。

Note

從捆綁包資料夾內執行時，捆綁命令會使用 中的 databricks.yml 設定進行身份驗證。 如果您想要從套件資料夾內執行具有不同驗證的套件命令，請使用 （或 ） 旗標指定--profile-p，且不要指定 --target。

或者，從捆綁包資料夾外部運行不需要與捆綁包相同身份驗證的命令。

databricks 套件組合部署

將套件組合部署至遠端工作區。

databricks bundle deploy [flags]

套件組合目標和身分識別

若要將套件組合部署至特定目標，請將 -t（或 --target）選項與目標名稱一起設定，該名稱需在套件組合組態檔中宣告。 如果未指定任何命令選項，則使用套件組合設定檔內宣告的預設目標。 舉例來說，對於一個聲明名稱為dev的目標：

databricks bundle deploy -t dev

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

此外，套件部署會根據識別碼追蹤在目標工作區中建立的資源，並將其狀態儲存在工作區檔案系統中。 資源名稱不會用來關聯資源包部署與資源實例，因此：

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

選項

--auto-approve

    略過部署可能需要的互動式核准。

-c, --cluster-id string

    使用指定的叢集標識碼覆寫部署中的叢集。

--fail-on-active-runs

    如果部署中有執行中的作業或管線，則失敗。

--force

    強制覆寫 Git 分支驗證。

--force-lock

    強制取得部署鎖定。

全域旗標

範例

下列範例會使用特定叢集標識符來部署套件組合：

databricks bundle deploy --cluster-id 0123-456789-abcdef

databricks 套件組合部署

部署相關的命令。

databricks bundle deployment [command]

可用的命令

• bind - 將套件組合定義的資源系結至遠端工作區中的現有資源。
• migrate - 將套件遷移以使用 直接部署引擎。
• unbind - 將套件組合定義的資源與其遠端資源解除系結。

databricks 套件組合部署系結

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

databricks bundle deployment bind KEY RESOURCE_ID [flags]

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

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

Tip

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

支援以下資源的綁定：

• app
• cluster
• dashboard
• job
• model_serving_endpoint
• pipeline
• quality_monitor
• registered_model
• schema
• volume

對於指令支援的 bundle generate 資源，請在產生後使用選項 --bind 自動繫結資源。

論點

KEY

    要綁定的資源鍵

RESOURCE_ID

    要系結至之現有資源的標識碼

選項

--auto-approve

    自動核准系結，而不是提示

--force-lock

    強制獲取部署鎖

全域旗標

範例

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

databricks bundle deployment bind hello_job 6565621249

Databricks 套件部署遷移

Important

此功能為 實驗性。

將套件從使用 Terraform 部署引擎遷移到直接部署引擎。 請參見 遷移至直接部署引擎。 要完成遷移，你必須先部署該套件。

你可以透過執行 databricks bundle plan來驗證遷移是否成功。 請參考 Databricks 的套件計畫。

databricks bundle deployment migrate [flags]

論點

None

選項

全域旗標

範例

以下範例將現有套件遷移至直接 部署引擎：

databricks bundle deployment migrate

databricks 套件組合部署解除系結

拿掉套件組合中資源與其工作區中遠端對應專案之間的連結。

databricks bundle deployment unbind KEY [flags]

論點

KEY

    解開束縛的資源關鍵

選項

--force-lock

    強制取得部署鎖定。

全域旗標

範例

下列範例會解除系結 hello_job 資源：

databricks bundle deployment unbind hello_job

databricks 套件組合終結

Warning

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

刪除先前部署的作業、管線、其他資源和成品。

databricks bundle destroy [flags]

Note

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

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

選項

--auto-approve

    略過刪除資源和檔案的互動式核准

--force-lock

    強制取得部署鎖定。

全域旗標

範例

下列命令會刪除套件組合組態檔中定義的所有先前部署的資源和成品：

databricks bundle destroy

databricks 套件組合產生

為 Databricks 工作區中已經存在的資源產生套件組合組態。 支援下列資源： 應用程式、 儀錶板、 作業、 管線。

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

Important

命令 bundle generate 為方便自動產生資源組態而提供。 不過，如果您的套件組合包含資源設定，而且您部署它，Azure Databricks 會建立新的資源，而不是更新現有的資源。 若要改為更新現有資源，您必須在部署之前使用 --bind 旗標 bundle generate 或執行 bundle deployment bind。 請參閱 databricks 套件組合部署系結。

databricks bundle generate [command]

可用的命令

• app - 產生 Databricks 應用程式的套件組合組態。
• dashboard - 產生儀錶板的組態。
• job - 產生作業的套件組合組態。
• pipeline - 產生管線的套件組合組態。

選項

--key string

    要用於所產生組態的資源密鑰

全域旗標

databricks 套件組合產生應用程式

為工作區中現有的 Databricks 應用程式產生套件組合組態。

databricks bundle generate app [flags]

選項

--bind

    自動將產生的資源與工作區中現有的資源綁定。

-d, --config-dir string

    儲存輸出套件組合元件的目錄路徑（預設的「資源」）

--existing-app-name string

    要為其產生組態的應用程式名稱

-f, --force

    強制覆寫輸出目錄中的現有檔案

-s, --source-dir string

    將儲存應用程式檔案的目錄路徑（預設為“src/app”）

全域旗標

範例

下列範例會為名為 my-app的現有應用程式產生組態。 您可以從工作區 UI 的 [ 計算>應用程式 ] 索引標籤取得應用程式名稱。

databricks bundle generate app --existing-app-name my-app

下列命令會在套件組合專案資料夾中產生新的 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

databricks 套件組合產生儀錶板

為工作區中的現有儀錶板產生組態。

databricks bundle generate dashboard [flags]

Tip

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

選項

--bind

    自動將產生的資源與工作區中現有的資源綁定。

-s, --dashboard-dir string

    要寫入儀表板表示法的目錄（預設 “src”）

--existing-id string

    要為其產生組態的儀錶板標識碼

--existing-path string

    要為其產生設定之儀錶板的工作區路徑

-f, --force

    強制覆寫輸出目錄中的現有檔案

--resource string

    要監看變更的儀錶板資源索引鍵

-d, --resource-dir string

    要寫入組態的目錄（預設的「資源」）

--watch

    監看儀錶板的變更並更新設定

全域旗標

範例

下列範例會由現有的儀錶板標識碼產生組態：

databricks bundle generate dashboard --existing-id abc123

您也可以依工作區路徑產生現有儀錶板的設定。 從工作區 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

databricks 套件組合產生作業

產生作業的套件組合組態。

Note

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

databricks bundle generate job [flags]

選項

--bind

    自動將產生的資源與工作區中現有的資源綁定。

-d, --config-dir string

    儲存輸出組態的 Dir 路徑 （預設“resources”）

--existing-job-id int

    要為其產生組態之作業的作業標識碼

-f, --force

    強制覆寫輸出目錄中的現有檔案

-s, --source-dir string

    將儲存所下載檔案的 Dir 路徑（預設為 “src”）

全域旗標

範例

下列範例會在包含下列 YAML 的套件組合專案資料夾中產生新 hello_job.yml 檔案 resources ，並將 下載 simple_notebook.py 至 src 項目資料夾。 它也會將產生的資源與工作區中的現有工作繫結。

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

# 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

databricks 套件組合產生管線

產生管線的套件組合組態。

databricks bundle generate pipeline [flags]

選項

--bind

    自動將產生的資源與工作區中現有的資源綁定。

-d, --config-dir string

    儲存輸出組態的 Dir 路徑 （預設“resources”）

--existing-pipeline-id string

    要為其產生組態的管線標識碼

-f, --force

    強制覆寫輸出目錄中的現有檔案

-s, --source-dir string

    將儲存所下載檔案的 Dir 路徑（預設為 “src”）

全域旗標

範例

下列範例會產生現有管線的組態：

databricks bundle generate pipeline --existing-pipeline-id abc-123-def

Databricks 套件初始化

使用套件組合範本初始化新的套件組合。 範本可以設定為提示使用者輸入值。 請參閱 Databricks Asset Bundles 專案範本。

databricks bundle init [TEMPLATE_PATH] [flags]

論點

TEMPLATE_PATH

    初始化樣本 （選擇性）

選項

--branch string

    要用於範本初始化的 Git 分支

--config-file string

    JSON 檔案，其中包含範本初始化所需的輸入參數索引鍵值組。

--output-dir string

    要寫入初始化範本的目錄。

--tag string

    要用於範本初始化的 Git 標籤

--template-dir string

    包含範本的 Git 存放庫內的目錄路徑。

全域旗標

範例

下列範例會提示您輸入要從中選擇的預設套件組合範本清單：

databricks bundle init

下列範例會使用預設 Python 樣本初始化套件組合：

databricks bundle init default-python

若要使用自定義 Databricks Asset Bundle 範本建立 Databricks 資產組合，請指定自定義範本路徑：

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

下列範例會從 Git 存放庫初始化套件組合：

databricks bundle init https://github.com/my/repository

下列範例會使用特定分支初始化：

databricks bundle init --branch main

databricks 套件組合開啟

流覽至工作區中的套件組合資源，並指定要開啟的資源。 如果未指定資源索引鍵，此命令會輸出套件組合的資源清單，以便從中選擇。

databricks bundle open [flags]

選項

--force-pull

    略過本機快取並從遠端工作區載入狀態

全域旗標

範例

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

databricks bundle open baby_gender_by_county

Databricks 套件組合方案

顯示目前軟體組態的部署計劃。

此命令會建置服務包，並顯示將在將要部署的資源上執行的動作，而不進行任何變更。 這可讓您在執行 bundle deploy之前預覽變更。

databricks bundle plan [flags]

選項

-c, --cluster-id string

    使用指定的叢集標識碼覆寫部署中的叢集。

--force

    強制覆寫 Git 分支驗證。

全域旗標

範例

下列範例會輸出建置 Python 輪盤之套件組合的部署計劃，並定義工作和管線：

databricks bundle plan

Building python_artifact...
create jobs.my_bundle_job
create pipelines.my_bundle_pipeline

databricks 套件組合執行

執行作業、管線或腳本。 如果您未指定資源，命令會顯示可供選擇的已定義作業、管線和腳本。 或者，指定套件組合組態檔內宣告的作業或管線密鑰或腳本名稱。

databricks bundle run [flags] [KEY]

驗證管線

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

databricks bundle run --validate-only my_pipeline

傳遞任務參數

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

databricks bundle run --params message=HelloWorld hello_job

Note

如下列範例所示，您可以使用作業工作選項將參數傳遞至作業工作，但 --params 此選項是傳遞作業參數的建議方法。 如果為未定義作業參數的作業指定作業參數，或為已定義作業參數的工作指定工作參數，就會發生錯誤。

您也可以指定關鍵詞或位置自變數。 如果指定的作業使用作業參數，或作業具有具有參數的筆記本工作，則旗標名稱會對應至參數名稱：

databricks bundle run hello_job -- --key1 value1 --key2 value2

或者，如果指定的作業不使用作業參數，且作業具有 Python 檔案工作或 Python 轉輪工作：

databricks bundle run my_job -- value1 value2 value3

如需具有參數的範例工作定義，請參閱 具有參數的工作。

執行腳本

若要使用套件組合設定的驗證認證來執行整合測試之類的腳本，您可以內嵌執行腳本，或執行套件組合組態中定義的腳本。 腳本會使用套件組合中設定的相同驗證內容來執行。

• 在--後面附加雙連字元（bundle run），以內嵌執行腳本。 例如，下列命令會輸出目前使用者目前的工作目錄：

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

• 或者，在套件組合組態的 scripts 對應中定義腳本，然後使用 bundle run 來執行腳本：

  scripts:
    my_script:
      content: python3 -c 'import os; print(os.getcwd())'
  

  databricks bundle run my_script
  

  如需設定的詳細資訊 scripts ，請參閱 腳本 和 腳本。

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

論點

KEY

    要執行之資源的唯一識別碼（選擇性）

選項

--no-wait

    請勿等候執行完成。

--restart

    如果已執行，請重新啟動執行。

全域旗標

作業旗標

下列旗標是作業層級參數旗標。 請參閱 設定工作參數。

--params stringToString

    工作參數的逗號分隔 k=v 群組 （預設值 []）

作業工作旗標

下列旗標是工作層級參數旗標。 請參閱設定任務參數。 Databricks 建議在工作層級參數上使用作業層級參數 （--params）。

--dbt-commands strings

    要針對具有 DBT 工作的作業執行的命令清單。

--jar-params strings

    具有Spark JAR工作之作業的參數清單。

--notebook-params stringToString

    從索引鍵對應至具有筆記本工作之作業的值。 （預設值 []）

--pipeline-params stringToString

    從索引鍵對應至具有管線工作的作業值。 （預設值 []）

--python-named-params stringToString

    從索引鍵對應至具有 Python 滾輪工作的作業值。 （預設值 []）

--python-params strings

    具有 Python 工作之作業的參數清單。

--spark-submit-params strings

    具有Spark提交工作的作業參數清單。

--sql-params stringToString

    從索引鍵對應至具有 SQL 工作的作業值。 （預設值 []）

管線旗標

下列旗標是管線旗標。

--full-refresh strings

    要重設和重新計算的數據表清單。

--full-refresh-all

    執行完整的圖形重設並重新計算。

--refresh strings

    要更新的數據表清單。

--refresh-all

    執行完整的圖形更新。

--validate-only

    執行更新以驗證圖形正確性。

範例

下列範例會在預設目標中執行作業 hello_job ：

databricks bundle run hello_job

下列範例會在以 名稱hello_job宣告的目標內容中執行作業dev：

databricks bundle run -t dev hello_job

下列範例會取消並重新啟動現有的作業執行：

databricks bundle run --restart hello_job

下列範例會執行具有完整重新整理的管線：

databricks bundle run my_pipeline --full-refresh-all

下列範例會在套件組合內容中執行命令：

databricks bundle run -- echo "hello, world"

databricks 套件組合架構

顯示套件組合元件的 JSON 架構。

databricks bundle schema [flags]

選項

全域旗標

範例

下列範例會輸出套件組合元件的 JSON 架構：

databricks bundle schema

若要將套件組合組態架構輸出為 JSON 檔案，請執行 bundle schema 命令，並將輸出重新導向至 JSON 檔案。 例如，您可以在目前目錄內產生名為 bundle_config_schema.json 的檔案：

databricks bundle schema > bundle_config_schema.json

databricks 套件組合摘要

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

databricks bundle summary [flags]

Tip

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

選項

--force-pull

    略過本機快取並從遠端工作區載入狀態

全域旗標

範例

下列範例會輸出套件組合已部署資源的摘要：

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

databricks 套件組合同步處理

在本機文件系統目錄中執行套件組合檔案變更的單向同步處理，到遠端 Azure Databricks 工作區內的目錄。

Note

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

databricks bundle sync [flags]

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

選項

--dry-run

    模擬同步執行而不進行實際變更

--full

    執行完整同步處理 （預設值為累加式）

--interval duration

    檔案系統輪詢間隔 （針對 --watch） （預設 1 秒）

--output type

    輸出格式的類型

--watch

    監看本機文件系統是否有變更

全域旗標

範例

下列範例會執行執行執行同步處理：

databricks bundle sync --dry-run

下列範例會自動監看變更和同步處理：

databricks bundle sync --watch

下列範例會執行完整同步處理：

databricks bundle sync --full

databricks 套件組合驗證

驗證套件組合組態檔語法正確。

databricks bundle validate [flags]

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

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!

Note

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

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

選項

全域旗標

範例

下列範例會驗證套件組合組態：

databricks bundle validate

全域旗標

--debug

  是否要啟用偵錯記錄。

-h 或 --help

    顯示 Databricks CLI、相關命令群組或相關命令的幫助說明。

--log-file 字串

    字串，表示要寫入輸出記錄檔的檔案。 若未指定此旗標，則預設值是將輸出記錄寫入 stderr。

--log-format 格式

    記錄格式類型，text 或 json。 預設值是 text。

--log-level 字串

    表示日誌格式層級的字串。 若未指定，則日誌的格式層級功能將被停用。

-o, --output 類型

    指令輸出類型，text 或 json。 預設值是 text。

-p, --profile 字串

    用於執行命令的~/.databrickscfg檔案中的配置檔名稱。 如果未指定此旗標，則如果存在，則會使用名為 DEFAULT 的配置檔。

--progress-format 格式

    顯示進度記錄的格式：default、、appendinplace、 或json

-t, --target 字串

    如果適用，要使用的套件組合目標

--var strings

    設定套件組合組態中定義的變數值。例： --var="foo=bar"