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

發行項
10/11/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 存放庫的 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 分支 - 分支概論。

隨即應該會開啟步驟 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 上的 Pandas API DataFrame。
在 Spark 上的 Pandas API DataFrame 上執行資料清理。
將 Spark 上的 Pandas API DataFrame 寫入為工作區中的 Delta 資料表。
顯示 Delta 資料表的內容。

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

從 [最佳筆記本] Git 資料夾，按下 [建立] > [資料夾]。
在 [新增資料夾] 對話方塊中，輸入 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：執行筆記本

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

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

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

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

在筆記本的名稱旁邊，按下 "eda" Git 分支按鈕。
在 [最佳筆記本] 對話方塊中的 [變更] 索引標籤上，確定已選取 "notebooks/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" 分支旁邊的下拉式箭頭，然後選取 [主要]。
按下 [提取] 按鈕。如果提示繼續提取，則按下 [確認]。
按下 [建立分支] 按鈕。
輸入 first_modules，然後按下 [建立]。 (您可以為分支指定不同的名稱。)
關閉此對話方塊。

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

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

從 [工作區] 瀏覽器，以滑鼠右鍵按一下 [筆記本] 資料夾，然後按下 [匯入]。
在 [匯入] 對話方塊中：
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 複製到 [匯入 Notebooks] 對話方塊。
  
  注意
  
  [匯入 Notebooks] 對話方塊僅適用於公用存放庫的 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 Runtime 版本的「系統環境」一節。

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

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

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

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

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

筆記本執行完成之後，您應該會在筆記本中看到與 covid_eda_raw 筆記本類似的結果：資料繪圖，以及 Delta 資料表中超過 600 個資料列的未經處理資料。此筆記本的主要差異在於使用了不同的篩選條件 (即 DZA 的 iso_code 而非 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" 分支旁邊的下拉式箭頭，然後選取 [主要]。
按下 [提取] 按鈕。如果提示繼續提取，則按下 [確認]。
按下 [建立分支]。
輸入 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 封裝並將其安裝到您的工作區，執行測試，以及報告測試的結果。雖然您可以從叢集的網路終端機執行 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 複製到 [匯入 Notebooks] 對話方塊。
  
  注意
  
  [匯入 Notebooks] 對話方塊僅適用於公用存放庫的 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 存放庫的 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. 按一下 [確認]。
針對 [路徑]，輸入 notebooks/run_unit_tests。請勿新增 .py 檔案副檔名。
針對 [叢集]，選取上一個步驟中的叢集。
按一下 [建立工作]。

注意

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

步驟 5.2：建立工作任務以執行主要筆記本

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

步驟 5.3 執行工作

按下 [立即執行]。
在快顯中，按下 [檢視執行]。
注意

如果快顯消失得太快，請執行下列動作：
1. 在 [資料科學與工程] 或 "Databricks Mosaic AI" 環境的側邊欄上，按下 [工作流程]。
2. 在 [工作執行] 索引標籤上，按下 [工作] 資料行中具有 covid_report 的最新工作的 [開始時間] 值。
若要查看工作結果，請按下 "run_notebook_tests" 磚、"run_main_notebook" 磚，或兩者。每個磚上的結果都與您自己逐一執行筆記本的一樣。

注意

此工作會隨選執行。若要將此工作設定為定期執行，請參閱 Databricks 工作的觸發程序類型。

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

在上一個步驟中，您使用了工作來自動測試您的共用程式碼，並在某個時間點或週期性地執行筆記本。不過，您可能偏好在變更合併至 GitHub 存放庫時使用 CI/CD 工具 (例如 GitHub Actions) 來自動觸發測試。

步驟 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 資料夾使用者介面不支援建立巢狀資料夾階層。

在 GitHub 存放庫的網站中，按下 [程式碼] 索引標籤。
按下 [主要] 旁邊的箭頭，展開 [切換分支或標籤] 下拉式清單。
在 [尋找或建立分支] 方塊中，輸入 adding_github_actions。
按下 [從「主要」建立分支：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" 分支旁邊的下拉式箭頭，然後選取 [主要]。
按下 [提取] 按鈕。如果提示繼續提取，則按下 [確認]。
按下 + ([建立分支]) 按鈕。
輸入 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：簽入變更以觸發測試

意見反應

其他資源