手动创建捆绑包

项目
10/03/2024

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

要求

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

步骤 1：创建捆绑包

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

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

提示

还可以使用一个包含从 Git 提供程序克隆的存储库的目录。这样，就可以通过外部版本控制管理捆绑包，并更轻松地与其他开发人员和 IT 专业人员就项目展开协作。

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

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

在此步骤中，需要将两个笔记本添加到项目。第一个笔记本从纽约州卫生部的公共数据源中获取了自 2007 年以来的流行婴儿姓名列表。请参阅部门网站上的 Baby Names: Trending by Name: Beginning 2007（婴儿姓名：按名称显示趋势：自 2007 年起）。然后，第一个笔记本将此数据保存到名为 my-volume 的 Azure Databricks Unity Catalog 卷中，该卷位于名为 main 的目录中名为 default 的架构中。第二个笔记本查询保存的数据，并按名字和性别显示 2014 年婴儿姓名的聚合计数。

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

将以下代码添加到 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)

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

将以下代码添加到 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 专业版或 IntelliJ IDEA Ultimate），则不仅可以使用 IDE 创建捆绑包配置架构文件，还可以检查项目的捆绑包配置文件语法和格式。虽然稍后在步骤 5 中创建的捆绑包配置文件是基于 YAML 的，但此步骤中的捆绑包配置架构文件是基于 JSON 的。

Visual Studio Code

将 YAML 语言服务器支持添加到 Visual Studio Code，例如，通过从 Visual Studio Code Marketplace 安装 YAML 扩展。
使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。例如，在当前目录中生成名为 bundle_config_schema.json 的文件，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
在步骤 5 中，你将向捆绑包配置文件的开头添加以下注释，该文件将捆绑包配置文件与指定的 JSON 架构文件相关联：
```
# yaml-language-server: $schema=bundle_config_schema.json
```
注意

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

PyCharm 专业版

使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。例如，在当前目录中生成名为 bundle_config_schema.json 的文件，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
配置 PyCharm 以识别捆绑包配置 JSON 架构文件，然后按照“配置自定义 JSON 架构”中的说明完成 JSON 架构映射。
在步骤 5 中，你将使用 PyCharm 创建或打开捆绑包配置文件。按照约定，此文件命名为 databricks.yml。

IntelliJ IDEA Ultimate

使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。例如，在当前目录中生成名为 bundle_config_schema.json 的文件，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
配置 IntelliJ IDEA 以识别捆绑包配置 JSON 架构文件，然后按照“配置自定义 JSON 架构”中的说明完成 JSON 架构映射。
在步骤 5 中，你将使用 IntelliJ IDEA 创建或打开捆绑包配置文件。按照约定，此文件命名为 databricks.yml。

步骤 4：设置身份验证

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

注意

U2M 身份验证适用于实时尝试这些步骤。对于完全自动化的工作流，Databricks 建议改用 OAuth 计算机到计算机 (M2M) 身份验证。请参阅身份验证中的 M2M 身份验证设置说明。

通过对每个目标工作区运行以下命令，使用 Databricks CLI 在本地启动 OAuth 令牌管理。

在以下命令中，将 <workspace-url> 替换为 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
```
databricks auth login --host <workspace-url>
```
Databricks CLI 会提示将输入的信息保存为 Azure Databricks 配置文件。按 Enter 接受建议的配置文件名称，或输入新的或现有的配置文件的名称。任何具有相同名称的现有配置文件都会被输入的信息覆盖。可以使用配置文件在多个工作区之间快速切换身份验证上下文。

若要获取任何现有配置文件的列表，请在单独的终端或命令提示符中使用 Databricks CLI 来运行 databricks auth profiles 命令。若要查看特定配置文件的现有设置，请运行 databricks auth env --profile <profile-name> 命令。
在 Web 浏览器中，按照屏幕上的说明登录到 Azure Databricks 工作区。
若要查看配置文件的当前 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 作业运行第一个笔记本，然后运行第二个笔记本。由于第一个笔记本保存数据，第二个笔记本查询保存的数据，因此你希望第一个笔记本在第二个笔记本启动之前完成运行。你将在项目的捆绑包配置文件中对这些目标进行建模。

从该目录的根目录创建捆绑包配置文件，该文件名为 databricks.yml。
将以下代码添加到 databricks.yml 文件中，并将 <workspace-url> 替换为每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。此 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>

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

提示

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

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

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

使用 Databricks CLI 运行 bundle validate 命令，如下所示：
```
databricks bundle validate
```
如果返回了捆绑包配置的摘要，则表示验证成功。如果返回了任何错误，请修复错误，然后重复此步骤。

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

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

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

使用 Databricks CLI 运行 bundle deploy 命令，如下所示：
```
databricks bundle deploy -t development
```
检查两个本地笔记本是否已部署：在 Azure Databricks 工作区的边栏中，单击“工作区”。
单击进入以下文件夹：Users ><your-username>> .bundle > baby-names > development > files。这两个笔记本应位于此文件夹中。
检查是否已创建作业：在 Azure Databricks 工作区的边栏中，单击“工作流”。
在“作业”选项卡上，单击“retrieve-filter-baby-names-job”。
单击“任务”选项卡。应有两个任务：应该有两个任务 - retrieve-baby-names-task 和 filter-baby-names-task。

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

步骤 8：运行部署的项目

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

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

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

复制终端中显示的 Run URL 值，并将该值粘贴到 Web 浏览器中以打开 Azure Databricks 工作区。
在 Azure Databricks 工作区中，在两个任务成功完成并显示绿色标题栏后，单击 filter-baby-names-task 任务以查看查询结果。

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

步骤 9：清理

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

使用 Databricks CLI 运行 bundle destroy 命令，如下所示：
```
databricks bundle destroy
```
确认作业删除请求：当系统提示是否永久销毁资源时，请键入 y 并按 Enter。
确认笔记本删除请求：当系统提示是否永久销毁先前部署的文件夹及其所有文件时，请键入 y 并按 Enter。

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

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

通过