bundle 命令群組

bundle Databricks CLI 中的指令群組包含管理宣告式自動化套件的指令。 宣告式自動化套件讓你能以程式碼形式表達專案，並程式化驗證、部署及執行 Azure Databricks 工作流程，例如 Azure Databricks 工作、Lakeflow pipelines 和 MLOps Stacks。 請參閱「什麼是宣告式自動化套件？」。

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

    強制取得部署鎖定。 此選項會停用防止同時部署互動的機制。 只有在先前部署當機或中斷導致鎖檔案過時，才應該使用。

--plan

    指定 JSON 計畫檔案的路徑以應用，取代規劃（僅適用於直接引擎）。 計劃檔案可以使用databricks bundle plan -o json建立。

--select strings

    僅部署指定的資源（例如， my_job 或 jobs.my_job）。 可以重複或逗號分隔。

全域旗標

範例

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

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

以下範例僅部署指定的資源。 使用 --select 帶有資源鍵的旗標，並依資源類型加限定，並重複該旗標，或使用逗號分隔的清單來部署多個資源：

databricks bundle deploy --select my_job
databricks bundle deploy --select jobs.my_job --select pipelines.my_pipeline
databricks bundle deploy --select my_job,my_pipeline

databricks 套件組合部署

部署相關的命令。

databricks bundle deployment [command]

可用的命令

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

databricks 套件組合部署系結

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

databricks bundle deployment bind KEY RESOURCE_ID [flags]

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

bind 命令應該搭配 --target 標誌使用。 識別碼格式依資源類型而異——詳見下方 的參數 部分。

Bind 支援所有宣告式自動化套件的資源類型。 請注意，部分資源僅能透過直接引擎取得，詳見 宣告式自動化套件資源。

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

論點

KEY

    要綁定的資源鍵

RESOURCE_ID

    綁定現有資源的識別碼。 格式依資源類型而異，因為 bind 指令會使用 GET REST API 端點來發現資源。 對於以數字或 UUID 風格識別的資源（如工作與管線），傳送該 ID。 對於以全名識別的 Unity 目錄資源（如結構和卷），則改為傳遞全名路徑。 例如：

• 工作：數字識別碼，例如 6565621249
• 管線：UUID，例如 7688611149d5709ac9-2900-1229-9996-586a9zez8929
• SCHEMA：全名形式， catalog.schema 例如 my_catalog.my_schema
• 卷：全名形式， catalog.schema.volume 例如 my_catalog.my_schema.my_volume
• registered_model：全名形式catalog.schema.model
• quality_monitor：完整表格名稱形式catalog.schema.table

選項

--auto-approve

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

--force-lock

    強制取得部署鎖定。 此選項會停用防止同時部署互動的機制。 只有在先前部署當機或中斷導致鎖檔案過時，才應該使用。

全域旗標

範例

以下指令會將 bundle 資源 hello_job 綁定到工作空間中已有的作業，並使用該工作單位的數值 ID。 命令會輸出差異，並可讓您拒絕資源系結，但如果已確認，套件組合中作業定義的任何更新會在下次部署套件組合時套用至對應的遠端作業。

databricks bundle deployment bind hello_job 6565621249

對於 Unity 目錄資源，如結構和磁碟區，請傳遞完整名稱路徑而非 ID。 以下指令將一個 bundle-defined schema 綁定到工作空間中已存在的 schema：

databricks bundle deployment bind my_bundle_schema_ref my_existing_catalog.my_existing_schema

Databricks 套件部署遷移

將套件從使用 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 套件組合終結

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

databricks bundle destroy [flags]

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

你可以利用這個 lifecycle 設定來防止特定資源被摧毀。 請參閱 生命週期。

選項

--auto-approve

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

--force-lock

    強制取得部署鎖定。 此選項會停用防止同時部署互動的機制。 只有在先前部署當機或中斷導致鎖檔案過時，才應該使用。

全域旗標

範例

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

databricks bundle destroy

databricks 套件組合產生

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

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

databricks bundle generate [command]

可用的命令

• app - 產生 Databricks 應用程式的套件組合組態。
• dashboard - 產生儀錶板的組態。
• genie-space - 為 Genie 代理產生配置。
• 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]

選項

--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 套件生成 Genie-Space

在工作區中為現有的 Genie 代理產生設定。

此指令會產生以下內容：

• 一個包含設定及 Genie 代理定義參考的 Genie agent 配置 YAML 檔案
• 一個包含序列化空間內容的 Genie 代理定義*.geniespace.json檔案

databricks bundle generate genie-space [flags]

選項

--existing-id string

    Genie agent 的 ID 以產生 的配置

-f, --force

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

-s, --genie-space-dir string

    用來寫入 Genie 代理表示的目錄（預設「src」）

--resource string

    Genie 代理的資源金鑰，用來觀察變化

-d, --resource-dir string

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

--watch

    注意 Genie 代理程式的變動並更新設定

全域旗標

範例

以下範例是利用現有的 Genie 代理 ID 產生配置：

databricks bundle generate genie-space --existing-id abc123

以下範例讓 Genie 代理的 UI 修改與套件保持同步：

databricks bundle generate genie-space --resource my_genie_space --watch --force

databricks 套件組合產生作業

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

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 套件組合產生管線

為現有管線產生 bundle 設定。

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 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 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 分支驗證。

--select strings

    只規劃指定的資源（例如， my_job 或 jobs.my_job）。 可以重複或逗號分隔。

全域旗標

範例

下列範例會輸出建置 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

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

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]

選項

--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 工作區內的目錄。

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!

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

選項

全域旗標

範例

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

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"