笔记本的软件工程最佳做法

本文提供了一个实践演练，演示如何将软件工程最佳做法应用于Azure Databricks笔记本，包括版本控制、代码共享、测试以及（可选）持续集成和持续交付或部署（CI/CD）。

在本演练中，你将：

  • 将笔记本添加到Azure Databricks Git 文件夹进行版本控制。
  • 将某个笔记本中的部分代码提取到可共享模块中。
  • 测试共享代码。
  • 从 Azure Databricks 作业中运行笔记本。
  • （可选）将 CI/CD 应用于共享代码。

要求

要完成本演练，必须提供以下资源：

  • 具有 Databricks 支持的 Git 提供程序的远程存储库。 本文的演练使用GitHub平台。 本演练假定你有一个名为 best-notebooks 的GitHub存储库。 （可以为存储库提供其他名称。如果这样做，请将 best-notebooks 替换为本演练中存储库的名称。创建GitHub存储库如果还没有存储库。

    注意

    如果创建新存储库，请务必使用至少一个文件（例如 README 文件）初始化存储库。

  • Azure Databricks 工作区。 如果还没有工作区，请创建一个。

  • 工作区中的Azure Databricks 通用群集。 要在设计阶段运行笔记本，可将笔记本附加到正在运行的通用群集。 稍后，本演练使用 Azure Databricks job 自动运行此群集上的笔记本。 （还可在仅存在于作业生存期的作业群集上运行作业。）如果还没有通用群集，则创建通用群集。

步骤 1：设置 Databricks Git 文件夹

在此步骤中，将现有GitHub存储库连接到现有Azure Databricks工作区中的Azure Databricks Git 文件夹。

若要使工作区能够连接到GitHub存储库，必须先向工作区提供GitHub凭据（如果尚未这样做）。

步骤 1.1：提供GitHub凭据

  1. 单击工作区右上角的用户名，然后单击下拉列表中的 “设置 ”。
  2. 在“设置”边栏的“用户”下，点击“链接帐户”。
  3. 在 Git 集成下，对于 Git 提供程序，请选择 GitHub。
  4. 单击 个人访问令牌。
  5. 对于 Git 提供程序用户名或电子邮件，请输入GitHub用户名。
  6. 对于 Token，请输入GitHub个人访问令牌（经典）。 此个人访问令牌（经典）必须具有存储库和工作流权限。
  7. 单击“ 保存”。

步骤 1.2：连接到GitHub存储库

  1. 在工作区边栏上，点击“工作区”。
  2. 在工作区浏览器中，展开 工作区> 用户。
  3. 右键单击用户名文件夹，然后单击“创建”>“Git 文件夹”。
  4. 在“创建 Git 文件夹”对话框中：
    1. 对于Git 存储库 URL，请输入 GitHub 仓库的使用 HTTPS 克隆 URL。 本文假定 URL 以 best-notebooks.git 结尾，例如 https://github.com/<your-GitHub-username>/best-notebooks.git。
    2. 对于 Git 提供程序，请选择 GitHub。
    3. 将“Git 文件夹名称”设为你的存储库的名称，例如 best-notebooks。
    4. 单击“创建 Git 文件夹”。

步骤 2：导入并运行笔记本

在此步骤中，将现有外部笔记本导入存储库。 可以为本演练创建自己的笔记本，但为了提高效率，我们已经在这里为您准备好了笔记本。

步骤 2.1：在存储库中创建工作分支

在此子步骤中，你将在存储库中创建一个名为 eda 的分支。 通过此分支，可以独立于存储库的 main 分支来处理文件和代码，这是软件工程最佳做法。 （可为分支提供其他名称。）

注意

在某些存储库中，可以改为将 main 分支命名为 master。 如果这样做，请在本演练中将 main 替换为 master。

提示

如果不熟悉使用 Git 分支，请参阅 Git 网站上的 Git 分支 - Nutshell 中的分支。

  1. 应会打开步骤 1.2 中的 Git 文件夹。 如果没有，请在“工作区”边栏中展开“工作区 > 用户”，然后展开您的用户名文件夹，并单击您的 Git 文件夹。

  2. 在工作区导航痕迹下的文件夹名称旁边，单击“主 Git 分支”按钮。

  3. 在“best-notebooks”对话框中点击“创建分支”按钮。

    注意

    如果存储库的名称不是 best-notebooks，则在此处和演练的其他地方该对话框的标题将有所不同。

  4. 输入eda并点击“创建”。

  5. 关闭此对话框。

步骤 2.2：将笔记本导入存储库

在此子步骤中，将现有笔记本从另一个存储库导入你的存储库。 此笔记本执行以下操作：

  • 将 CSV 文件从 owid/covid-19-data GitHub 存储库复制到工作区中的群集。 此 CSV 文件包含有关全球 COVID-19 住院和重症监护指标的公共数据。
  • 将 CSV 文件的内容读入 pandasDataFrame。
  • 筛选数据以仅包含来自美国的指标。
  • 显示数据的绘图。
  • 将 pandas DataFrame 另存为 Spark 上的 Pandas APIDataFrame。
  • 在 Spark 数据帧上对 Pandas API 执行数据清洗。
  • 将“Spark 上的 Pandas API”数据帧以 Delta 表形式写入工作区。
  • 显示 Delta 表的内容。

虽然可在存储库中创建自己的笔记本，但在此导入现有笔记本有助于加快本演练的进度。 若要在此分支中创建笔记本或将现有笔记本移入此分支而不是导入笔记本，请参阅工作区文件基本用法。

  1. 在“best-notebooks”Git 文件夹中，单击创建 文件夹>。
  2. 在“新建文件夹”对话框中输入 ，然后单击“创建”notebooks。
  3. 在“笔记本”文件夹中，点击三个点，然后选择“导入”。
  4. 在 “导入 ”对话框中：

    1. 对于“导入自”，请选择“URL”。

    2. 在 GitHub 的 covid_eda_raw 存储库中输入 databricks/notebook-best-practices 笔记本原始内容的 URL。 要获取此 URL，请执行以下步骤：i. 转到 https://github.com/databricks/notebook-best-practices 。 二. 单击 notebooks 文件夹。 第三。 单击 covid_eda_raw.py 文件。 四。 单击“原始”。 v. 将 Web 浏览器地址栏中的完整 URL 复制到 “导入”对话框。

      注意

      “导入”对话框仅支持使用公有库的 Git URL。

    3. 单击“导入” 。

步骤 2.3：运行笔记本

  1. 如果笔记本尚未显示，请打开“笔记本”文件夹，然后单击文件夹内的“covid_eda_raw”笔记本。
  2. 选择群集以将笔记本附加到其中。 有关创建群集的说明，请参阅创建群集。
  3. 单击“全部运行”。
  4. 等待笔记本运行。

笔记本运行完成后，你应会在笔记本中看到数据的绘图以及 Delta 表中超过 600 行的原始数据。 如果你在开始运行此笔记本时群集尚未运行，群集可能需要几分钟才能启动，然后才能显示结果。

步骤 2.4：将笔记本签入并合并

在此子步骤中，将到目前为止的工作保存到GitHub存储库。 然后将笔记本从工作分支合并到存储库的 main 分支。

  1. 在笔记本的名称旁边，单击“eda” Git 分支按钮。
  2. 在 best-notebooks 对话框中的“更改”选项卡上，确保已选中 notebooks/covid_eda_raw.py 文件。
  3. 对于“提交消息（必填）”，请输入 Added raw notebook。
  4. 对于说明（可选），请输入This is the first version of the notebook.
  5. 单击提交和推送。
  6. 单击横幅中“在 git 提供程序上创建拉取请求”中的拉取请求链接。
  7. 在GitHub中创建拉取请求，然后将拉取请求合并到 main 分支中。
  8. 返回Azure Databricks工作区，如果仍显示，请关闭 best-notebooks 对话框。

步骤 3：将代码移到共享模块中

在此步骤中，将笔记本中的部分代码移到笔记本外部的一组共享函数中。 这样做可将这些函数与其他类似的笔记本配合使用，从而加快将来的编码速度，并帮助确保笔记本结果更加可预测且更一致。 共享此代码还使你能够更轻松地测试这些函数，这作为软件工程最佳做法，可以提高代码的整体质量。

步骤 3.1：在存储库中创建其他工作分支

  1. 在笔记本的名称旁边，单击“eda” Git 分支按钮。
  2. 在“best-notebooks”对话框中，单击“eda”分支旁的下拉箭头，然后选择“main”。
  3. 单击“拉取”按钮。 如果提示继续拉取，请点击确认。
  4. 单击“创建分支”按钮。
  5. 输入 first_modules，然后单击“创建”。 （可为分支提供其他名称。）
  6. 关闭此对话框。

步骤 3.2：将笔记本导入存储库

要加快本演练的速度，在此子步骤中，将另一个现有笔记本导入存储库。 此笔记本与上一个笔记本执行相同的操作，但此笔记本将调用存储在笔记本外部的共享代码函数。 同样，你可在此处的存储库中创建自己的笔记本，并自行执行实际代码共享。

  1. 在“工作区”浏览器中，右键单击“笔记本”文件夹，然后单击“导入”。
  2. 在 “导入 ”对话框中：

    1. 对于“导入自”，请选择“URL”。

    2. 在 GitHub 的 covid_eda_modular 存储库中输入 databricks/notebook-best-practices 笔记本原始内容的 URL。 要获取此 URL，请执行以下步骤：i. 转到 https://github.com/databricks/notebook-best-practices 。 二. 单击 notebooks 文件夹。 第三。 单击 covid_eda_modular.py 文件。 四。 单击“原始”。 v. 将 Web 浏览器地址栏中的完整 URL 复制到 “导入笔记本”对话框。

      注意

      “导入笔记本”对话框仅适用于公共存储库的 Git URL。

    3. 单击“导入” 。

第 3.3 步：添加笔记本的共享代码支持函数

  1. 在工作区浏览器中，右键单击best-notebooks Git 文件夹，然后单击创建 > 文件夹。

  2. 在“新建文件夹”对话框中输入 ，然后单击“创建”covid_analysis。

  3. 在 covid_analysis 文件夹中，单击Create File。

  4. 在“新文件名称”对话框中输入 ，然后单击“创建文件”。

  5. 在 transforms.py 编辑器窗口中输入以下代码：

    import pandas as pd

# Filter by country code.
def filter_country(pdf, country="USA"):
  pdf = pdf[pdf.iso_code == country]
  return pdf

# Pivot by indicator, and fill missing values.
def pivot_and_clean(pdf, fillna):
  pdf["value"] = pd.to_numeric(pdf["value"])
  pdf = pdf.fillna(fillna).pivot_table(
    values="value", columns="indicator", index="date"
  )
  return pdf

# Create column names that are compatible with Delta tables.
def clean_spark_cols(pdf):
  pdf.columns = pdf.columns.str.replace(" ", "_")
  return pdf

# Convert index to column (works with pandas API on Spark, too).
def index_to_col(df, colname):
  df[colname] = df.index
  return df

提示

有关其他代码共享技术，请参阅在 Databricks 笔记本之间共享代码。

步骤 3.4：添加共享代码的依赖项

前面的代码有多个Python包依赖项，使代码能够正常运行。 在此子步骤中，你将声明这些包依赖项。 声明依赖项通过使用精确定义的库版本来提高可再现性。

  1. 在工作区浏览器中，右键单击best-notebooks Git 文件夹，然后单击创建>文件。

    注意

    你希望列有包依赖项的文件进入 Git 文件夹的根目录而不是 notebooks 或 covid_analysis 文件夹。

  2. 在“新文件名称”对话框中输入 ，然后单击“创建文件”。

  3. 在 requirements.txt 编辑器窗口中，输入以下代码：

    注意

    如果 requirements.txt 文件不可见，可能需要刷新 Web 浏览器。

    -i https://pypi.org/simple
attrs==21.4.0
cycler==0.11.0
fonttools==4.33.3
iniconfig==1.1.1
kiwisolver==1.4.2
matplotlib==3.5.1
numpy==1.22.3
packaging==21.3
pandas==1.4.2
pillow==9.1.0
pluggy==1.0.0
py==1.11.0
py4j==0.10.9.3
pyarrow==7.0.0
pyparsing==3.0.8
pyspark==3.2.1
pytest==7.1.2
python-dateutil==2.8.2
pytz==2022.1
six==1.16.0
tomli==2.0.1
wget==3.2

    注意

    上述文件列出了特定的包版本。 为了获得更好的兼容性，可以将这些版本与安装在通用群集上的版本进行交叉引用。 请参阅“系统环境”部分，以获取 Databricks Runtime 发行说明版本和兼容性中的群集 Databricks Runtime 版本信息。

存储库结构现应如下所示：

|-- covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
└── requirements.txt

步骤 3.5：运行重构的笔记本

在此子步骤中，你将运行 covid_eda_modular 笔记本，该笔记本将调用 covid_analysis/transforms.py 中的共享代码。

  1. 在“工作区”浏览器中，单击“笔记本”文件夹中的“covid_eda_modular”笔记本。
  2. 选择群集以将笔记本附加到其中。
  3. 单击“全部运行”。
  4. 等待笔记本运行。

笔记本运行完成后，你应会在笔记本中看到与 covid_eda_raw 笔记本相似的结果：数据绘图以及 Delta 表中超过 600 行的原始数据。 此笔记本的主要区别在于使用了不同的过滤器（使用 iso_code 的 DZA 而不是 USA）。 如果你在开始运行此笔记本时群集尚未运行，群集可能需要几分钟才能启动，然后才能显示结果。

  1. 在笔记本的名称旁边，单击“ first_modules”Git 分支按钮。
  2. 在“best-notebooks”对话框的“更改”选项卡上，确保已选择以下内容：
    • requirements.txt
    • covid_analysis/transforms.py
    • notebooks/covid_eda_modular.py
  3. 对于“提交消息（必填）”，请输入 Added refactored notebook。
  4. 对于说明（可选），请输入This is the second version of the notebook.
  5. 单击提交和推送。
  6. 单击横幅中“在 git 提供程序上创建拉取请求”中的拉取请求链接。
  7. 在GitHub中创建拉取请求，然后将拉取请求合并到 main 分支中。
  8. 返回Azure Databricks工作区，如果仍显示，请关闭 best-notebooks 对话框。

步骤 4：测试共享代码

在此步骤中，你将测试上一步中的共享代码。 但是，你希望在不运行 covid_eda_modular 笔记本本身的情况下测试此代码。 这是因为如果共享代码无法运行，笔记本本身也可能无法运行。 你希望在主笔记本最终出现故障之前，先捕获共享代码中的故障。 此测试技术是软件工程最佳做法。

提示

有关笔记本测试以及 R 和 Scala 笔记本测试的其他方法，请参阅笔记本单元测试。

步骤 4.1：在存储库中创建其他工作分支

  1. 在笔记本的名称旁边，单击“ first_modules”Git 分支按钮。
  2. 在best-notebooks对话框中，单击first_modules分支旁的下拉箭头，然后选择main。
  3. 单击“拉取”按钮。 如果提示继续拉取，请点击确认。
  4. 单击“创建分支”。
  5. 输入 first_tests，然后单击“创建”。 （可为分支提供其他名称。）
  6. 关闭此对话框。

步骤 4.2：添加测试

在此子步骤中，使用 pytest 框架测试共享代码。 在这些测试中，你验证是否实现了特定的测试结果。 如果任一测试产生意外结果，则该测试未能通过断言，因此测试本身也失败。

  1. 在“工作区”浏览器中，右键单击 Git 文件夹，然后单击“创建”“文件夹”>。

  2. 在“新建文件夹”对话框中输入 ，然后单击“创建”tests。

  3. 在“测试”文件夹中，单击“创建”“文件”>。

  4. 在“新文件名称”对话框中输入 ，然后单击“创建文件”。

  5. 在 testdata.csv 编辑器窗口中输入以下测试数据：

    entity,iso_code,date,indicator,value
United States,USA,2022-04-17,Daily ICU occupancy,
United States,USA,2022-04-17,Daily ICU occupancy per million,4.1
United States,USA,2022-04-17,Daily hospital occupancy,10000
United States,USA,2022-04-17,Daily hospital occupancy per million,30.3
United States,USA,2022-04-17,Weekly new hospital admissions,11000
United States,USA,2022-04-17,Weekly new hospital admissions per million,32.8
Algeria,DZA,2022-04-18,Daily ICU occupancy,1010
Algeria,DZA,2022-04-18,Daily ICU occupancy per million,4.5
Algeria,DZA,2022-04-18,Daily hospital occupancy,11000
Algeria,DZA,2022-04-18,Daily hospital occupancy per million,30.9
Algeria,DZA,2022-04-18,Weekly new hospital admissions,10000
Algeria,DZA,2022-04-18,Weekly new hospital admissions per million,32.1

  6. 在“测试”文件夹中，单击“创建”“文件”>。

  7. 在“新文件名称”对话框中输入 ，然后单击“创建文件”。

  8. 在 transforms_test.py 编辑器窗口中，输入以下测试代码。 这些测试使用标准 pytest固定例程以及模拟的内存中 pandas DataFrame：

    # Test each of the transform functions.
import pytest
from textwrap import fill
import os
import pandas as pd
import numpy as np
from covid_analysis.transforms import *
from pyspark.sql import SparkSession

@pytest.fixture
def raw_input_df() -> pd.DataFrame:
  """
  Create a basic version of the input dataset for testing, including NaNs.
  """
  return pd.read_csv('tests/testdata.csv')

@pytest.fixture
def colnames_df() -> pd.DataFrame:
  df = pd.DataFrame(
    data=[[0,1,2,3,4,5]],
    columns=[
      "Daily ICU occupancy",
      "Daily ICU occupancy per million",
      "Daily hospital occupancy",
      "Daily hospital occupancy per million",
      "Weekly new hospital admissions",
      "Weekly new hospital admissions per million"
    ]
  )
  return df

# Make sure the filter works as expected.
def test_filter(raw_input_df):
  filtered = filter_country(raw_input_df)
  assert filtered.iso_code.drop_duplicates()[0] == "USA"

# The test data has NaNs for Daily ICU occupancy; this should get filled to 0.
def test_pivot(raw_input_df):
  pivoted = pivot_and_clean(raw_input_df, 0)
  assert pivoted["Daily ICU occupancy"][0] == 0

# Test column cleaning.
def test_clean_cols(colnames_df):
  cleaned = clean_spark_cols(colnames_df)
  cols_w_spaces = cleaned.filter(regex=(" "))
  assert cols_w_spaces.empty == True

# Test column creation from index.
def test_index_to_col(raw_input_df):
  raw_input_df["col_from_index"] = raw_input_df.index
  assert (raw_input_df.index == raw_input_df.col_from_index).all()

存储库结构现应如下所示：

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

步骤 4.3：运行测试

为加快本演练的速度，在本子步骤中，你将使用导入的笔记本来运行前面的测试。 此笔记本将测试的依赖Python包下载并安装到工作区中，运行测试并报告测试的结果。 虽然可从群集的 pytest运行 ，但从笔记本运行 pytest 可能会更方便。

注意

如果运行 pytest，将运行当前目录及其子目录中名称遵循 test_*.py 或 /*_test.py 形式的所有文件。

  1. 在“工作区”浏览器中，右键单击“笔记本”文件夹，然后单击“导入”。

  2. 在 “导入笔记本 ”对话框中：

    1. 对于“导入自”，请选择“URL”。

    2. 在 GitHub 的 run_unit_tests 存储库中输入 databricks/notebook-best-practices 笔记本原始内容的 URL。 要获取此 URL，请执行以下步骤：i. 转到 https://github.com/databricks/notebook-best-practices 。 二. 单击 notebooks 文件夹。 第三。 单击 run_unit_tests.py 文件。 四。 单击“原始”。 v. 将 Web 浏览器地址栏中的完整 URL 复制到 “导入笔记本”对话框。

      注意

      “导入笔记本”对话框仅适用于公共存储库的 Git URL。

    3. 单击“导入” 。

  3. 选择群集以将笔记本附加到其中。

  4. 单击“全部运行”。

  5. 等待笔记本运行。

笔记本运行完成后，你应会在笔记本中看到有关测试通过或失败次数的信息，以及其他相关详细信息。 如果你在开始运行此笔记本时群集尚未运行，群集可能需要几分钟才能启动，然后才能显示结果。

存储库结构现应如下所示：

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py
  1. 在笔记本名称旁边，单击“first_tests”Git 分支按钮。
  2. 在“best-notebooks”对话框的“更改”选项卡上，确保已选择以下内容：
    • tests/transforms_test.py
    • notebooks/run_unit_tests.py
    • 测试/testdata.csv
  3. 对于“提交消息（必填）”，请输入 Added tests。
  4. 对于“说明(可选)”，请输入 。
  5. 单击提交和推送。
  6. 单击横幅中“在 git 提供程序上创建拉取请求”中的拉取请求链接。
  7. 在GitHub中创建拉取请求，然后将拉取请求合并到 main 分支中。
  8. 返回Azure Databricks工作区，如果仍显示，请关闭 best-notebooks 对话框。

步骤 5：创建作业以运行笔记本

在前面的步骤中，你手动测试了共享代码，并手动运行了笔记本。 在此步骤中，您将使用 Azure Databricks 作业来测试共享代码，并按需或定期自动运行笔记本。

步骤 5.1：创建作业任务以运行测试笔记本

  1. 在工作区中，单击边栏中的“工作流”图标。作业和管道。
  2. 单击创建，然后选择作业。
  3. 将作业名称编辑为 covid_report。
  4. 单击 “笔记本” 磁贴以配置第一个任务。 如果 笔记本 磁贴不可用，请单击“ 添加其他任务类型 ”并搜索 笔记本。
  5. 对于“任务名称”，请输入 。
  6. 如有必要，请从“类型”下拉菜单中选择“笔记本”。
  7. 对于源，选择Git 提供者。
  8. 单击“添加 git 引用”。
  9. 在“Git 信息”对话框中执行以下操作：
    1. 对于Git 存储库 URL，请输入 GitHub 仓库的使用 HTTPS 克隆 URL。 本文假定 URL 以 best-notebooks.git 结尾，例如 https://github.com/<your-GitHub-username>/best-notebooks.git。
    2. 对于 Git 提供程序，请选择 GitHub。
    3. 对于Git 引用（分支 / 标签 / 提交），请输入main。
    4. 在“Git 引用(分支/标记/提交)”旁边，选择“分支”。
    5. 单击“确认” 。
  10. 对于“路径”，请输入 。 不要添加 .py 文件扩展名。
  11. 对于“群集”，请选择上一步中的群集。
  12. 单击“创建任务”。

注意

在这种情况下，Databricks 不建议使用笔记本中的计划按钮（如创建和管理计划的笔记本作业中所述）来计划作业以定期运行此笔记本。 这是因为计划按钮会使用工作区存储库中笔记本的最新工作副本来创建作业。 相反，Databricks 建议你按照上述说明创建一个任务，使其使用存储库中笔记本的最新提交版本。

步骤 5.2：创建作业任务以运行主笔记本

  1. 单击“+ 添加任务”图标。
  2. 此时将显示一个弹出菜单。 选择“笔记本”。
  3. 对于“任务名称”，请输入 。
  4. 对于“类型”，请选择“笔记本”。
  5. 对于“路径”，请输入 。 不要添加 .py 文件扩展名。
  6. 对于“群集”，请选择上一步中的群集。
  7. 验证 取决于 值是否是 run_notebook-tests。
  8. 单击“创建任务”。

步骤 5.3 运行作业

  1. 单击“立即运行”。

  2. 在弹出窗口中，单击“查看运行情况”。

    注意

    如果弹出窗口消失得太快，请执行以下操作：

    1. 在数据科学与工程或 Databricks Mosaic AI 环境的边栏上，单击作业和管道。
    2. 在“作业运行”选项卡中，找到“作业”列中包含 covid_report 的最新作业，然后单击其“开始时间”值。

  3. 要查看作业结果，请单击 run_notebook_tests 磁贴和/或 run_main_notebook 磁贴。 每个面板上的结果与您逐个运行这些笔记本的结果相同。

注意

此作业按需运行。 若要设置此作业以定期运行，请参阅 使用计划和触发器自动执行作业。

（可选）步骤 6：设置存储库以测试代码并在代码发生更改时自动运行笔记本

在上一步中，你使用任务来自动测试你的共享代码，并在某个时间点或定期运行笔记本。 但是，你可能希望使用 CI/CD 工具（如 GitHub Actions）将更改合并到GitHub存储库时自动触发测试。

步骤 6.1：设置对工作区GitHub访问权限

在此子步骤中，将设置一个GitHub Actions工作流，该工作流会在更改合并到存储库中时在工作区中运行作业。 要做到这一点，请向GitHub提供一个用于访问的唯一的Azure Databricks令牌。

出于安全原因，Databricks 不建议将 Azure Databricks 工作区用户的个人访问令牌提供给 GitHub。 相反，Databricks 建议向 GitHub 提供一个与 Microsoft Entra ID 服务主体关联的 Microsoft Entra ID 令牌。 有关说明，请参阅 GitHub Actions 市集中的 运行 Databricks Notebook GitHub Action 页的 Azure 部分。

重要

笔记本使用与令牌关联的标识的所有工作区权限运行，因此 Databricks 建议使用服务主体。 如果确实希望将Azure Databricks工作区用户的个人访问令牌提供给GitHub，仅供个人探索之用，并且你明白，出于安全原因，Databricks不建议这样做，请参阅说明以创建工作区用户的个人访问令牌。

步骤 6.2：添加GitHub Actions工作流

在此子步骤中，每当存储库有拉取请求时，添加GitHub Actions工作流来运行 run_unit_tests 笔记本。

此子步骤将GitHub Actions工作流存储在GitHub存储库中的多个文件夹级别的文件中。 GitHub Actions要求存储库中存在特定的嵌套文件夹层次结构才能正常工作。 若要完成此步骤，您必须访问您的 GitHub 存储库的网站，因为 Azure Databricks Git 文件夹的用户界面无法支持创建嵌套文件夹层次结构。

  1. 在GitHub存储库的网站中，单击Code选项卡。

  2. 单击main旁边的箭头可展开切换分支或标记下拉列表。

  3. 在“查找或创建分支”框中，输入 。

  4. 单击“创建分支: adding_github_actions from 'main'”。

  5. 单击“添加文件”>“创建新文件”。

  6. 对于“为文件命名”，请输入 。

  7. 在编辑器窗口中，输入以下代码。 此代码使用 Run Databricks Notebook GitHub Action 中的pull_request挂钩来运行 run_unit_tests 笔记本。

    在以下代码中，进行以下替换：

    • <your-workspace-instance-URL> 将其与你的 Azure Databricks 实例名称 配合使用。
    • 将 <your-access-token> 替换为前面生成的令牌。
    • <your-cluster-id> 使用目标 经典计算 ID。
    name: Run pre-merge Databricks tests

on:
  pull_request:

env:
  # Replace this value with your workspace instance name.
  DATABRICKS_HOST: https://<your-workspace-instance-name>

jobs:
  unit-test-notebook:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repo
        uses: actions/checkout@v2
      - name: Run test notebook
        uses: databricks/run-notebook@main
        with:
          databricks-token: <your-access-token>

          local-notebook-path: notebooks/run_unit_tests.py

          existing-cluster-id: <your-cluster-id>

          git-commit: '${{ github.event.pull_request.head.sha }}'

          # Grant all users view permission on the notebook's results, so that they can
          # see the result of the notebook, if they have related access permissions.
          access-control-list-json: >
            [
              {
                "group_name": "users",
                "permission_level": "CAN_VIEW"
              }
            ]
          run-name: 'EDA transforms helper module unit tests'

  8. 单击“提交更改”。

  9. 在“提交更改”对话框中，将Create databricks_pull_request_tests.yml 输入到“提交消息”中

  10. 选择“直接提交到 adding_github_actions 分支”，然后单击“提交更改”。

  11. 在“代码”选项卡上，单击“比较并拉取请求”，然后创建拉取请求。

  12. 在合并请求页面上，等待“运行预合并 Databricks 测试 / unit-test-notebook (pull_request)”旁边的图标显示绿色复选标记。 （图标可能需要一些时间才能显示。）如果出现红色 X 而不是绿色复选标记，请单击“详细信息”以找出原因。 如果图标或“详细信息”不再显示，请单击“显示所有检查”。

  13. 如果出现绿色对勾标记，请将合并请求合并到 main 分支。

（可选）步骤 7：更新GitHub中的共享代码以触发测试

在此步骤中，你将对共享代码进行更改，然后将更改推送到GitHub存储库，该存储库会根据上一步中的GitHub操作自动触发测试。

步骤 7.1：在存储库中创建其他工作分支

  1. 在“工作区”浏览器中，打开“best-notebooks”Git 文件夹。
  2. 在文件夹名称旁边，单击“first_tests”Git 分支按钮。
  3. 在“best-notebooks”对话框中，单击“first_tests”分支旁的下拉箭头，然后选择“主”。
  4. 单击“拉取”按钮。 如果提示继续拉取，请点击确认。
  5. 单击 +（创建分支）按钮。
  6. 输入 trigger_tests，然后单击“创建”。 （可为分支提供其他名称。）
  7. 关闭此对话框。

步骤 7.2：更改共享代码

  1. 在“工作区”浏览器的“best-notebooks”Git 文件夹中，单击“covid_analysis/transforms.py”文件。

  2. 更改此文件的第三行：

    # Filter by country code.

    更改为：

    # Filter by country code. If not specified, use "USA."

步骤 7.3：提交更改以触发测试

  1. 在文件名称旁边，单击“trigger_tests”Git 分支按钮。
  2. 在 best-notebooks 对话框中的“更改”选项卡上，确保已选中 covid_analysis/transforms.py。
  3. 对于“提交消息（必填）”，请输入 Updated comment。
  4. 对于说明（可选），请输入This updates the comment for filter_country.
  5. 单击提交和推送。
  6. 单击横幅中“在 git 提供程序上创建拉取请求”的链接，然后在 GitHub 创建拉取请求。
  7. 在合并请求页面上，等待“运行预合并 Databricks 测试 / unit-test-notebook (pull_request)”旁边的图标显示绿色复选标记。 （图标可能需要一些时间才能显示。）如果出现红色 X 而不是绿色复选标记，请单击“详细信息”以找出原因。 如果图标或“详细信息”不再显示，请单击“显示所有检查”。
  8. 如果出现绿色对勾标记，请将合并请求合并到 main 分支。
  • Last updated on