通过

使用 Databricks 资产捆绑包在 Azure Databricks 上开发作业

  • 项目

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

本文介绍可在本地开发计设置上通过哪些步骤使用捆绑包以编程方式管理作业。 请参阅计划和协调工作流。

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

除了使用 Databricks CLI 运行捆绑包部署的作业外，还可在 Azure Databricks 作业 UI 中查看和运行这些作业。 请参阅查看并运行使用 Databricks 资产捆绑包创建的作业。

要求

  • Databricks CLI 版本 0.218.0 或更高版本。 若要检查安装的 Databricks CLI 版本，请运行命令 databricks -v。 要安装 Databricks CLI，请参阅《安装或更新 Databricks CLI》。

决定：通过使用模板或手动创建捆绑包

决定是要使用模板还是手动创建示例捆绑包：

使用模板创建捆绑包

在这些步骤中，你将使用适用于 Python 的 Azure Databricks 默认捆绑包模板来创建捆绑包，该模板由笔记本或 Python 代码组成，与要运行它的作业的定义配对。 然后在 Azure 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.databricks.azure.cn。

    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：创建捆绑包

捆绑包中有要部署的生成工件以及要运行的资源的设置。

  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”，选择“yes”并按“Enter”。

  6. 对于“Include a stub (sample) DLT pipeline”，选择“no”并按“Enter”。 这会指示 Databricks CLI 不要在捆绑包中定义示例 Delta Live Tables 管道。

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

步骤 3：浏览捆绑包

若要查看模板生成的文件，请切换到新创建的捆绑包的根目录，并使用首选 IDE（例如 Visual Studio Code）打开此目录。 特别感兴趣的文件包括：

  • databricks.yml：此文件指定程序包的编程名称，包括对作业定义的引用，并指定有关目标工作区的设置。
  • resources/<project-name>_job.yml：此文件指定作业的设置，包括默认的笔记本任务。
  • src/notebook.ipynb：此文件是一个示例笔记本，它在运行时只需初始化包含数字 1 到 10 的 RDD。

对于自定义作业，作业声明中的映射对应于 REST API 参考中的 POST /api/2.1/jobs/create 中定义的创建作业操作的请求负载（以 YAML 格式表示）。

提示

可以使用覆盖 Databricks 资产包中的群集设置中描述的技术来定义、组合和覆盖捆绑包中新作业群集的设置。

步骤 4：验证项目的程序包配置文件

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

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

    databricks bundle validate

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

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

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

此步骤将本地笔记本部署到远程 Azure Databricks 工作区，并在工作区中创建 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>_job”。

  6. 单击“任务”选项卡。应该有一个任务：notebook_task。

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

步骤 6：运行部署的项目

此步骤在工作区中运行 Azure Databricks 作业。

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

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

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

  3. 在 Azure Databricks 工作区中，作业任务成功完成并显示绿色标题栏后，请单击作业任务以查看结果。

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

步骤 7：清理

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

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

    databricks bundle destroy

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

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

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

你已达到使用模板创建捆绑包的步骤的末尾。

手动创建捆绑包

在这些步骤中，从头开始创建捆绑包。 此示例捆绑包由两个笔记本和用于运行这些笔记本的 Azure Databricks 作业定义组成。 然后，从 Azure Databricks 工作区中的作业验证、部署和运行已部署的笔记本。 这些步骤自动执行标题为使用 Azure Databricks 作业创建第一个工作流的快速入门。

步骤 1：创建捆绑包

捆绑包中有要部署的生成工件以及要运行的资源的设置。

  1. 在开发计算机上创建或标识一个空目录。
  2. 切换到终端中的空目录，或在 IDE 中打开空目录。

提示

你的空目录可能与 Git 提供商管理的克隆存储库相关联。 这样，你就可通过外部版本控制管理捆绑包，并更轻松地与其他开发人员和 IT 专业人员就项目展开协作。 但是，为了帮助简化本演示，此处未使用克隆的存储库。

如果你选择为本演示克隆存储库，Databricks 建议克隆空存储库或仅包含基本文件（例如 README 和 .gitignore）的存储库。 否则，该存储库中的任何现有文件可能会不必要地同步到 Azure Databricks 工作区。

步骤 2：将笔记本添加到项目

在此步骤中，需要将两个笔记本添加到项目。 第一个笔记本从北京市卫生局的公共数据源获取自 2007 年以来热门婴儿名字列表。 请参阅该局网站上的婴儿名字：热门名字：从 2007 年开始。 然后，第一个笔记本将此数据保存到名为 my-volume 的 Azure Databricks Unity Catalog 卷中，该卷位于名为 main 的目录中名为 default 的架构中。 第二个笔记本查询保存的数据，并按名字和性别显示 2014 年婴儿姓名的聚合计数。

  1. 在该目录的根目录中，创建第一个笔记本，即名为 retrieve-baby-names.py 的文件。

  2. 将以下代码添加到 retrieve-baby-names.py 文件：

    # Databricks notebook source
import requests

response = requests.get('http://health.data.ny.gov/api/views/jxy9-yhdk/rows.csv')
csvfile = response.content.decode('utf-8')
dbutils.fs.put("/Volumes/main/default/my-volume/babynames.csv", csvfile, True)

  3. 在同一目录中创建第二个笔记本，该文件名为 filter-baby-names.py。

  4. 将以下代码添加到 filter-baby-names.py 文件：

    # Databricks notebook source
babynames = spark.read.format("csv").option("header", "true").option("inferSchema", "true").load("/Volumes/main/default/my-volume/babynames.csv")
babynames.createOrReplaceTempView("babynames_table")
years = spark.sql("select distinct(Year) from babynames_table").toPandas()['Year'].tolist()
years.sort()
dbutils.widgets.dropdown("year", "2014", [str(x) for x in years])
display(babynames.filter(babynames.Year == dbutils.widgets.get("year")))

步骤 3：将捆绑包配置架构文件添加到项目

如果使用支持 YAML 文件和 JSON 架构文件的 IDE（如 Visual Studio Code、PyCharm Professional 或 IntelliJ IDEA Ultimate），则使用 IDE 不仅可以创建程序包配置架构文件，还可以检查项目的程序包配置文件语法和格式，并提供代码补全提示，如下所示。 请注意，稍后在步骤 5 中创建的捆绑包配置文件基于 YAML，而此步骤中的捆绑包配置架构文件基于 JSON。

Visual Studio Code

  1. 将 YAML 语言服务器支持添加到 Visual Studio Code，例如，通过从 Visual Studio Code Marketplace 安装 YAML 扩展。

  2. 使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。 例如，在当前目录中生成名为bundle_config_schema.json的文件，如下所示：

    databricks bundle schema > bundle_config_schema.json

  3. 请注意，稍后在步骤 5 中，你将向捆绑包配置文件的开头添加以下注释，该文件将捆绑包配置文件与指定的 JSON 架构文件相关联：

    # yaml-language-server: $schema=bundle_config_schema.json

    注意

    在前面的注释中，如果 Databricks 资产捆绑包配置 JSON 架构文件位于不同的路径中，请将 bundle_config_schema.json 替换为架构文件的完整路径。

PyCharm 专业版

  1. 使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。 例如，在当前目录中生成名为bundle_config_schema.json的文件，如下所示：

    databricks bundle schema > bundle_config_schema.json

  2. 配置 PyCharm 以识别捆绑包配置 JSON 架构文件，然后按照“配置自定义 JSON 架构”中的说明完成 JSON 架构映射。

  3. 请注意，稍后在步骤 5 中，你将使用 PyCharm 创建或打开捆绑包配置文件。 按照约定，此文件命名为 databricks.yml。

IntelliJ IDEA Ultimate

  1. 使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。 例如，在当前目录中生成名为bundle_config_schema.json的文件，如下所示：

    databricks bundle schema > bundle_config_schema.json

  2. 配置 IntelliJ IDEA 以识别捆绑包配置 JSON 架构文件，然后按照“配置自定义 JSON 架构”中的说明完成 JSON 架构映射。

  3. 请注意，稍后在步骤 5 中，你将使用 IntelliJ IDEA 创建或打开捆绑包配置文件。 按照约定，此文件命名为 databricks.yml。

步骤 4：设置身份验证

此步骤在开发计算机上的 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.databricks.azure.cn。

    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 令牌信息。

步骤 5：将捆绑包配置文件添加到项目

此步骤定义如何部署和运行两个笔记本。 在本演示中，需要使用 Azure Databricks 作业运行第一个笔记本，然后运行第二个笔记本。 由于第一个笔记本保存数据，第二个笔记本查询保存的数据，因此你希望第一个笔记本在第二个笔记本启动之前完成运行。 你将在项目的捆绑包配置文件中对这些目标进行建模。

  1. 在该目录的根目录中，创建程序包配置文件，即名为 databricks.yml 的文件。
  2. 将以下代码添加到 databricks.yml 文件中，并将 <workspace-url> 替换为每工作区 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn。 此 URL 必须与 .databrickscfg 文件中的 URL 匹配：

提示

只有在 IDE 支持的情况下，才需要以 # yaml-language-server 开头的第一行。 有关详细信息，请参阅前面的步骤 3。

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job:
      name: retrieve-filter-baby-names-job
      job_clusters:
        - job_cluster_key: common-cluster
          new_cluster:
            spark_version: 12.2.x-scala2.12
            node_type_id: Standard_DS3_v2
            num_workers: 1
      tasks:
        - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./filter-baby-names.py

targets:
  development:
    workspace:
      host: <workspace-url>

对于自定义作业，作业声明中的映射对应于 REST API 参考中的 POST /api/2.1/jobs/create 中定义的创建作业操作的请求负载（以 YAML 格式表示）。

提示

可以使用覆盖 Databricks 资产包中的群集设置中描述的技术来定义、组合和覆盖捆绑包中新作业群集的设置。

步骤 6：验证项目的程序包配置文件

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

  1. 使用 Databricks CLI 运行 bundle validate 命令，如下所示：

    databricks bundle validate

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

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

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

此步骤将两个本地笔记本部署到远程 Azure Databricks 工作区，并在工作区中创建 Azure Databricks 作业。

  1. 使用 Databricks CLI 运行 bundle deploy 命令，如下所示：

    databricks bundle deploy -t development

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

  3. 单击进入以下文件夹：Users ><your-username>> .bundle > baby-names > development > files。 这两个笔记本应位于此文件夹中。

  4. 检查是否已创建作业：在 Azure Databricks 工作区的边栏中，单击“工作流”。

  5. 在“作业”选项卡上，单击“retrieve-filter-baby-names-job”。

  6. 单击“任务”选项卡。应有两个任务：应该有两个任务 - retrieve-baby-names-task 和 filter-baby-names-task。

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

步骤 8：运行部署的项目

此步骤在工作区中运行 Azure Databricks 作业。

  1. 使用 Databricks CLI 运行 bundle run 命令，如下所示：

    databricks bundle run -t development retrieve-filter-baby-names-job

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

  3. 在 Azure Databricks 工作区中，在两个任务成功完成并显示绿色标题栏后，单击 filter-baby-names-task 任务以查看查询结果。

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

步骤 9：清理

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

  1. 使用 Databricks CLI 运行 bundle destroy 命令，如下所示：

    databricks bundle destroy

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

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

运行 bundle destroy 命令仅会删除已部署的作业和包含两个已部署笔记本的文件夹。 此命令不会删除任何副产物，例如第一个笔记本创建的 babynames.csv 文件。 若要删除 babybnames.csv 文件，请执行以下操作：

  1. 在 Azure Databricks 工作区的边栏中，单击“目录”。
  2. 单击“浏览 DBFS”。
  3. 单击“FileStore”文件夹。
  4. 单击 babynames.csv 旁边的下拉箭头，然后单击“删除”。
  5. 如果还想从开发计算机中删除捆绑包，现在可以从步骤 1 中删除本地目录。

将现有作业定义添加到捆绑包

可以基于现有的作业定义在捆绑包配置文件中定义新作业。 为此，请完成以下步骤：

注意

以下步骤创建一个与现有作业设置相同的新作业。 但是，新作业的作业 ID 与现有作业不同。 无法自动将现有作业 ID 导入捆绑包中。

步骤 1：获取 YAML 格式的现有作业定义

在此步骤中，使用 Azure Databricks 工作区用户界面获取现有作业定义的 YAML 表示形式。

  1. 在 Azure Databricks 工作区的边栏中，单击“工作流”。
  2. 在“作业”选项卡上，单击作业的“名称”链接。
  3. 单击“立即运行”按钮旁边的省略号，然后单击“查看 YAML”。
  4. 在“创建”选项卡上，单击“复制”，将作业定义的 YAML 复制到本地剪贴板。

步骤 2：将作业定义 YAML 添加到捆绑包配置文件

在捆绑包配置文件中，将从上一步复制的 YAML 添加到捆绑包配置文件中标记为 <job-yaml-can-go-here> 的以下位置之一，如下所示：

resources:
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      <job-yaml-can-go-here>

targets:
  <some-unique-programmatic-identifier-for-this-target>:
    resources:
      jobs:
        <some-unique-programmatic-identifier-for-this-job>:
          <job-yaml-can-go-here>

步骤 3：将笔记本、Python 文件和其他生成工件添加到捆绑包

应将现有作业中引用的所有 Python 文件和笔记本都移动到程序包所在的源。

为了更好地与捆绑包兼容，笔记本应使用 IPython 笔记本格式 (.ipynb)。 如果在本地开发程序包，可以通过单击 Azure Databricks 笔记本用户界面中的“文件”>“导出”>“IPython Notebook”，将现有笔记本从 Azure Databricks 工作区导出为 .ipynb 格式。 按照惯例，之后应将下载的笔记本放入捆绑包的 src/ 目录中。

将笔记本、Python 文件和其他生成工件添加到捆绑包后，请确保作业定义引用它们。 例如，对于 src/ 目录中文件名为 hello.ipynb 的笔记本，如果 src/ 目录与引用 src/ 目录的捆绑包配置文件位于同一文件夹中，则作业定义可能会用以下方式表示：

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ./src/hello.ipynb

步骤 4：验证、部署和运行新作业

  1. 运行以下命令，验证程序包的配置文件在语法上是否正确：

    databricks bundle validate

  2. 通过运行以下命令导入捆绑包。 在此命令中，将 <target-identifier> 替换为捆绑包配置中目标的唯一编程标识符：

    databricks bundle deploy -t <target-identifier>

  3. 使用以下命令运行作业。

    databricks bundle run -t <target-identifier> <job-identifier>
    • 将 <target-identifier> 替换为捆绑包配置中目标的唯一编程标识符。
    • 将 <job-identifier> 替换为捆绑配置中作业的唯一编程标识符。