使用 Databricks 资产捆绑包开发增量实时表管道

  • 项目

Databricks 资产捆绑包简称为捆绑包，使你能够以编程方式验证、部署和运行增量实时表管道等 Azure Databricks 资源。 请参阅什么是 Databricks 资产捆绑包？。

本文介绍了如何创建捆绑包来以编程方式管理管道。 请参阅什么是增量实时表？。 该捆绑包是使用适用于 Python 的 Databricks 资产捆绑包默认捆绑包模板创建的，由一个笔记本和运行该笔记本的管道和作业定义组成。 然后在 Azure Databricks 工作区中验证、部署和运行已部署的管道。

提示

如果要移动到捆绑包的现有管道是使用 Azure Databricks 用户界面或 API 创建的，则必须在捆绑包的配置文件中进行定义。 Databricks 建议首先使用以下步骤创建捆绑包，并验证捆绑包是否正常工作。 然后可以将其他定义、笔记本和其他源添加到捆绑包。 请参阅将现有管道定义添加到捆绑包。

要求

  • Databricks CLI 版本 0.218.0 或更高版本。 若要检查安装的 Databricks CLI 版本，请运行命令 databricks -v。 要安装 Databricks CLI，请参阅《安装或更新 Databricks CLI》。
  • 远程工作区必须启用工作区文件。 请参阅什么是工作区文件？。

（可选）安装 Python 模块以支持本地管道开发

Databricks 提供了一个 Python 模块，用于在 IDE 中编写代码时提供语法检查、自动完成和数据类型检查，从而帮助进行 Delta Live Tables 管道代码的本地开发。

可在 PyPi 上找到用于本地开发的 Python 模块。 若要安装模块，请参阅 Delta Live Tables 的 Python 存根。

使用项目模板创建捆绑包

使用适用于 Python 的 Azure Databricks 默认捆绑包模板创建捆绑包。 该模板包含一个笔记本，其中定义了一个用于筛选原始数据集中数据的 Delta Live Tables 管道。 有关捆绑包模板的详细信息，请参阅 Databricks 资产捆绑包项目模板。

如果要从头开始创建捆绑包，请参阅手动创建捆绑包。

步骤 1：设置身份验证

此步骤在开发计算机上的 Databricks CLI 与 Azure Databricks 工作区之间设置身份验证。 本文假设你要使用 OAuth 用户到计算机 (U2M) 身份验证和名为 DEFAULT 的相应的 Azure Databricks 配置文件进行身份验证。

注意

U2M 身份验证适用于实时尝试这些步骤。 对于完全自动化的工作流，Databricks 建议改用 OAuth 计算机到计算机 (M2M) 身份验证。 请参阅身份验证中的 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. 在 Web 浏览器中，按照屏幕上的说明登录到 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：创建捆绑包

使用默认 Python 捆绑包项目模板来初始化捆绑包。

  1. 使用终端或命令提示符切换到本地开发计算机上的目录，其中包含模板生成的捆绑包。

  2. 使用 Databricks CLI 运行 bundle init 命令：

    databricks bundle init

  3. 对于 Template to use，请按 Enter 保留 default-python 的默认值。

  4. 对于 Unique name for this project，请保留 my_project 的默认值，或键入其他值，然后按 Enter。 这将确定此捆绑包的根目录的名称。 此根目录是在当前工作目录中创建的。

  5. 对于“Include a stub (sample) notebook”，选择“no”并按“Enter”。 这会指示 Databricks CLI 此时不添加示例笔记本，因为与此选项关联的示例笔记本中没有增量实时表代码。

  6. 对于 Include a stub (sample) DLT pipeline，请按 Enter 保留 yes 的默认值。 这会指示 Databricks CLI 添加包含增量实时表代码的示例笔记本。

  7. 对于“Include a stub (sample) Python package”，选择“no”并按“Enter”。 这会指示 Databricks CLI 不要向捆绑包添加示例 Python wheel 包文件或相关的生成说明。

步骤 3：浏览捆绑包

要查看模板生成的文件，请切换到新创建的捆绑包的根目录。 特别感兴趣的文件包括：

  • databricks.yml：此文件指定捆绑包的编程名称，包括对管道定义的引用，并指定有关目标工作区的设置。
  • resources/<project-name>_job.yml 和 resources/<project-name>_pipeline.yml：这些文件用于定义包含管道刷新任务的作业和该管道的设置。
  • src/dlt_pipeline.ipynb：此文件是运行时执行管道的笔记本。

在对管道进行自定义时，管道声明中的映射对应于 REST API 参考中的 POST /api/2.0/pipelines 中定义的“创建管道”操作的请求有效负载（以 YAML 格式表示）。

步骤 4：验证项目的捆绑包配置文件

在此步骤中，检查捆绑包配置是否有效。

  1. 在根目录中，使用 Databricks CLI 运行 bundle validate 命令，如下所示：

    databricks bundle validate

  2. 如果返回了捆绑包配置的摘要，则表示验证成功。 如果返回了任何错误，请修复错误，然后重复此步骤。

如果在此步骤之后对捆绑包进行任何更改，则应重复此步骤以检查捆绑包配置是否仍然有效。

步骤 5：将本地项目部署到远程工作区

此步骤将本地笔记本部署到远程 Azure Databricks 工作区，并在工作区中创建增量实时表管道。

  1. 在捆绑包根目录中，使用 Databricks CLI 运行 bundle deploy 命令，如下所示：

    databricks bundle deploy -t dev

  2. 检查是否已部署本地笔记本：在 Azure Databricks 工作区的边栏中，单击“工作区”。

  3. 单击进入以下文件夹：Users ><your-username>> .bundle ><project-name>> dev > files > src。 笔记本应该位于此文件夹中。

  4. 检查是否已创建管道：在 Azure Databricks 工作区的边栏中，单击“增量实时表”。

  5. 在“增量实时表”选项卡上，单击 [dev <your-username>] <project-name>_pipeline。

如果在此步骤之后对捆绑包进行了任何更改，则应重复步骤 4-5 以检查捆绑包配置是否仍然有效，然后重新部署项目。

步骤 6：运行部署的项目

在此步骤中，你将从命令行触发在工作区中运行该 Delta Live Tables 管道。

  1. 在根目录中，使用 Databricks CLI 运行 bundle run 命令，如下所示，将 <project-name> 替换为步骤 2 中项目的名称：

    databricks bundle run -t dev <project-name>_pipeline

  2. 复制终端中显示的 Update URL 值，并将该值粘贴到 Web 浏览器中以打开 Azure Databricks 工作区。

  3. 在 Azure Databricks 工作区中，管道成功完成后，单击 taxi_raw 视图和 filtered_taxis 具体化视图以查看详细信息。

如果在此步骤之后对捆绑包进行了任何更改，则应重复步骤 4-6 以检查捆绑包配置是否仍然有效，重新部署项目，然后运行重新部署的项目。

步骤 7：清理

在此步骤中，将从工作区中删除已部署的笔记本和管道。

  1. 在根目录中，使用 Databricks CLI 运行 bundle destroy 命令，如下所示：

    databricks bundle destroy -t dev

  2. 确认管道删除请求：当系统提示是否永久销毁资源时，请键入 y 并按 Enter。

  3. 确认笔记本删除请求：当系统提示是否永久销毁先前部署的文件夹及其所有文件时，请键入 y 并按 Enter。

  4. 如果还想从开发计算机中删除捆绑包，现在可以从步骤 2 中删除本地目录。

将现有管道定义添加到捆绑包

可以基于现有的增量实时表管道定义在捆绑包配置文件中定义新管道。 要获取现有管道的定义，可以使用 UI 手动检索，也可以使用 Databricks CLI 以编程方式生成。

使用 UI 获取现有管道的定义

要从 Azure Databricks 工作区 UI 获取现有管道定义的 YAML 表示形式，请执行以下操作：

  1. 在 Azure Databricks 工作区的边栏中，单击“工作流”。

  2. 在“增量实时表”选项卡上，单击管道的“名称”链接。

  3. 单击“开发”按钮旁的烤肉串图标，然后单击“查看设置 YAML”。

  4. 单击复制图标，将“管道设置 YAML”对话框中的管道定义的 YAML 复制到本地剪贴板。

  5. 添加复制到捆绑包 databricks.yml 文件的 YAML，或在捆绑包项目的 resources 文件夹中为你的管道创建一个配置文件，然后从 databricks.yml 文件引用该配置文件。 查看资源。

  6. 下载并将引用的所有 Python 文件和笔记本添加到捆绑包的项目源中。 通常，捆绑包项目位于捆绑包的 src 目录中。

    提示

    可以通过单击 Azure Databricks 笔记本用户界面中的“文件”>“导出”>“IPython Notebook”，将现有笔记本从 Azure Databricks 工作区导出为 .ipynb 格式。

    将笔记本、Python 文件和其他生成工件添加到捆绑包后，请确保管道定义正确引用它们。 例如，对于位于捆绑包的 hello.ipynb 目录中名为 src/ 的笔记本：

    resources:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      libraries:
        - notebook:
            path: ../src/hello.ipynb

使用 Databricks CLI 生成现有管道定义

要以编程方式为现有管道生成捆绑包配置，请执行以下操作：

  1. 从 UI 中管道的“管道详细信息”侧面板中检索现有管道的 ID，或者使用 Databricks CLI databricks pipelines list-pipelines 命令。

  2. 运行 bundle generate pipeline Databricks CLI 命令，设置管道 ID：

    databricks bundle generate pipeline --existing-pipeline-id 6565621249

    此命令将在捆绑包的 resources 文件夹中为管道创建一个捆绑配置文件，并将任何引用的工件下载到 src 文件夹。

    提示

    如果首先使用 bundle deployment bind 将捆绑包中的资源绑定到工作区中的资源，则在下一次 bundle deploy 之后，工作区中的资源将根据其绑定到的捆绑包中定义的配置进行更新。 有关 bundle deployment bind 的信息，请参阅绑定捆绑包资源。