共用方式為

使用 Databricks 資產套件組合開發 Lakeflow Spark 宣告式管線

Databricks 資產套件組合 （也稱為 套件組合） 可讓您以程式設計方式驗證、部署和執行 Azure Databricks 資源，例如 Lakeflow Spark 宣告式管線。 請參閱 什麼是 Databricks 資產套件組合？。

本頁說明如何建立套件組合，以程式設計方式管理管線。 請參閱 Lakeflow Spark 宣告式管線。 該套件是使用 Databricks CLI pipelines init 指令建立的，該指令定義了 ETL 管線及執行工作。 然後，在 Azure Databricks 工作空間內驗證和部署管線，並以無伺服器計算的方式運行已部署的管線。

提示

如果您有使用想要移至套件組合的 Azure Databricks 使用者介面或 API 建立的現有管線，則必須在套件組合的組態檔中定義它們。 Databricks 建議您先使用下列步驟建立套件組合，然後將設定和其他來源新增至套件組合。 請參閱 使用UI擷取現有的管線定義。

需求

  • Databricks CLI 版本 0.283.0 或更高。 若要檢查您已安裝的 Databricks CLI 版本，請執行命令 databricks -v。 若要安裝 Databricks CLI，請參閱 安裝或更新 Databricks CLI。
  • uv 是從 IDE 執行測試和安裝此專案依賴項所需的。
  • 遠端工作區必須已啟用工作區檔案。 請參閱 什麼是工作區檔案？。
  • 管線中資料表的現有目錄。 請參閱 建立目錄。

(選用)安裝 Python 模組以支援本機管線開發

Databricks 提供 Python 模組，可在您在 IDE 中撰寫程式碼時提供語法檢查、自動完成和資料類型檢查，以協助您在本機開發 Lakeflow Spark 宣告式管線程式碼。

適用於本機開發的 Python 模組可在 PyPi 上使用。 若要安裝模組，請參閱 DLT 的 Python 存根。

步驟 1：設定驗證

首先，在開發電腦上的 Databricks CLI 與 Azure Databricks 工作區之間設定驗證。 此頁面假設您希望使用 OAuth 使用者到機器 (U2M) 驗證，以及名為 DEFAULT 的對應 Azure Databricks 組態設定檔進行驗證。

注意

U2M 驗證適用於即時試用這些步驟。 針對完全自動化的工作流程，Databricks 建議您改用 OAuth 機器對機器 (M2M) 驗證。 請參閱 使用 OAuth 授權服務主體存取 Azure Databricks 中的 M2M 驗證設定指示。

  1. 針對每個目標工作區執行下列命令，使用 Databricks CLI 在本機起始 OAuth 令牌管理。

    在下列命令中，將 取代 <workspace-url> 為您的 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。

    databricks auth login --host <workspace-url>

  2. Databricks CLI 會提示您將輸入的資訊儲存為 Azure Databricks 設定檔。 按 Enter 以接受建議的設定檔名稱，或輸入新或現有設定檔的名稱。 任何具有相同名稱的現有設定檔，會以您輸入的資訊覆寫。 您可使用設定檔，在多個工作區之間快速切換身份驗證。

    若要取得任何現有設定檔的清單，請在個別的終端機或命令提示字元中，使用 Databricks CLI 執行命令 databricks auth profiles。 若要檢視特定設定檔的現有設定，請執行 命令 databricks auth env --profile <profile-name>。

  3. 在網頁瀏覽器中，完成畫面上的指示，登入 Azure Databricks 工作區。

  4. 若要檢視配置檔目前的 OAuth 令牌值和令牌即將到期的時間戳，請執行下列其中一個命令：

    • databricks auth token --host <workspace-url>
    • databricks auth token -p <profile-name>
    • databricks auth token --host <workspace-url> -p <profile-name>

    如果您有多個具有相同 --host 值的設定檔，您可能需要一起指定 --host 和 -p 選項，以協助 Databricks CLI 尋找正確的相符 OAuth 權杖資訊。

步驟 2：建立套件組合

初始化一個具有管線的套件

  1. 使用終端機或命令提示字元，切換至本機開發計算機上的目錄，其中包含範本產生的套件組合。

  2. 使用 Databricks CLI 執行 pipelines init 命令：

    databricks pipelines init

  3. 針對 Unique name for this project，保留 my_pipeline_project 的預設值，或輸入不同的值，然後按 Enter。 這會決定此套件組合的根目錄名稱。 此根目錄是在您目前的工作目錄中建立的。

  4. 針對 Initial catalog，輸入現有 Unity 目錄目錄的名稱。

  5. 針對Use a personal schema for each user working on this project?，選取yes。

  6. 針對Initial language for this project，選取python。

步驟 3：探索套件組合

若要檢視範本產生的檔案，請切換至新建立套件組合的根目錄。 預設建立的結構如下：

my_pipeline_project
├── databricks.yml
├── pyproject.toml
├── README.md
├── resources
│   ├── my_pipeline_project_etl.pipeline.yml
│   └── sample_job.job.yml
└── src
    └── my_pipeline_project_etl
        ├── explorations
        │   └── sample_exploration.ipynb
        ├── README.md
        └── transformations
            ├── sample_trips_my_pipeline_project.py
            └── sample_zones_my_pipeline_project.py

特別值得注意的檔案如下所示：

  • databricks.yml：此檔案指定軟體組的程式設計名稱、包含軟體組檔案的參照、定義型錄和結構描述變數，以及指定目標工作區的設定。

  • resources/sample_job.job.yml 和 resources/<project-name>_etl_pipeline.yml：這些檔案會定義包含管線重新整理工作的作業，以及管線的設定。 如需管線設定的相關資訊，請參閱 管線。

  • src/：此資料夾包含範例管線的來源檔案、探索和轉換。

    提示

    如果你新增測試，請用 pytest 來在本地執行：

    uv run pytest

  • README.md：此檔案包含有關開始使用和使用此套件範本的其他資訊。

步驟 4：驗證套件組合組態

現在檢查捆綁包配置是否有效。

  1. 從根目錄，使用 Databricks CLI 來執行命令 bundle validate ：

    databricks bundle validate

  2. 如果傳回套件組合設定的摘要，則驗證成功。 如果傳回任何錯誤，請修正錯誤，然後重複此步驟。

步驟 5：將管線部署至遠端工作空間

接下來，將套件組合部署至遠端 Azure Databricks 工作區，並驗證工作區中的管線。

  1. 從封裝根目錄，使用 Databricks CLI 指令 deploy：

    databricks bundle deploy --target dev

    或：

    databricks pipelines deploy --target dev

    注意

    預設範本包含每天執行管線的作業，但對於目標部署模式 dev 則會暫停。 請參閱 Databricks 資產組合部署模式。

  2. 確認套件組合已部署：

    1. 在 Azure Databricks 工作區的側邊欄中，按一下 [工作區]。
    2. 按一下 「使用者 ><your-username>>.bundle 」資料夾，然後找到您的套件組合專案。

  3. 檢查您的管線是否已建立：

    1. 在 Azure Databricks 工作區的側邊欄中，點擊 作業和管線。
    2. 或者，選取 [ 管線 ] 和 [我所擁有的 篩選]。
    3. 按一下 [dev <your-username>] <project-name>_etl。

如果您在此步驟後對套件組合進行任何變更，您應該重複步驟 4-5，以檢查套件組合設定是否仍然有效，然後重新部署專案。

步驟 6：執行已部署的管線

現在，從命令列介面觸發您工作區中的管線執行。

  1. 從根目錄使用 Databricks CLI pipelines run 指令。 如果專案中只有一條管線，你不需要指定管線名稱。

    databricks pipelines run my_pipeline_project_etl --target dev

  2. 複製終端機中顯示的 Update URL 的值，並將此值貼到您的網頁瀏覽器中，以開啟您的 Azure Databricks 工作區。

  3. 在您的 Azure Databricks 工作區中，當管線成功執行完成後，請按一下實體化檢視以查看每個檢視的詳細資料。

如果您在此步驟後對套件組合進行任何變更，您應該重複步驟 4-6，以檢查套件組合設定是否仍然有效，重新部署專案並執行重新部署的專案。

步驟 7：輸出歷史與事件日誌

由pipelines history和pipelines logs命令提供的資訊有助於診斷故障。

要取得管線過去的運行記錄：

databricks pipelines history my_pipeline_project_etl

Updates Summary for pipeline my_pipeline_project_etl:
Update ID: a62293ec-8a63-43b7-8629-b218d56dac7c
   State: COMPLETED
   Cause: API_CALL
   Creation Time: 2026-01-29T23:16:14Z
   Full Refresh: false
   Validate Only: false

要輸出（以 JSON 格式）管線最近更新的事件：

databricks pipelines logs my_pipeline_project_etl

請使用 jq 來篩選結果。 請參見 Filter JSON 輸出。jq

步驟 8：清除

在此步驟中，您會從工作區中刪除已部署的服務包和管線。

  1. 從根目錄，使用 Databricks CLI 來執行命令 pipelines destroy ：

    databricks pipelines destroy --target dev

  2. 當系統提示您永久終結資源、管線，以及管線所管理的表格和檢視時，請輸入 y 並按 Enter。

  3. 如果您也想從開發機器中刪除套件組合，您現在可以刪除本機專案目錄。

  • Last updated on