ノートブックのソフトウェアエンジニアリングのベストプラクティス

この記事では、バージョン管理、コード共有、テスト、必要に応じて継続的インテグレーションと継続的デリバリーまたはデプロイ (CI/CD) など、Azure Databricks ノートブックにソフトウェアエンジニアリングのベストプラクティスを適用する方法を示す実践的なチュートリアルを提供します。

このチュートリアルでは、次の操作を行います。

バージョン管理用の Git フォルダー Azure Databricksにノートブックを追加します。
いずれかのノートブックから共有可能なモジュールにコードの一部を抽出します。
共有コードをテストします。
Azure Databricks ジョブからノートブックを実行します。
必要に応じて、CI/CD を共有コードに適用します。

必要条件

このチュートリアルを完了するには、以下のリソースを提供する必要があります。

Databricks でサポートされている Git プロバイダーを使用したリモートリポジトリ。この記事のチュートリアルでは、GitHubを使用します。このチュートリアルでは、best-notebooks という名前のGitHub リポジトリが使用可能であることを前提としています。 (リポジトリに別の名前を付けることができます。その場合は、このチュートリアル全体best-notebooksをリポジトリの名前に置き換えます)。まだGitHubリポジトリがない場合はを作成します。

注意

新しいリポジトリを作成する場合は、少なくとも 1 つのファイル (README ファイルなど) を使用してリポジトリを初期化してください。
Azure Databricksのワークスペース。ワークスペースがまだない場合は、ワークスペースを作成します。
ワークスペース内のAzure Databricks 汎用クラスター。設計フェーズでノートブックを実行するには、実行中の汎用クラスターにノートブックをアタッチします。このチュートリアルでは、後で Azure Databricks job を使用して、このクラスターでのノートブックの実行を自動化します。 (ジョブの有効期間のみ存在するジョブクラスターでジョブを実行することもできます)。汎用クラスターがまだない場合は作成します。

手順 1: Databricks Git フォルダーを設定する

この手順では、既存の GitHub リポジトリを、既存の Azure Databricks ワークスペース内の Git フォルダーにある Azure Databricks に接続します。

ワークスペースが GitHub リポジトリに接続できるようにするには、まず、GitHub資格情報をワークスペースに提供する必要があります (まだ行っていない場合)。

手順 1.1: GitHub資格情報を指定する

ワークスペースの右上にあるユーザー名をクリックし、ドロップダウンリストの [設定] をクリックします。
[設定] サイドバーの [ユーザー] にある [リンクされたアカウント] をクリックします。
Git integration で、Git provider で、GitHub を選択します。
[個人用アクセストークン] をクリックします。
Git プロバイダーのユーザー名または電子メールに、GitHubユーザー名を入力します。
Tokenで、GitHub個人用アクセストークン (クラシック) を入力します。この個人用アクセストークン (クラシック) には、 リポジトリとワークフローのアクセス許可が必要です。
[保存] をクリックします。

手順 1.2: GitHub リポジトリに接続する

ワークスペースサイドバーにある [ワークスペース] をクリックします。
ワークスペース ブラウザーで [ワークスペース] > [ユーザー] を展開します。
ユーザー名フォルダーを右クリックし、[作成] > [Git フォルダー] をクリックします。
[Git フォルダーの作成] ダイアログで次の手順を実行します。
1. Git リポジトリの URL に、GitHub リポジトリの GitHub Clone と HTTPS URL を入力します。この記事では、URL の末尾が best-notebooks.git (例: https://github.com/<your-GitHub-username>/best-notebooks.git) であることを前提としています。
2. Git provider で、GitHub を選択します。
3. [Git フォルダー名] をお使いのリポジトリの名前に設定したままにします (例: best-notebooks)。
4. [Git フォルダーの作成] をクリックします。

手順 2: ノートブックをインポートして実行する

この手順では、既存の外部ノートブックをお使いのリポジトリにインポートします。このチュートリアル用に独自のノートブックを作成できますが、迅速に進めるために、ここでは指定のノートブックを使用します。

手順 2.1: リポジトリに作業ブランチを作成する

このサブステップでは、お使いのリポジトリに eda という名前のブランチを作成します。このブランチを使用すると、リポジトリの main ブランチとは別にファイルとコードを操作できます。これはソフトウェアエンジニアリングのベストプラクティスです。 (ブランチに別の名前を付けることができます。)

注意

一部のリポジトリでは、main ブランチに master という名前を代わりに付けることがあります。その場合は、このチュートリアル全体を通して main を master に置き換えてください。

ヒント

Git ブランチでの作業に慣れていない場合は、Git ウェブサイトのGit ブランチ概要 - 基本を参照してください。

手順 1.2 の Git フォルダーが開くはずです。そうでない場合は、[ワークスペース] サイドバーにある [ワークスペース] > [ユーザー] を展開し、ユーザー名フォルダーを展開して、Git フォルダーをクリックします。
ワークスペースナビゲーション階層リンクでフォルダー名の横にある main Git ブランチボタンをクリックします。
[best-notebooks] ダイアログで [ブランチの作成] ボタンをクリックします。

注意

リポジトリに best-notebooks 以外の名前がある場合、このダイアログのタイトルは、このチュートリアル全体で異なります。
「eda」と入力し、[作成] をクリックします。
このダイアログを閉じます。

手順 2.2: ノートブックをリポジトリにインポートする

このサブステップでは、別のリポジトリからお使いのリポジトリに既存のノートブックをインポートします。このノートブックでは、以下の処理が行われます。

owid/covid-19-data GitHub リポジトリからワークスペース内のクラスターに CSV ファイルをコピーします。この CSV ファイルには、世界中の COVID-19 の入院患者数と集中治療者数のメトリックに関する公開データが含まれています。
CSV ファイルの内容を pandas DataFrame に読み取ります。
データをフィルター処理して、United Statesからのみメトリックを含める。
データのプロットを表示します。
pandas DataFrame を Pandas API on Spark DataFrame として保存します。
Pandas API on Spark DataFrame でデータクレンジングを実行します。
Pandas API on Spark DataFrame をワークスペース内の Delta テーブルとして書き込みます。
Delta テーブルの内容を表示します。

ここでリポジトリに独自のノートブックを作成することもできますが、代わりに既存のノートブックをインポートすると、このチュートリアルを迅速に進めるのに役立ちます。このブランチでノートブックを作成するか、ノートブックをインポートする代わりに既存のノートブックをこのブランチに移動するには、「ワークスペースファイルの基本的な使用方法」を参照してください。

best-notebooks Git フォルダーから[作成] > [フォルダー] をクリックします。
[新しいフォルダー] ダイアログで「notebooks」と入力し、[作成] をクリックします。
notebooks フォルダーから kebab をクリックし、[インポート] をクリックします。
[ インポート ] ダイアログで、次の操作を行います。
1. [インポート元] で、[URL] を選択します。
2. GitHubの covid_eda_raw リポジトリの databricks/notebook-best-practices ノートブックの生コンテンツの URL を入力します。この URL を取得する方法は次のとおりです。i. https://github.com/databricks/notebook-best-practices にアクセスします。二. notebooks フォルダーをクリックします。 iii. covid_eda_raw.py ファイルをクリックします。 iv. [Raw] (未加工) をクリックします。 .v Web ブラウザーのアドレスバーから完全な URL を [インポート ] ダイアログにコピーします。
  
  注意
  
  [インポート] ダイアログは、パブリックリポジトリ用の Git URL でのみ機能します。
3. [インポート] をクリックします。

手順 2.3: ノートブックを実行する

ノートブックがまだ表示されていない場合は、notebooks フォルダーを開き、フォルダー内の covid_eda_raw ノートブックをクリックします。
このノートブックをアタッチするクラスターを選びます。クラスターの作成手順については、「クラスターの作成」を参照してください。
[すべて実行] をクリックします。
ノートブックが実行している間待ちます。

ノートブックの実行が完了すると、ノートブックにデータのプロットが表示され、Delta テーブルには 600 行を超える生データが表示されます。このノートブックの実行を開始したときにクラスターがまだ実行されていなかった場合は、クラスターが起動してから結果が表示されるまでに数分かかることがあります。

手順 2.4: ノートブックをチェックインし、マージする

このサブステップでは、これまでの作業を GitHub リポジトリに保存します。次に、作業ブランチからリポジトリの main ブランチにノートブックをマージします。

ノートブックの名前の横にある eda Git ブランチボタンをクリックします。
[best-notebooks] ダイアログの [変更] タブで、notebooks/covid_eda_raw.py ファイルが選択されていることを確認します。
[コミットメッセージ (必須)] に「Added raw notebook」と入力します。
[説明] (省略可能) に、「This is the first version of the notebook.」と入力します。
[コミット & プッシュ] をクリックします。
バナーの [Git プロバイダー上に pull request を作成する] の pull request リンクをクリックします。
GitHubで pull request を作成し、pull request を main ブランチにマージします。
Azure Databricks ワークスペースに戻り、まだ表示されている場合は、best-notebooks ダイアログを閉じます。

手順 3: コードを共有モジュールに移動する

この手順では、ノートブック内のコードの一部を、ノートブックの外部にある 1 組の共有関数に移動します。これにより、これらの関数を他の同様のノートブックと一緒に使用できるため、将来のコーディングを迅速に進め、より予測可能で一貫性のあるノートブックの結果を確保できます。また、このコードの共有により、これらの関数をより簡単にテストすることもできます。これは、ソフトウェアエンジニアリングのベストプラクティスとして、コード全体の品質を向上させることができます。

手順 3.1: リポジトリに別の作業ブランチを作成する

ノートブックの名前の横にある eda Git ブランチボタンをクリックします。
[best-notebooks] ダイアログで、eda ブランチの横にあるドロップダウン矢印をクリックし、[main] を選びます。
[プル] ボタンをクリックします。プルの続行を求めるメッセージが表示されたら、[確認] をクリックします。
[ブランチの作成] ボタンをクリックします。
「first_modules」と入力し、[作成] をクリックします。 (ブランチに別の名前を付けることができます。)
このダイアログを閉じます。

手順 3.2: ノートブックをリポジトリにインポートする

このチュートリアルを迅速に進めるために、このサブステップでは、別の既存のノートブックをリポジトリにインポートします。このノートブックでは、前のノートブックと同じ処理を行います。ただし、このノートブックは、ノートブックの外部に格納されている共有コード関数を呼び出す点を除きます。ここでも、お使いのリポジトリに独自のノートブックを作成し、実際のコード共有を自分で実行することができます。

ワークスペース ブラウザーで notebooks フォルダーを右クリックし、[インポート] をクリックします。
[ インポート ] ダイアログで、次の操作を行います。
1. [インポート元] で、[URL] を選択します。
2. GitHubの covid_eda_modular リポジトリの databricks/notebook-best-practices ノートブックの生コンテンツの URL を入力します。この URL を取得する方法は次のとおりです。i. https://github.com/databricks/notebook-best-practices にアクセスします。二. notebooks フォルダーをクリックします。 iii. covid_eda_modular.py ファイルをクリックします。 iv. [Raw] (未加工) をクリックします。 .v Web ブラウザーのアドレスバーから完全な URL を [ ノートブックのインポート ] ダイアログにコピーします。
  
  注意
  
  [ノートブックのインポート] ダイアログは、パブリックリポジトリ用の Git URL でのみ機能します。
3. [インポート] をクリックします。

手順 3.3: ノートブックのサポートする共有コード関数を追加する

ワークスペース ブラウザーで best-notebooks 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 パッケージの依存関係があります。このサブステップでは、これらのパッケージの依存関係を宣言します。依存関係を宣言すると、正確に定義されたバージョンのライブラリを使用することで再現性が向上します。

ワークスペース ブラウザーで best-notebooks Git フォルダーを右クリックし、[作成] > [ファイル] をクリックします。

注意

パッケージの依存関係を一覧表示するファイルは、 ノートブック や covid_analysis フォルダーではなく、Git フォルダーのルートに移動する必要があります。
[新しいファイル名] ダイアログで、「requirements.txt」と入力し、[ファイルを作成する] をクリックします。
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 ノートブックを実行します。

ワークスペース ブラウザーで notebooks フォルダー内の covid_eda_modular ノートブックをクリックします。
このノートブックをアタッチするクラスターを選びます。
[すべて実行] をクリックします。
ノートブックが実行している間待ちます。

ノートブックの実行が完了すると、ノートブックに covid_eda_raw ノートブックと似た結果が表示されます。つまり、データのプロットが表示され、Delta テーブルには 600 行を超える生データが表示されます。このノートブックとの主な違いは、iso_code の代わりに DZA の USA という別のフィルターが使用されていることです。このノートブックの実行を開始したときにクラスターがまだ実行されていなかった場合は、クラスターが起動してから結果が表示されるまでに数分かかることがあります。

ノートブックの名前の横にある first_modules Git ブランチボタンをクリックします。
[best-notebooks] ダイアログの [変更] タブで、以下が選択されていることを確認します。
- requirements.txt
- covid_analysis/transforms.py
- notebooks/covid_eda_modular.py
[コミットメッセージ (必須)] に「Added refactored notebook」と入力します。
[説明] (省略可能) に、「This is the second version of the notebook.」と入力します。
[コミット & プッシュ] をクリックします。
バナーの [Git プロバイダー上に pull request を作成する] の pull request リンクをクリックします。
GitHubで pull request を作成し、pull request を main ブランチにマージします。
Azure Databricks ワークスペースに戻り、まだ表示されている場合は、best-notebooks ダイアログを閉じます。

手順 4: 共有コードをテストする

この手順では、最後の手順の共有コードをテストします。ただし、covid_eda_modular ノートブック自体を実行せずにこのコードをテストする必要があります。これは、共有コードの実行に失敗した場合、ノートブック自体も実行できない可能性があるためです。メインノートブックが最終的に後で失敗する前に、まず共有コードのエラーをキャッチする必要があります。このテスト手法は、ソフトウェアエンジニアリングのベストプラクティスです。

ヒント

R および Scala ノートブックのテストだけでなく、ノートブックのテストに対するその他のアプローチについては、「ノートブックの単体テスト」をご覧ください。

手順 4.1: リポジトリに別の作業ブランチを作成する

ノートブックの名前の横にある first_modules Git ブランチボタンをクリックします。
[best-notebooks] ダイアログで、first_modules ブランチの横にあるドロップダウン矢印をクリックし、[main] を選びます。
[プル] ボタンをクリックします。プルの続行を求めるメッセージが表示されたら、[確認] をクリックします。
[Create Branch] \(ブランチの作成\) をクリックします。
「first_tests」と入力し、[作成] をクリックします。 (ブランチに別の名前を付けることができます。)
このダイアログを閉じます。

手順 4.2: テストを追加する

このサブステップでは、pytest フレームワークを使用して共有コードをテストします。これらのテストでは、特定のテスト結果が得られるかどうかをアサートします。テストで予期しない結果が生成された場合、その特定のテストはアサーションに失敗するため、テスト自体が失敗します。

ワークスペース ブラウザーで Git フォルダーを右クリックし、[作成] > [フォルダー] をクリックします。
[新しいフォルダー] ダイアログで「tests」と入力し、[作成] をクリックします。
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

tests フォルダーで [作成] > [ファイル] をクリックします。
[新しいファイル名] ダイアログで、「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の run_unit_tests リポジトリの databricks/notebook-best-practices ノートブックの生コンテンツの URL を入力します。この URL を取得する方法は次のとおりです。i. https://github.com/databricks/notebook-best-practices にアクセスします。二. notebooks フォルダーをクリックします。 iii. run_unit_tests.py ファイルをクリックします。 iv. [Raw] (未加工) をクリックします。 .v Web ブラウザーのアドレスバーから完全な 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 ブランチボタンをクリックします。
[best-notebooks] ダイアログの [変更] タブで、以下が選択されていることを確認します。
- tests/transforms_test.py
- notebooks/run_unit_tests.py
- tests/testdata.csv
[コミットメッセージ (必須)] に「Added tests」と入力します。
[説明] (省略可能) に、「These are the unit tests for the shared code.」と入力します。
[コミット & プッシュ] をクリックします。
バナーの [Git プロバイダー上に pull request を作成する] の pull request リンクをクリックします。
GitHubで pull request を作成し、pull request を main ブランチにマージします。
Azure Databricks ワークスペースに戻り、まだ表示されている場合は、best-notebooks ダイアログを閉じます。

手順 5: ノートブックを実行するジョブを作成する

前の手順で、手動で共有コードをテストし、手動でノートブックを実行しました。この手順では、Azure Databricks ジョブを使用して共有コードをテストし、オンデマンドまたは定期的なスケジュールでノートブックを自動的に実行します。

手順 5.1: テストノートブックを実行するジョブタスクを作成する

ワークスペースで、[ワークフロー] アイコンをクリックサイドバーのジョブとパイプライン。
[ 作成]、[ ジョブ] の順にクリックします。
ジョブの名前を「covid_report」に編集します。
[ ノートブック ] タイルをクリックして、最初のタスクを構成します。 [ノートブック] タイルが使用できない場合は、[別のタスクの種類の追加] をクリックしてノートブックを検索します。
[タスク名] に、「run_notebook_tests」と入力します。
必要に応じて、[種類] ドロップダウンメニューから [ノートブック] を選択します。
[ソース] で [Git プロバイダー] を選びます。
[Add a git reference] (Git 参照の追加) をクリックします。
[Git 情報] ダイアログで、以下の手順を実行します。
1. Git リポジトリの URL に、GitHub リポジトリの GitHub Clone と HTTPS URL を入力します。この記事では、URL の末尾が best-notebooks.git (例: https://github.com/<your-GitHub-username>/best-notebooks.git) であることを前提としています。
2. Git provider で、GitHub を選択します。
3. [Git reference (branch / tag / commit)] (Git 参照 (ブランチ/タグ/コミット)) に、「main」と入力します。
4. [Git reference (branch / tag / commit)] (Git 参照 (ブランチ/タグ/コミット)) の横で、[ブランチ] を選択します。
5. [Confirm](確認) をクリックします。
[パス] に、「notebooks/run_unit_tests」と入力します。 .py ファイル拡張子を追加しないでください。
[クラスター] で、前の手順のクラスターを選択します。
[タスクの作成] をクリックします。

注意

このシナリオで、Databricks では、「スケジュールされたノートブックジョブを作成および管理する」で説明されているようにノートブックで [スケジュール] ボタンを使用して、このノートブックを定期的に実行するようにジョブをスケジュールすることをお勧めしません。これは、[スケジュール] ボタンによって、ワークスペースリポジトリ内のノートブックの最新の "作業" コピーを使用してジョブが作成されるためです。代わりに、Databricks では、上記の手順に従って、リポジトリ内で最新の "コミット済み" バージョンのノートブックを使用するジョブを作成することをお勧めします。

手順 5.2: メインノートブックを実行するジョブタスクを作成する

[+ タスクの追加] アイコンをクリックします。
ポップアップメニューが表示されます。 [ノートブック] を選択します。
[タスク名] に、「run_main_notebook」と入力します。
[種類] に、[ノートブック] を選択します。
[パス] に、「notebooks/covid_eda_modular」と入力します。 .py ファイル拡張子を追加しないでください。
[クラスター] で、前の手順のクラスターを選択します。
[依存先] の値が run_notebook-tests であることを確認します。
[タスクの作成] をクリックします。

手順 5.3 ジョブを実行する

[今すぐ実行] をクリックします。
ポップアップで、[実行の表示] をクリックします。
注意

ポップアップの表示時間が短すぎる場合は、次の操作を行います。
1. データサイエンス & エンジニアリングまたは Databricks モザイク AI 環境のサイドバーで、[ジョブとパイプライン] をクリックします。
2. [ジョブの実行] タブの [ジョブ] 列で、covid_report がある最新のジョブの [開始時刻] 値をクリックします。
ジョブの結果を表示するには、run_notebook_tests タイル、run_main_notebook タイル、またはその両方をクリックします。各タイルの結果は、ノートブックを自分で 1 つずつ実行した場合と同じです。

注意

このジョブは要求に応じて実行されました。このジョブを定期的に実行するように設定するには、「スケジュールとトリガーを使用したジョブの自動化」をご覧ください。

(省略可能) 手順 6: コードが変更されるたびに自動的にコードをテストし、ノートブックを実行するようにリポジトリを設定する

前のステップでは、ジョブを使用して共有コードを自動的にテストし、特定の時点や定期的にノートブックを実行しました。ただし、GitHub Actions。

手順 6.1: ワークスペースへのGitHubアクセスを設定する

このサブステップでは、変更がリポジトリにマージされるたびにワークスペースでジョブを実行するGitHub Actions ワークフローを設定します。 GitHubへのアクセスを許可するために、Azure Databricksのユニークなトークンを提供します。

セキュリティ上の理由から、Databricks では、Azure Databricks ワークスペースユーザーの個人用アクセストークンをGitHubに付与することはお勧めしません。代わりに、Databricks では、Microsoft Entra ID サービスプリンシパルに関連付けられている Microsoft Entra ID トークンを GitHub に指定することをお勧めします。手順については、GitHub Actions Marketplace の Run Databricks Notebook GitHub Action ページの Azure セクションを参照してください。

重要

ノートブックは、トークンに関連付けられている ID のすべてのワークスペースアクセス許可で実行されるため、Databricks ではサービスプリンシパルの使用をお勧めします。 Azure Databricksワークスペースユーザーの個人用アクセストークンをGitHubで個人的な探求のために使用する必要があり、セキュリティ上の理由からDatabricksがその行為を推奨しないことを理解している場合は、ワークスペースユーザーの個人用アクセストークンを作成する方法を参照してください。

手順 6.2: GitHub Actions ワークフローを追加する

このサブステップでは、リポジトリへのプル要求が発生するたびに、run_unit_tests ノートブックを実行するGitHub Actions ワークフローを追加します。

このサブステップは、GitHub Actions ワークフローを、GitHub リポジトリ内の複数のフォルダーレベル内に格納されているファイルに格納します。 GitHub Actionsは、適切に動作するために、リポジトリに特定の入れ子になったフォルダー階層が存在する必要があります。この手順を完了するには、GitHub リポジトリの Web サイトを使用する必要があります。これは、Azure Databricks Git フォルダーのユーザーインターフェイスでは、入れ子になったフォルダー階層の作成がサポートされていないためです。

GitHub リポジトリの Web サイトで、Code タブをクリックします。
main の横にある矢印をクリックして、[ブランチまたはタグの切り替え] ドロップダウンリストを展開します。
[Find or create a branch] (ブランチの検索または作成) ボックスに、「adding_github_actions」と入力します。
「main」から「adding_github_actions」へのブランチ作成をクリックします。
[ファイルの追加] > [新しいファイルの作成] をクリックします。
[ファイル名を指定する] に、「.github/workflows/databricks_pull_request_tests.yml」と入力します。

エディターウィンドウで、以下のコードを入力します。このコードでは、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'

[変更をコミットする] をクリックします。
[変更のコミット] ダイアログで Create databricks_pull_request_tests.yml にを入力します
[adding_github_actions ブランチに直接コミットする] を選び、[変更のコミット] をクリックします。
[コード] タブで、[Compare & プルリクエスト] (比較とプルリクエスト) をクリックし、プルリクエストを作成します。
[pull request] ページで、[Run pre-merge Databricks tests / unit-test-notebook (pull_request)] (マージ前の Databricks テスト / 単体テストノートブック (pull_request) の実行) の横にあるアイコンが緑色のチェックマークを表示するまで待ちます。 (アイコンが表示されるまでにしばらく時間がかかる場合があります)。緑色のチェックマークではなく赤い X がある場合は、[詳細] をクリックして理由を確認します。アイコンまたは [詳細] が表示されなくなった場合は、[Show all checks] (すべてのチェックを表示) をクリックします。
緑色のチェックマークが表示されたら、pull request を main ブランチにマージします。

(省略可能)手順 7: GitHubの共有コードを更新してテストをトリガーする

この手順では、共有コードに変更を加え、変更を GitHub リポジトリにプッシュします。これにより、前の手順のGitHubアクションに基づいて、すぐにテストが自動的にトリガーされます。

手順 7.1: リポジトリに別の作業ブランチを作成する

ワークスペース ブラウザーで best-notebooks Git フォルダーを開きます。
フォルダーの名前の横にある [first_tests Git ブランチ] ボタンをクリックします。
[best-notebooks] ダイアログで、first_tests ブランチの横にあるドロップダウン矢印をクリックし、[main] を選びます。
[プル] ボタンをクリックします。プルの続行を求めるメッセージが表示されたら、[確認] をクリックします。
+ ([ブランチの作成]) ボタンをクリックします。
「trigger_tests」と入力し、[作成] をクリックします。 (ブランチに別の名前を付けることができます。)
このダイアログを閉じます。

手順 7.2: 共有コードを変更する

ワークスペース ブラウザーの best-notebooks Git フォルダーで、covid_analysis/transforms.py ファイルをクリックします。
このファイルの 3 行目を変更します。
```
# Filter by country code.
```
この内容を次のように変更します。
```
# Filter by country code. If not specified, use "USA."
```

手順 7.3: 変更をチェックインしてテストをトリガーする

ファイルの名前の横にある [trigger_tests Git ブランチ] ボタンをクリックします。
[best-notebooks] ダイアログの [変更] タブで、covid_analysis/transforms.py が選択されていることを確認します。
[コミットメッセージ (必須)] に「Updated comment」と入力します。
[説明] (省略可能) に、「This updates the comment for filter_country.」と入力します。
[コミット & プッシュ] をクリックします。
バナーの「Git 提供元でプルリクエストを作成」でプルリクエストリンクをクリックして、GitHubでプルリクエストを作成します。
[pull request] ページで、[Run pre-merge Databricks tests / unit-test-notebook (pull_request)] (マージ前の Databricks テスト / 単体テストノートブック (pull_request) の実行) の横にあるアイコンが緑色のチェックマークを表示するまで待ちます。 (アイコンが表示されるまでにしばらく時間がかかる場合があります)。緑色のチェックマークではなく赤い X がある場合は、[詳細] をクリックして理由を確認します。アイコンまたは [詳細] が表示されなくなった場合は、[Show all checks] (すべてのチェックを表示) をクリックします。
緑色のチェックマークが表示されたら、pull request を main ブランチにマージします。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-13

ノートブックのソフトウェア エンジニアリングのベスト プラクティス

必要条件

手順 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: 変更をチェックインしてテストをトリガーする

フィードバック

その他のリソース

ノートブックのソフトウェアエンジニアリングのベストプラクティス

手順 5.1: テストノートブックを実行するジョブタスクを作成する

手順 5.2: メインノートブックを実行するジョブタスクを作成する