将 dbx 与 Visual Studio Code 配合使用

项目
09/02/2024

重要

本文档已过时，将来可能不会更新。

Databricks 建议使用 Databricks 资产捆绑包，而不是使用 Databricks Labs 的 dbx。请参阅什么是 Databricks 资产捆绑包？和从 dbx 迁移到捆绑包。

若要将 Azure Databricks 与 Visual Studio Code 配合使用，请参阅 Visual Studio Code 的 Databricks 扩展一文。

本文介绍一个基于 Python 的代码示例，该示例可在任何与 Python 兼容的 IDE 中使用。具体而言，本文介绍如何在 Visual Studio Code 中使用此代码示例，该示例提供以下开发人员工作效率功能：

代码完成
Linting
测试：
调试不需要与远程 Azure Databricks 资源的实时连接的代码对象。

本文使用 dbx by Databricks Labs 以及 Visual Studio Code 将代码示例提交到远程 Azure Databricks 工作区。 dbx 指示 Azure Databricks 计划和编排工作流，以在该工作区中的 Azure Databricks 作业群集上运行提交的代码。

可以使用常用的第三方 Git 提供程序进行代码的版本控制和持续集成以及持续交付或持续部署(CI/CD)。对于版本控制，这些 Git 提供程序包括以下内容：

对于 CI/CD，dbx 支持以下 CI/CD 平台：

为了演示版本控制和 CI/CD 的工作原理，本文介绍如何使用 Visual Studio Code、dbx、此代码示例以及 GitHub 和 GitHub Actions。

代码示例要求

若要使用此代码示例，必须具有以下各项：

Azure Databricks 帐户中的 Azure Databricks 工作区。如果还没有工作区，请创建一个。
一个 GitHub 帐户。如果还没有 GitHub 帐户，请创建一个。

此外，在本地开发计算机上，必须具有以下各项：

Python 3.8 或更高版本。

应该使用与目标群集上安装的版本匹配的 Python 版本。若要获取现有群集上安装的 Python 版本，可以使用群集的 Web 终端运行 python --version 命令。另请参阅 Databricks Runtime 发行说明版本和兼容性中的“系统环境”部分，了解适用于你的目标群集的 Databricks Runtime 版本。在任何情况下，Python 的版本都必须为 3.8 或更高版本。

若要获取当前在本地计算机上引用的 Python 版本，请从本地终端运行 python --version。（根据在本地计算机上设置 Python 的方式，可能需要在整个文章中运行 python3 而不是 python。）另请参阅选择 Python 解释器。
pip。 pip 使用较新版本的 Python 自动安装。若要检查是否已安装 pip，请从本地终端运行 pip --version。（根据在本地计算机上设置 Python 或 pip 的方式，可能需要在整个文章中运行 pip3 而不是 pip。）
dbx 版本 0.8.0 或更高版本。可以通过运行 pip install dbx，从 Python 包索引 (PyPI) 安装 dbx 包。

注意

现在无需安装 dbx。稍后可以在代码示例安装部分中安装它。
一个用于创建 Python 虚拟环境的方法，以确保在 dbx 项目中使用正确版本的 Python 和包依赖项。本文将介绍 pipenv。
设置了身份验证的 Databricks CLI 0.18 或更低版本。

注意

现在无需安装旧版 Databricks CLI（Databricks CLI 版本 0.17）。稍后可以在代码示例安装部分中安装它。如果以后要安装它，则必须记住在那个时候设置身份验证。
Visual Studio Code。
Visual Studio Code 的 Python 扩展。
Visual Studio Code 的 GitHub 拉取请求和问题扩展。
Git。

关于代码示例

本文的 Python 代码示例在 GitHub 中的 databricks/ide-best-practices 存储库中提供，执行以下操作：

从 GitHub 中的 owid/covid-19-data 存储库中获取数据。
筛选特定 ISO 国家/地区代码的数据。
从数据创建数据透视表。
对数据执行数据清洗。
将代码逻辑模块化为可重用函数。
单元测试函数。
提供 dbx 项目配置和设置，使代码能够将数据写入远程 Azure Databricks 工作区中的 Delta 表。

设置代码示例

满足此代码示例的要求后，请完成以下步骤以开始使用代码示例。

注意

这些步骤不包括为 CI/CD 设置此代码示例。无需设置 CI/CD 也能运行此代码示例。若要稍后设置 CI/CD，请参阅使用 GitHub Actions 运行。

步骤1：创建 Python 虚拟环境

在终端中，创建一个空白文件夹，以包含此代码示例的虚拟环境。这些说明使用名为 ide-demo 的父级文件夹。可以为此文件夹指定任何名称。如果使用其他名称，请在整个文章中替换该名称。创建文件夹后，切换到该文件夹，然后从该文件夹启动 Visual Studio Code。请务必在 code 命令中包含此点（.）。

对于 Linux 和 macOS：
```
mkdir ide-demo
cd ide-demo
code .
```
提示

如果收到错误 command not found: code，请参阅 Microsoft 网站上的从命令行启动。

对于 Windows：
```
md ide-demo
cd ide-demo
code .
```
在 Visual Studio Code 上，单击“视图>终端”。
从 ide-demo 文件夹的根目录，结合以下选项运行 pipenv 命令，其中 <version> 是已在本地安装的 Python 的目标版本（最好是与目标群集的 Python 版本匹配的版本），例如 3.8.14。
```
pipenv --python <version>
```
记下 pipenv 命令输出中的 Virtualenv location 值，因为在下一步骤中需要用到。
选择目标 Python 解释器，然后激活 Python 虚拟环境：
1. 在菜单栏上，单击“视图”>“命令面板”，键入 Python: Select，然后单击“Python: 选择解释器”。
2. 选择刚刚创建的 Python 虚拟环境的路径中的 Python 解释器。（此路径在 pipenv 命令的输出中作为 Virtualenv location 值列出。）
3. 在菜单栏上，单击“视图”>“命令面板”，键入 Terminal: Create，然后单击“终端: 创建新终端”。
4. 确保命令提示符指示你位于 pipenv shell 中。若要确认，应在命令提示符前看到类似 (<your-username>) 内容。如果未看到，请运行以下命令：
```
pipenv shell
```
  若要退出 pipenv shell，请运行命令 exit，括号消失。
有关详细信息，请参阅 Visual Studio Code 文档中的在 VS Code 中使用 Python 环境。

步骤 2：从 GitHub 克隆代码示例

在 Visual Studio Code 中，打开 ide-demo 文件夹（“文件>打开文件夹”）（如果尚未打开）。
单击“查看>命令面板”，键入 Git: Clone，然后单击“Git：克隆”。
对于提供存储库 URL 或选择存储库源，请输入 https://github.com/databricks/ide-best-practices
浏览到文件夹 ide-demo，然后单击“选择存储库位置”。

步骤 3：安装代码示例的依赖项

安装 dbx 的某个版本以及与你的 Python 版本兼容的 Databricks CLI 版本 0.18 或更低版本。为此，请在终端的 Visual Studio Code 中，从已激活 pipenv shell 的文件夹 ide-demo (pipenv shell) 运行以下命令：
```
pip install dbx
```
确认已安装 dbx。为此，请运行以下命令：
```
dbx --version
```
如果返回版本号，则已安装 dbx。

如果版本号低于 0.8.0，请运行以下命令来升级 dbx，然后再次查看版本号：
```
pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version
```
安装 dbx 时，会同时自动安装旧版 Databricks CLI（Databricks CLI 版本 0.17）。若要确认已安装旧版 Databricks CLI（Databricks CLI 版本 0.17），请运行以下命令：
```
databricks --version
```
如果返回了 Databricks CLI 版本 0.17，则会安装旧版 Databricks CLI。
如果尚未设置带有身份验证的旧版 Databricks CLI（Databricks CLI 版本 0.17），则必须立即进行设置。若要确认是否已设置身份验证，请运行以下命令以获取有关 Azure Databricks 工作区的一些摘要信息。请确保在 ls 子命令后面包括正斜杠（/）：
```
databricks workspace ls /
```
如果返回工作区的根级文件夹名称列表，则会设置身份验证。
安装此代码示例所依赖的 Python 包。若要进行此验证，请从文件夹 ide-demo/ide-best-practices 运行以下命令：
```
pip install -r unit-requirements.txt
```
确认已安装代码示例的依赖包。为此，请运行以下命令：
```
pip list
```
如果文件夹 requirements.txt 和 unit-requirements.txt 中列出的包位于此列表中的某个位置，则已安装依赖包。

注意

requirements.txt 中列出的文件适用于特定包版本。为了获得更好的兼容性，可以将这些版本与希望 Azure Databricks 工作区用于以后运行部署的群集节点类型交叉引用。请参阅 Databricks Runtime 发行说明版本和兼容性中的“系统环境”部分，了解你的群集的 Databricks Runtime 版本。

步骤 4：自定义 Azure Databricks 工作区的代码示例

自定义存储库的 dbx 项目设置。要执行此操作，请在 .dbx/project.json 文件中，将 profile 对象的值从 DEFAULT 更改为配置文件的名称，其与使用旧版 Databricks CLI（Databricks CLI 版本 0.17）进行身份验证而设置的配置文件相匹配。如果未设置任何非默认配置文件，请保留 DEFAULT 原样。例如：
```
{
  "environments": {
    "default": {
      "profile": "DEFAULT",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Shared/dbx/covid_analysis",
        "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
      }
    }
  },
  "inplace_jinja_support": false
}
```

自定义 dbx 项目的部署设置。为此，请在 conf/deployment.yml 文件中将 spark_version 和 node_type_id 对象的值从 10.4.x-scala2.12 和 m6gd.large 更改为你希望 Azure Databricks 工作区用于在其上运行部署的 Azure Databricks 运行时版本字符串和群集节点类型。

例如，指定 Databricks Runtime 10.4 LTS 和 Standard_DS3_v2 节点类型：

environments:
  default:
    workflows:
      - name: "covid_analysis_etl_integ"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
        node_type_id: "Standard_DS3_v2"
        spark_python_task:
          python_file: "file://jobs/covid_trends_job.py"
      - name: "covid_analysis_etl_prod"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
          node_type_id: "Standard_DS3_v2"
          spark_python_task:
            python_file: "file://jobs/covid_trends_job.py"
          parameters: ["--prod"]
      - name: "covid_analysis_etl_raw"
        new_cluster:
          spark_version: "10.4.x-scala2.12"
          num_workers: 1
          node_type_id: "Standard_DS3_v2"
          spark_python_task:
            python_file: "file://jobs/covid_trends_job_raw.py"

提示

在此示例中，三个作业定义中的每一个都具有相同的 spark_version 和 node_type_id 值。可以将不同的值用于不同的作业定义。还可以创建共享值，并在作业定义之间重复使用，以减少键入错误和代码维护。请参阅 dbx 文档中的 YAML 示例。

浏览代码示例

设置代码示例后，请使用以下信息了解 ide-demo/ide-best-practices 文件夹中的各种文件的工作原理。

代码模块化

非模块化代码

该文件 jobs/covid_trends_job_raw.py 是代码逻辑的非模块化版本。可以单独运行此文件。

模块化代码

该文件 jobs/covid_trends_job.py 是代码逻辑的模块化版本。此文件依赖于文件 covid_analysis/transforms.py 中的共享代码。该文件 covid_analysis/__init__.py 将文件夹 covide_analysis 视为包含包。

测试

单元测试

该文件 tests/testdata.csv 包含文件 covid-hospitalizations.csv 中用于测试的一小部分数据。该文件 tests/transforms_test.py 包含文件 covid_analysis/transforms.py 的单元测试。

单元测试运行程序

该文件 pytest.ini 包含使用 pytest 运行测试的配置选项。请参阅 pytest 文档中的 pytest.ini 和配置选项。

该文件 .coveragerc 包含使用 coverage.py 的 Python 代码覆盖率度量的配置选项。请参阅 coverage.py 文档中的配置参考。

该文件 requirements.txt 是之前使用 pip 运行的文件 unit-requirements.txt 的子集，包含单元测试也依赖的包列表。

打包

该文件 setup.py 提供在控制台（控制台脚本）中运行的命令，例如 pip 命令，用于将 Python 项目打包为 setuptools。请参阅 setuptools 文档中的入口点。

其他文件

此代码示例中还有其他尚未描述的文件：

该 .github/workflows 文件夹包含三个文件，databricks_pull_request_tests.yml、onpush.yml 以及 onrelease.yaml，代表 GitHub Actions，稍后在 GitHub Actions 部分中介绍。
该文件 .gitignore 包含 Git 为存储库忽略的本地文件夹和文件的列表。

运行代码示例

可以在本地计算机上使用 dbx，指示 Azure Databricks 按需在远程工作区中运行代码示例，如下一个子节中所述。或者，每次将代码更改推送到 GitHub 存储库时，可以使用 GitHub Actions 让 GitHub 运行代码示例。

使用 dbx 运行

从 dbx 项目的根目录（例如文件夹 ide-demo/ide-best-practices）运行以下命令，在 Python setuptools 开发模式下将 covid_analysis 文件夹的内容安装为包。请务必在命令末尾包含点 (.)：
```
pip install -e .
```
此命令创建一个 covid_analysis.egg-info 文件夹，其中包含有关 covid_analysis/__init__.py 和 covid_analysis/transforms.py 文件编译版本的信息。
通过运行以下命令运行测试：
```
pytest tests/
```
测试结果在终端中显示。这四个测试都应显示为通过。

提示

有关测试的其他方法，包括 R 和 Scala 笔记本的测试，请参阅笔记本的单元测试。
（可选）运行以下命令，获取测试的测试覆盖率指标：
```
coverage run -m pytest tests/
```
注意

如果显示 coverage 找不到的消息，请运行 pip install coverage，然后重试。

若要查看测试覆盖率结果，请运行以下命令：
```
coverage report -m
```
如果四项测试全都通过，请运行以下命令，将 dbx 项目的内容发送到你的 Azure Databricks 工作区：
```
dbx deploy --environment=default
```
有关项目及其运行的信息将发送到 .dbx/project.json 文件中 workspace_directory 对象中指定的位置。

项目的内容将发送到 .dbx/project.json 文件中 artifact_location 对象中指定的位置。
运行以下命令，在工作区中运行代码的预生产版本：
```
dbx launch covid_analysis_etl_integ
```
指向运行结果的链接在终端中显示。结果应如下所示：
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
```
按照 Web 浏览器中的此链接查看工作区中的运行结果。
运行以下命令，在工作区中运行代码的生产版本：
```
dbx launch covid_analysis_etl_prod
```
指向运行结果的链接在终端中显示。结果应如下所示：
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
```
按照 Web 浏览器中的此链接查看工作区中的运行结果。

使用 GitHub Actions 运行

在项目的 .github/workflows 文件夹中，onpush.yml 和 onrelease.yml GitHub Actions 文件执行以下操作：

在每次推送到以 v 开头的标记时，用 dbx 来部署 covid_analysis_etl_prod 作业。
在每次推送到不以 v 开头的标记时：
1. 使用 pytest 运行单元测试
2. 使用 dbx 将 covid_analysis_etl_integ 作业中指定的文件部署到远程工作区。
3. 使用 dbx 启动远程工作区上 covid_analysis_etl_integ 作业中指定的已部署文件，跟踪此运行，直到它完成。

注意

还提供了一个额外的 databricks_pull_request_tests.yml GitHub Actions 文件，供你作为模板进行试验，而不会影响 onpush.yml 和 onrelease.yml GitHub Actions 文件。无需 databricks_pull_request_tests.yml GitHub Actions 文件即可运行此代码示例。本文未介绍其用法

以下子节介绍如何设置和运行 onpush.yml 和 onrelease.yml GitHub Actions 文件。

设置为使用 GitHub Actions

按照 CI/CD 服务主体中的说明设置 Azure Databricks 工作区。此过程包括以下操作：

创建服务主体。
为服务主体创建 Microsoft Entra ID 令牌。

Databricks 建议为服务主体使用 Microsoft Entra ID 令牌，而不是工作区用户的 Databricks 个人访问令牌，以便 GitHub 向 Azure Databricks 工作区进行身份验证，这是安全最佳做法。

创建服务主体及其 Microsoft Entra ID 令牌后，请停止并记下将在下一部分使用的 Microsoft Entra ID 令牌值。

运行 GitHub Actions

步骤 1：发布克隆的存储库

在 Visual Studio Code 的边栏中，单击“GitHub”图标。如果图标不可见，请先通过“扩展”视图（视图>扩展）启用 GitHub 拉取请求和问题扩展。
如果“登录”按钮可见，请单击该按钮，然后按照屏幕上的说明登录到 GitHub 帐户。
在菜单栏上，单击“视图>命令面板”，键入 Publish to GitHub，然后单击“发布到 GitHub”。
选择将克隆的存储库发布到 GitHub 帐户的选项。

步骤 2：将加密机密添加到存储库

在已发布存储库的 GitHub 网站中，请按照创建存储库加密机密中的说明操作，获取以下加密机密：

创建一个名为 DATABRICKS_HOST 的加密机密，设置为每个工作区 URL 的值，例如 https://adb-1234567890123456.7.databricks.azure.cn。
创建一个名为 DATABRICKS_TOKEN 的加密机密，设置为服务主体的 Microsoft Entra ID 令牌的值。

步骤 3：创建分支并将其发布到存储库

在 Visual Studio Code 的“源代码管理”视图（视图>源代码管理）中，单击… （视图和更多操作）图标。
单击“分支>创建分支”。
输入分支的名称，例如 my-branch。
选择要从中创建分支的分支，例如 main。
对本地存储库中的其中一个文件进行轻微更改，然后保存该文件。例如，对 tests/transforms_test.py 文件中的代码注释进行轻微更改。
在“源代码管理”视图中，再次单击... （视图和更多操作）图标。
单击“更改>暂存所有更改”。
再次单击... （视图和更多操作）图标。
单击“暂存>暂存提交”。
输入提交消息。
再次单击... （视图和更多操作）图标。
单击“分支>发布分支”。

步骤 4：创建拉取请求和合并

转到已发布存储库 https://github/<your-GitHub-username>/ide-best-practices 的 GitHub 网站。
在“拉取请求”选项卡上，单击“my-branch 有最近推送”旁边的“比较和拉取请求”。
单击“创建拉取请求”。
在拉取请求页上，等待 CI pipleline/ci-pipeline （推送）旁边的图标显示绿色复选标记。（图标可能需要一些时间才能显示。）如果出现红色 X 而不是绿色复选标记，请单击“详细信息”以找出原因。如果图标或“详细信息”不再显示，请单击“显示所有检查”。
如果出现绿色复选标记，请单击main“合并拉取请求”将拉取请求合并到分支中。

通过