筆記本的軟體工程最佳做法

發行項
05/03/2024

本文提供實際操作逐步解說，示範如何將軟體工程最佳做法套用至 Azure Databricks 筆記本，包括版本控制、程式代碼共享、測試，以及選擇性持續整合和持續傳遞或部署（CI/CD）。

在本逐步解說中，您將能夠：

將筆記本新增至 Azure Databricks Git 資料夾以進行版本控制。
將部分程式碼從其中一個筆記本擷取到可共用的模組中。
測試共用程式碼。
從 Azure Databricks 作業執行筆記本。
選擇性地將持續整合與持續傳遞套用至共用程式碼。

需求

若要完成本逐步解說，您必須提供下列資源：

具有 Databricks 支援的 Git 提供者的遠端存放庫。本文的逐步解說使用 GitHub。本逐步解說假設您有名為 best-notebooks 的 GitHub 存放庫可供使用。（您可以為存放庫提供不同的名稱。如果您這麼做，請將取代 best-notebooks 為整個本逐步解說的存放庫名稱。如果您還沒有 GitHub 存放庫，請建立一個存放庫。

注意

如果您建立新的存放庫，請務必使用至少一個 README 檔案來初始化存放庫，例如檔案。
Azure Databricks 工作區。如果您還沒有工作區，請建立工作區。
工作區中的 Azure Databricks 所有用途叢集。若要在設計階段執行筆記本，您可以將筆記本附加至執行中的所有用途叢集。稍後，本逐步解說會使用 Azure Databricks 作業來自動執行此叢集上的筆記本。（您也可以在只存在於作業存留期的作業叢集上執行作業。如果您還沒有一個叢集，請建立一個用途的叢集。

步驟 1：設定 Databricks Git 資料夾

在此步驟中，您會將現有的 GitHub 存放庫聯機到現有 Azure Databricks 工作區中的 Azure Databricks Git 資料夾。

若要讓您的工作區連線到 GitHub 存放庫，如果您尚未這麼做，您必須先提供您的工作區與 GitHub 認證。

步驟 1.1：提供 GitHub 認證

按兩下右上方的使用者名稱，然後按下拉式清單中的 [設定]。
在設定提要字段中，按兩下 [使用者] 底下的 [鏈接帳戶]。
在 [Git 整合] 底下，針對 [Git 提供者]，選取 [GitHub]。
按兩下 [ 個人存取令牌]。
針對 Git 提供者使用者名稱或電子郵件，輸入您的 GitHub 用戶名稱。
針對 [令牌]，輸入您的 GitHub 個人存取令牌（傳統版）。此個人存取令牌（傳統）必須具有 存放庫 和 工作流程 許可權。
按一下 [檔案] 。

步驟 1.2：連線至 GitHub 存放庫

在工作區提要欄位中，按兩下 [ 工作區]。
在 [ 工作區 ] 瀏覽器中，展開 [工作區 > 使用者]。
以滑鼠右鍵按下您的使用者名稱資料夾，然後按兩下 [ 建立 > Git 資料夾]。
在 [ 建立 Git 資料夾] 對話框中：
1. 針對 Git 存放庫 URL，輸入 GitHub Clone with HTTPS URL for your GitHub 存放庫。本文假設您的 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 。若是如此，請在本逐步解說中以取代 mainmaster 。

提示

如果您不熟悉在 Git 分支中工作，請參閱 Git 網站上的 Git 分支 - 分支。

應該會開啟步驟 1.2 中的 Git 資料夾。如果沒有，請在 [工作區] 提要字段中，依序展開 [工作區>使用者] 和 [用戶名稱] 資料夾，然後按兩下您的 Git 資料夾。
在工作區導覽階層連結下的資料夾名稱旁邊，按兩下主要 Git 分支按鈕。
在 [ 最佳筆記本] 對話框中，按兩下 [ 建立分支 ] 按鈕。

注意

如果您的存放庫具有以外的 best-notebooks名稱，此對話框的標題將會不同，在此和整個逐步解說中。
輸入 eda，然後按兩下 [ 建立]。
關閉此對話框。

步驟 2.2：將筆記本匯入存放庫

在此子步驟中，您會將現有的筆記本從另一個存放庫匯入存放庫。此筆記本會執行下列動作：

將 CSV 檔案從 owid/covid-19-data GitHub 存放庫複製到工作區中的叢集。此 CSV 檔案包含來自世界各地有關 COVID-19 住院和重症監護計量的公用數據。
將 CSV 檔案的內容讀入 pandas DataFrame。
篩選數據，只包含來自美國的計量。
顯示數據的繪圖。
將 pandas DataFrame 儲存為 Spark DataFrame 上的 Pandas API。
在 Spark DataFrame 上的 Pandas API 上執行數據清理。
將 Spark DataFrame 上的 Pandas API 寫入為工作區中的 Delta 數據表。
顯示 Delta 數據表的內容。

雖然您可以在這裡的存放庫中建立自己的筆記本，但匯入現有的筆記本有助於加快本逐步解說的速度。若要在此分支中建立筆記本，或將現有的筆記本移至此分支，而不是匯入筆記本，請參閱工作區檔案基本用法。

從最佳筆記本 Git 資料夾，按兩下 [建立>資料夾]。
在 [ 新增資料夾] 對話框中，輸入 notebooks，然後按兩下 [ 建立]。
從 Notebooks 資料夾中，按兩下 kebab，然後按兩下 [匯入]。
在 [ 匯入 ] 對話框中：
1. 針對 [ 匯入的來源]，選取 [ URL]。
2. 在 GitHub 的databricks/notebook-best-practices存放庫中輸入筆記本原始內容的 covid_eda_raw URL。若要取得此 URL：i. 移至 https://github.com/databricks/notebook-best-practices。 ii. notebooks按兩下資料夾。 iii. 按兩下檔案 covid_eda_raw.py 。 iv. 按兩下 [ 原始]。 v. 將網頁瀏覽器網址列的完整 URL 複製到 [ 匯入] 對話方塊。
  
  注意
  
  [ 匯入] 對話框僅適用於公用存放庫的 Git URL。
3. 按一下 [匯入]。

步驟 2.3：執行筆記本

如果筆記本尚未顯示，請開啟 Notebooks 資料夾，然後按兩下 資料夾內的covid_eda_raw 筆記本。
選取要附加此筆記本的叢集。如需建立叢集的指示，請參閱建立叢集。
按兩下 [ 全部執行]。
等候筆記本執行。

筆記本執行完成之後，您應該會在筆記本中看到數據繪圖，以及 Delta 數據表中超過 600 個原始數據列。如果您開始執行此筆記本時尚未執行叢集，叢集可能需要幾分鐘的時間才能啟動，才能顯示結果。

步驟 2.4：簽入並合併筆記本

在此子步驟中，到目前為止，您會將工作儲存到 GitHub 存放庫。接著，您會將筆記本從工作分支合併到存放庫的 main 分支。

在筆記本的名稱旁邊，按兩下 eda Git 分支按鈕。
在 [ 最佳筆記本] 對話框中的 [變更 ] 索引標籤上，確定 已選取筆記本/covid_eda_raw.py 檔案。
針對 [ 認可訊息（必要]，輸入 Added raw notebook。
針對 [描述] （選擇性），輸入 This is the first version of the notebook.
按兩下 [ 認可與推送]。
按兩下橫幅中在 Git 提供者上建立提取要求中的提取要求連結。
在 GitHub 中建立提取要求，然後將提取要求合併至 main 分支。
回到您的 Azure Databricks 工作區，如果仍然顯示，請關閉 [最佳筆記本] 對話方塊。

步驟 3：將程式代碼移至共享模組

在此步驟中，您會將筆記本中的部分程式代碼移至筆記本外部的一組共用函式。這可讓您搭配其他類似的筆記本使用這些函式，以加速未來的程式代碼撰寫，並協助確保更可預測且一致的筆記本結果。共用此程式代碼也可讓您更輕鬆地測試這些函式，因為軟體工程最佳做法可以提升程式代碼的整體品質。

步驟 3.1：在存放庫中建立另一個工作分支

在筆記本的名稱旁邊，按兩下 eda Git 分支按鈕。
在 [最佳筆記本] 對話框中，按兩下 eda 分支旁的下拉式箭號，然後選取main。
按兩下 [ 提取] 按鈕。如果系統提示您繼續提取，請按兩下 [ 確認]。
按兩下 [ 建立分支] 按鈕。
輸入 first_modules，然後按兩下 [ 建立]。（您可以為分支提供不同的名稱。
關閉此對話框。

步驟 3.2：將筆記本匯入存放庫

若要加速本逐步解說，在此子步驟中，您會將另一個現有的筆記本匯入存放庫。此筆記本會執行與上一個筆記本相同的動作，但此筆記本會呼叫儲存在筆記本外部的共用程式代碼函式。同樣地，您可以在存放庫中建立自己的筆記本，並自行執行實際的程式代碼共用。

從 [ 工作區 ] 瀏覽器，以滑鼠右鍵按下 Notebooks 資料夾，然後按兩下 [ 匯入]。
在 [ 匯入 ] 對話框中：
1. 針對 [ 匯入的來源]，選取 [ URL]。
2. 在 GitHub 的databricks/notebook-best-practices存放庫中輸入筆記本原始內容的 covid_eda_modular URL。若要取得此 URL：i. 移至 https://github.com/databricks/notebook-best-practices。 ii. notebooks按兩下資料夾。 iii. 按兩下檔案 covid_eda_modular.py 。 iv. 按兩下 [ 原始]。 v. 將網頁瀏覽器網址列的完整 URL 複製到 [ 匯入筆記本 ] 對話方塊。
  
  注意
  
  [ 匯入筆記本] 對話框僅適用於公用存放庫的 Git URL。
3. 按一下 [匯入]。

步驟 3.3：新增筆記本支援的共用程式代碼函式

從 [ 工作區 ] 瀏覽器，以滑鼠右鍵按兩下 最佳筆記本 Git 資料夾，然後按兩下 [ 建立 > 資料夾]。
在 [ 新增資料夾] 對話框中，輸入 covid_analysis，然後按兩下 [ 建立]。
從 [covid_analysis] 資料夾中，按兩下 [建立>檔案]。
在 [ 新增檔名] 對話框中，輸入 transforms.py，然後按兩下 [ 建立檔案]。

在 [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 套件相依性，可讓程式代碼正常執行。在此子步驟中，您會宣告這些套件相依性。宣告相依性可藉由使用精確定義的連結庫版本來改善重現性。

從 [ 工作區 ] 瀏覽器，以滑鼠右鍵按兩下 最佳筆記本 Git 資料夾，然後按兩下 [ 建立 > 檔案]。

注意

您想要列出套件相依性的檔案進入 Git 資料夾的根目錄，而不是 移至筆記本 或 covid_analysis 資料夾。
在 [ 新增檔名] 對話框中，輸入 requirements.txt，然後按兩下 [ 建立檔案]。
在 [requirements.txt 編輯器] 視窗中，輸入下列程式代碼：

注意

如果看不到檔案 requirements.txt ，您可能需要重新整理網頁瀏覽器。
```
-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 運行時間版本的一節。

您的存放庫結構現在看起來應該像這樣：

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

步驟 3.5：執行重構的筆記本

在此子步驟中 covid_eda_modular ，您會執行 Notebook，其會在中 covid_analysis/transforms.py呼叫共用程式代碼。

從 [工作區] 瀏覽器中，按下 notebooks 資料夾內的covid_eda_modular筆記本。
選取要附加此筆記本的叢集。
按兩下 [ 全部執行]。
等候筆記本執行。

筆記本執行完成之後，您應該會在筆記本中看到類似的結果 covid_eda_raw ：數據繪圖，以及 Delta 數據表中超過 600 個原始數據列。此筆記本的主要差異在於使用不同的篩選條件（iso_codeDZA而非 USA）。如果您開始執行此筆記本時尚未執行叢集，叢集可能需要幾分鐘的時間才能啟動，才能顯示結果。

按兩下筆記本名稱 旁的 [first_modules Git 分支] 按鈕。
在 [ 最佳筆記本] 對話框中的 [變更 ] 索引標籤上，確定已選取下列專案：
- requirements.txt
- covid_analysis/transforms.py
- notebooks/covid_eda_modular.py
針對 [ 認可訊息（必要]，輸入 Added refactored notebook。
針對 [描述] （選擇性），輸入 This is the second version of the notebook.
按兩下 [ 認可與推送]。
按兩下橫幅中在 Git 提供者上建立提取要求中的提取要求連結。
在 GitHub 中建立提取要求，然後將提取要求合併至 main 分支。
回到您的 Azure Databricks 工作區，如果仍然顯示，請關閉 [最佳筆記本] 對話方塊。

步驟 4：測試共用程序代碼

在此步驟中，您會測試上一個步驟中的共享程序代碼。不過，您想要在不執行 covid_eda_modular 筆記本本身的情況下測試此程序代碼。這是因為如果共用程式代碼無法執行，筆記本本身也可能無法執行。您想要先攔截共用程式代碼中的失敗，再讓主要筆記本稍後失敗。此測試技術是軟體工程最佳做法。

提示

如需筆記本測試的其他方法，以及 R 和 Scala 筆記本的測試，請參閱筆記本的單元測試。

步驟 4.1：在存放庫中建立另一個工作分支

按兩下筆記本名稱 旁的 [first_modules Git 分支] 按鈕。
在 [最佳筆記本] 對話框中，按兩下first_modules分支旁的下拉式箭號，然後選取main。
按兩下 [ 提取] 按鈕。如果系統提示您繼續提取，請按兩下 [ 確認]。
按兩下 [ 建立分支]。
輸入 first_tests，然後按兩下 [ 建立]。（您可以為分支提供不同的名稱。
關閉此對話框。

步驟 4.2：新增測試

在此子步驟中，您會使用 pytest 架構來測試您的共享程式碼。在這些測試中，您會判斷是否要達到特定的測試結果。如果有任何測試產生非預期的結果，該特定測試會失敗判斷提示，因此測試本身會失敗。

從 [ 工作區 ] 瀏覽器，以滑鼠右鍵按下您的 Git 資料夾，然後按兩下 [ 建立 > 資料夾]。
在 [ 新增資料夾] 對話框中，輸入 tests，然後按兩下 [ 建立]。
從 [測試] 資料夾，按兩下 [建立>檔案]。
在 [ 新增檔名] 對話框中，輸入 testdata.csv，然後按兩下 [ 建立檔案]。

在 [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

從 [測試] 資料夾，按兩下 [建立>檔案]。
在 [ 新增檔名] 對話框中，輸入 transforms_test.py，然後按兩下 [ 建立檔案]。

在 [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 套件下載並安裝到您的工作區、執行測試，以及報告測試的結果。雖然您可以從叢集的 Web 終端機執行pytest，但從筆記本執行pytest可能會更方便。

注意

執行 pytest 會執行名稱遵循表單 test_*.py 或 /*_test.py 目前目錄中及其子目錄中的所有檔案。

從 [ 工作區 ] 瀏覽器，以滑鼠右鍵按下 Notebooks 資料夾，然後按兩下 [ 匯入]。
在 [ 匯入筆記本] 對話框中：
1. 針對 [ 匯入的來源]，選取 [ URL]。
2. 在 GitHub 的databricks/notebook-best-practices存放庫中輸入筆記本原始內容的 run_unit_tests URL。若要取得此 URL：i. 移至 https://github.com/databricks/notebook-best-practices。 ii. notebooks按兩下資料夾。 iii. 按兩下檔案 run_unit_tests.py 。 iv. 按兩下 [ 原始]。 v. 將網頁瀏覽器網址列的完整 URL 複製到 [ 匯入筆記本 ] 對話方塊。
  
  注意
  
  [ 匯入筆記本] 對話框僅適用於公用存放庫的 Git URL。
3. 按一下 [匯入]。
選取要附加此筆記本的叢集。
按兩下 [ 全部執行]。
等候筆記本執行。

筆記本執行完成之後，您應該會在筆記本中看到通過和失敗測試數目的相關信息，以及其他相關詳細數據。如果您開始執行此筆記本時尚未執行叢集，叢集可能需要幾分鐘的時間才能啟動，才能顯示結果。

您的存放庫結構現在看起來應該像這樣：

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

在筆記本的名稱旁邊，按兩下 [first_tests Git 分支] 按鈕。
在 [ 最佳筆記本] 對話框中的 [變更 ] 索引標籤上，確定已選取下列專案：
- tests/transforms_test.py
- notebooks/run_unit_tests.py
- tests/testdata.csv
針對 [ 認可訊息（必要]，輸入 Added tests。
針對 [描述] [選擇性]，輸入 These are the unit tests for the shared code.。
按兩下 [ 認可與推送]。
按兩下橫幅中在 Git 提供者上建立提取要求中的提取要求連結。
在 GitHub 中建立提取要求，然後將提取要求合併至 main 分支。
回到您的 Azure Databricks 工作區，如果仍然顯示，請關閉 [最佳筆記本] 對話方塊。

步驟 5：建立作業以執行筆記本

在先前的步驟中，您已手動測試共用程序代碼，並手動執行筆記本。在此步驟中，您會使用 Azure Databricks 作業來測試您的共享程式代碼，並視需要或定期排程自動執行筆記本。

步驟 5.1：建立作業工作以執行測試筆記本

在工作區提要欄位中，按兩下 [ 工作流程]。
在 [作業] 索引標籤上，按兩下 [建立作業]。
編輯要為 covid_report的作業名稱。
針對 [ 工作名稱]，輸入 run_notebook_tests。
針對 [ 類型]，選取 [筆記本]。
針對 [ 來源]，選取 [Git 提供者]。
按兩下 [ 新增 Git 參考]。
在 [ Git 資訊] 對話框中：
1. 針對 Git 存放庫 URL，輸入 GitHub Clone with HTTPS URL for your GitHub 存放庫。本文假設您的 URL 結尾為 best-notebooks.git，例如 https://github.com/<your-GitHub-username>/best-notebooks.git。
2. 針對 [Git 提供者]，選取 [GitHub]。
3. 針對 Git 參考（分支/標記/認可），輸入 main。
4. 選取 [Git 參考] 旁的 [分支/標籤/認可]，選取分支。
5. 按一下 [確認]。
針對 [路徑]，輸入 notebooks/run_unit_tests。請勿新增 .py 擴展名。
針對 [ 叢集]，從上一個步驟中選取叢集。
按兩下 [ 建立工作]。

注意

在此案例中，Databricks 不建議您使用筆記本中的 [排程] 按鈕，如建立和管理排程的筆記本作業中所述，以排程作業以定期執行此筆記本。這是因為排程按鈕會使用工作區存放庫中筆記本的最新工作複本來建立作業。相反地，Databricks 建議您遵循上述指示來建立作業，以使用存放庫中最新 認可的 筆記本版本。

步驟 5.2：建立作業工作以執行主筆記本

按兩下 [ + 新增工作 ] 圖示。
彈出視窗隨即出現。選取 [筆記本]。
針對 [ 工作名稱]，輸入 run_main_notebook。
針對 [ 類型]，選取 [筆記本]。
針對 [路徑]，輸入 notebooks/covid_eda_modular。請勿新增 .py 擴展名。
針對 [ 叢集]，從上一個步驟中選取叢集。
確認 [相依 於值] 為 run_notebook-tests。
按兩下 [ 建立工作]。

步驟 5.3 執行作業

按兩下 [ 立即執行]。
在彈出視窗中，按兩下 [ 檢視執行]。
注意

如果快顯消失得太快，請執行下列動作：
1. 在資料科學與工程或 Databricks 機器學習 環境中的提要欄位上，按兩下 [工作流程]。
2. 在 [作業執行] 索引標籤上，按兩下 [作業] 資料行中具有covid_report最新作業的 [開始時間] 值。
若要查看作業結果，請按兩下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（先前稱為 Azure Active Directory）令牌。如需指示，請參閱 GitHub Actions Marketplace 中執行 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 資料夾使用者介面不支援建立巢狀資料夾階層。

在 GitHub 存放庫的網站中，按兩下 [ 程序代碼 ] 索引標籤。
按兩下main旁的箭號，展開 [切換分支] 或 [卷標] 下拉式清單。
在 [ 尋找或建立分支] 方塊 中，輸入 adding_github_actions。
按兩下 [ 建立分支]：從 [main] adding_github_actions。
按兩下 [ 新增檔案 > ] [建立新檔案]。
針對 [ 為檔案命名]，輸入 .github/workflows/databricks_pull_request_tests.yml。

在編輯器視窗中，輸入下列程序代碼。此程式代碼會使用執行 Databricks Notebook GitHub Action 中的pull_request勾點來執行run_unit_tests筆記本。

在下列程式碼中，進行下列取代：

<your-workspace-instance-URL> 使用您的 Azure Databricks 實例名稱。
<your-access-token> 使用您稍早產生的令牌。
<your-cluster-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"

按兩下 [ 認可變更]。
在 [ 認可變更 ] 對話框中，輸入 Create databricks_pull_request_tests.yml 認可訊息
選取 [直接認可至adding_github_actions分支 ]，然後按兩下 [ 認可變更]。
在 [ 程序代碼] 索引標籤上，按兩下 [比較和提取要求]，然後建立提取要求。
在提取要求頁面上，等候 [執行預先合併的 Databricks 測試/ unit-test-notebook （pull_request）旁的圖示顯示綠色複選標記。（可能需要一些時間，圖示才會出現。如果有紅色 X 而非綠色複選標記，請按兩下 [ 詳細數據 ] 以找出原因。如果圖示或詳細數據不再顯示，請按兩下 [ 顯示所有檢查]。
如果出現綠色複選標記，請將提取要求合併至 main 分支。

（選擇性）步驟 7：更新 GitHub 中的共用程式代碼以觸發測試

在此步驟中，您會變更共用程式碼，然後將變更推送至 GitHub 存放庫，這會根據上一個步驟中的 GitHub Action 自動觸發測試。

步驟 7.1：在存放庫中建立另一個工作分支

從 [ 工作區 ] 瀏覽器，開啟 最佳筆記本 Git 資料夾。
按兩下資料夾名稱 旁的 [first_tests Git 分支] 按鈕。
在 [最佳筆記本] 對話框中，按兩下 first_tests 分支旁的下拉式箭號，然後選取main。
按兩下 [ 提取] 按鈕。如果系統提示您繼續提取，請按兩下 [ 確認]。
+ 按兩下 [建立分支] 按鈕。
輸入 trigger_tests，然後按兩下 [ 建立]。（您可以為分支提供不同的名稱。
關閉此對話框。

步驟 7.2：變更共享程式碼

從 [ 工作區 ] 瀏覽器的 [最佳筆記本 Git] 資料夾中，按兩下 covid_analysis/transforms.py 檔案。

變更此檔案的第三行：

# Filter by country code.

對此：

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

步驟 7.3：簽入變更以觸發測試

在檔名旁邊，按兩下 [trigger_tests Git 分支] 按鈕。
在 [最佳筆記本] 對話框中的 [變更] 索引標籤上，確定已選取 [covid_analysis/transforms.py]。
針對 [ 認可訊息（必要]，輸入 Updated comment。
針對 [描述] （選擇性），輸入 This updates the comment for filter_country.
按兩下 [ 認可與推送]。
按兩下橫幅中 在 Git 提供者 上建立提取要求中的提取要求連結，然後在 GitHub 中建立提取要求。
在提取要求頁面上，等候 [執行預先合併的 Databricks 測試/ unit-test-notebook （pull_request）旁的圖示顯示綠色複選標記。（可能需要一些時間，圖示才會出現。如果有紅色 X 而非綠色複選標記，請按兩下 [ 詳細數據 ] 以找出原因。如果圖示或詳細數據不再顯示，請按兩下 [ 顯示所有檢查]。
如果出現綠色複選標記，請將提取要求合併至 main 分支。

筆記本的軟體工程最佳做法

需求

步驟 1：設定 Databricks Git 資料夾

步驟 1.1：提供 GitHub 認證

步驟 1.2：連線至 GitHub 存放庫

步驟 2：匯入並執行筆記本

步驟 2.1：在存放庫中建立工作分支

步驟 2.2：將筆記本匯入存放庫

步驟 2.3：執行筆記本

步驟 2.4：簽入並合併筆記本

步驟 3：將程式代碼移至共享模組

步驟 3.1：在存放庫中建立另一個工作分支

步驟 3.2：將筆記本匯入存放庫

步驟 3.3：新增筆記本支援的共用程式代碼函式

步驟 3.4：新增共用程式代碼的相依性

步驟 3.5：執行重構的筆記本

步驟 4：測試共用程序代碼

步驟 4.1：在存放庫中建立另一個工作分支

步驟 4.2：新增測試

步驟 4.3：執行測試

步驟 5：建立作業以執行筆記本

步驟 5.1：建立作業工作以執行測試筆記本

步驟 5.2：建立作業工作以執行主筆記本

步驟 5.3 執行作業

（選擇性）步驟 6：設定存放庫以測試程式代碼，並在程式碼變更時自動執行筆記本

步驟 6.1：設定工作區的 GitHub 存取權

步驟 6.2：新增 GitHub Actions 工作流程

（選擇性）步驟 7：更新 GitHub 中的共用程式代碼以觸發測試

步驟 7.1：在存放庫中建立另一個工作分支

步驟 7.2：變更共享程式碼

步驟 7.3：簽入變更以觸發測試

意見反應

意見反應

其他資源

筆記本的軟體工程最佳做法

需求

步驟 1：設定 Databricks Git 資料夾

步驟 1.1：提供 GitHub 認證

步驟 1.2：連線 至 GitHub 存放庫

步驟 2：匯入並執行筆記本

步驟 2.1：在存放庫中建立工作分支

步驟 2.2：將筆記本匯入存放庫

步驟 2.3：執行筆記本

步驟 2.4：簽入並合併筆記本

步驟 3：將程式代碼移至共享模組

步驟 3.1：在存放庫中建立另一個工作分支

步驟 3.2：將筆記本匯入存放庫

步驟 3.3：新增筆記本支援的共用程式代碼函式

步驟 3.4：新增共用程式代碼的相依性

步驟 3.5：執行重構的筆記本

步驟 3.6：簽入筆記本及其相關程序代碼

步驟 4：測試共用程序代碼

步驟 4.1：在存放庫中建立另一個工作分支

步驟 4.2：新增測試

步驟 4.3：執行測試

步驟 4.4：簽入筆記本和相關測試

步驟 5：建立作業以執行筆記本

步驟 5.1：建立作業工作以執行測試筆記本

步驟 5.2：建立作業工作以執行主筆記本

步驟 5.3 執行作業

（選擇性）步驟 6：設定存放庫以測試程式代碼，並在程式碼變更時自動執行筆記本

步驟 6.1：設定工作區的 GitHub 存取權

步驟 6.2：新增 GitHub Actions 工作流程

（選擇性）步驟 7：更新 GitHub 中的共用程式代碼以觸發測試

步驟 7.1：在存放庫中建立另一個工作分支

步驟 7.2：變更共享程式碼

步驟 7.3：簽入變更以觸發測試

意見反應

意見反應

其他資源

步驟 1.2：連線至 GitHub 存放庫