将 Lakeflow 声明性管道转换为 Databricks 资产捆绑项目

2025-08-25

本文介绍如何将现有管道转换为 Databricks 资产捆绑包项目。通过捆绑包，可以在单个源控制的 YAML 文件中定义和管理 Azure Databricks 数据处理配置，该文件提供更简单的维护，并允许自动部署到目标环境。

转换过程概述

图显示了将现有管道转换为捆绑包的具体步骤

将现有管道转换为捆绑包所要执行的步骤包括：

确保您可以访问已配置好的管道，以便将其转换为捆绑包。
创建或准备文件夹（最好在源代码控制的层次结构中）以存储捆绑包。
使用 Azure Databricks CLI 从现有管道生成捆绑包的配置。
查看生成的捆绑配置，确保其完整。
将捆绑包链接到原始管道。
使用捆绑配置将管道部署到目标工作区。

要求

在开始之前，你必须具有：

在本地开发计算机上安装的 Databricks CLI。使用 Databricks 资产捆绑包需要 Databricks CLI 版本 0.218.0 或更高版本。
您将使用捆绑包管理的现有声明性管道的ID。若要了解如何获取此 ID，请参阅使用 UI获取现有管道定义。
运行现有管道的 Azure Databricks 工作区的授权。若要为 Azure Databricks CLI 调用配置身份验证和授权，请参阅授权访问 Azure Databricks 资源。

步骤 1：为捆绑项目设置文件夹

必须有权访问 Azure Databricks 中配置为 Git 文件夹的 Git 存储库。在此存储库中创建捆绑项目，该项目将应用源代码管理，并通过相应 Azure Databricks 工作区中的 Git 文件夹向其他协作者提供它。（有关 Git 文件夹的更多详细信息，请参阅什么是 Databricks Git 文件夹。

转到本地计算机上的克隆 Git 存储库的根目录。
在文件夹层次结构中的适当位置，专门为捆绑项目创建一个文件夹。例如：
```
mkdir - p ~/source/my-pipelines/ingestion/events/my-bundle
```
将当前工作目录更改为此新文件夹。例如：
```
cd ~/source/my-pipelines/ingestion/events/my-bundle
```
通过运行 databricks bundle init 并回答提示来初始化新捆绑包。完成后，项目的新主文件夹中将有一个名为 databricks.yml 的项目配置文件。从命令行部署管道需要此文件。有关此配置文件的更多详细信息，请参阅 Databricks 资产捆绑包配置。

步骤 2：生成管道配置

在克隆的 Git 存储库的文件夹树中新建的目录中，运行 Azure Databricks CLI 捆绑包生成命令，并提供您的管道 ID，如 <pipeline-id>：

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

运行 generate 此命令时，它会在捆绑包的 resources 文件夹中为管道创建捆绑配置文件，并将任何引用的项目下载到 src 该文件夹。 --profile（或-p标志）是可选项，但如果你有一个特定的 Databricks 配置文件（在你安装 Azure Databricks CLI 时于.databrickscfg文件中定义），并希望使用该文件而不是默认配置文件，请在此命令中提供它。有关 Databricks 配置文件的信息，请参阅 Azure Databricks 配置文件。

步骤 3：查看捆绑项目文件

bundle generate 命令完成后，它将创建两个新文件夹：

resources 是包含项目配置文件的项目子目录。
src 是存储源文件（如查询和笔记本）的项目文件夹。

该命令还会创建一些其他文件：

*.pipeline.yml 子目录下的 resources。此文件包含管道的特定配置和设置。
从现有管道复制的源文件，例如src 子目录下的 SQL 查询。

├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {SQl-query-retrieved-from-your-existing-pipeline}.sql # Your pipeline's declarative query

步骤 4：将捆绑包管道绑定到现有管道

必须将捆绑包中的管道定义链接或绑定到现有的管道，以便在进行更改时保持其最新状态。为此，请运行 Azure Databricks CLI 捆绑部署绑定命令：

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> 是管道的名称。此名称应与新 resources 目录中管道配置的文件名的前缀字符串值相同。例如，如果 ingestion_data_pipeline.pipeline.yml 文件夹中有一个名为 resources 的管道配置文件，则必须提供 ingestion_data_pipeline 作为管道名称。

<pipeline-ID> 是管道的 ID。它与你根据这些说明的要求复制的管道 ID 相同。

步骤 5：使用新软件包部署管道

现在，使用 Azure Databricks CLI 将管道捆绑包部署到目标工作区捆绑包部署命令：

databricks bundle deploy --target <target-name> --profile <profile-name>

--target 标志是必需的，并且必须设置为与配置的目标工作区名称匹配的字符串，例如 development 或 production。

如果此命令成功，那么现在您有了一个在外部项目中的管道配置，可以将其加载到其他工作区并运行，并能轻松地与您帐户中的其他 Azure Databricks 用户共享。

故障排除

問题	解决方案
运行时出现“`databricks.yml` 找不到”错误 `bundle generate`	目前，该 `bundle generate` 命令不会自动创建捆绑配置文件（`databricks.yml`）。必须使用 `databricks bundle init` 或手动创建文件。
现有管道设置与生成的管道 YAML 配置中的值不匹配	管道 ID 不会显示在捆绑包配置 YML 文件中。如果注意到任何其他缺失的设置，可以手动应用它们。

成功提示

始终使用版本控制。如果不使用 Databricks Git 文件夹，请将项目子目录和文件存储在 Git 或其他版本控制的存储库或文件系统中。
在将管道部署到生产环境之前，在非生产环境中（例如“开发”或“测试”环境）中测试管道。很容易意外引入错误配置。

其他资源

有关使用捆绑包定义和管理数据处理的详细信息，请参阅：

什么是 Databricks 资产捆绑包？
使用 Databricks 资产包开发 Lakeflow 声明式管道。本主题介绍如何为新管道（而不是现有管道）创建捆绑包，其中包含你提供的用于处理的源代码控制笔记本。

共用方式為