ノートブックのソフトウェアエンジニアリングのベストプラクティス
この記事では、バージョン管理、コード共有、テスト、そしてオプションとして継続的インテグレーションと継続的デリバリーまたはデプロイメント(CI/CD)を含む、ソフトウェアエンジニアリングのベストプラクティスをDatabricksノートブックに適用する方法を示す実践的なチュートリアルをご紹介します。
このチュートリアルでは、以下のことを行います。
- バージョン管理のために Databricks Git フォルダーにノートブックを追加します。
- いずれかのノートブックからコードの一部を共有可能なモジュールに抽出します。
- 共有コードをテストします。
- Databricksジョブからノートブックを実行します。
- 必要に応じて、共有コードにCI/CDを適用します。
必要条件
このチュートリアルを完了するには、以下のリソースが必要です。
- Databricks がサポートする Git プロバイダー を含むリモート リポジトリ。 この記事のチュートリアルでは、GitHub を使用します。 このチュートリアルでは、
best-notebooks
という名前の GitHub リポジトリが使用可能であることを前提としています。 (リポジトリに別の名前を付けることができます。 その場合は、このチュートリアル全体でbest-notebooks
をリポジトリの名前に置き換えます。 GitHub リポジトリ をまだ作成していない場合は作成します。
新しいリポジトリを作成する場合は、少なくとも1つのファイル、例えばREADME
ファイルでリポジトリを初期化してください。
-
ワークスペース内の Databricks All-Purposeクラスター 。 設計フェーズでノートブックを実行するには、 実行中の All-Purposeクラスターにノートブックをアタッチします。 後で、このチュートリアルでは Databricks ジョブ を使用して、このクラスタリングでのノートブックの実行を自動化します。 (ジョブの有効期間中のみ存在する ジョブ クラスタリング でジョブを実行することもできます。 All-Purposeクラスターを まだお持ちでない場合は、作成してください。
ステップ 1: Databricks Git フォルダーを設定する
この手順では、既存の GitHub リポジトリを既存の Databricks ワークスペースの Databricks Git フォルダーに接続します。
ワークスペースをGitHubリポジトリに接続できるようにするには、まずワークスペースにGitHubの認証情報を入力する必要があります(まだ行っていない場合)。
ステップ 1.1: GitHub の資格情報を入力する
- ワークスペースの右上にあるユーザー名をクリックし、ドロップダウンリストの [設定 ]をクリックします。
- 「設定 」サイドバーの 「ユーザー 」で、「 リンクされたアカウント 」をクリックします。
- [Git 統合 ] の [ Git プロバイダー ] で [ GitHub ] を選択します。
- [個人用アクセストークン ]をクリックします。
- 「 Gitプロバイダーのユーザー名またはEメールアドレス 」に、GitHubユーザー名を入力します。
- 「 トークン 」にGitHubパーソナルアクセストークン(クラシック)を入力します。このパーソナルアクセストークン(クラシック)には、 リポジトリ と ワークフロー の権限が必要です。
- [ 保存 ]をクリックします。
ステップ 1.2: GitHub リポジトリに接続する
- ワークスペースのサイドバーで、[ ワークスペース ] をクリックします。
- ワークスペース ブラウザで、「 ワークスペース」>「ユーザー 」を展開します。
- ユーザー名フォルダーを右クリックし、[ Git フォルダー>作成 ] をクリックします。
- 「Create Git folder 」ダイアログで、次の操作を行います。
- [Git リポジトリ URL ] に、GitHub リポジトリの [GitHub Clone with HTTPS URL] を入力します。この記事では、URL の末尾が (
https://github.com/<your-GitHub-username>/best-notebooks.git
など)best-notebooks.git
であることを前提としています。 - Gitプロバイダー として、 GitHub を選択します。
- Git フォルダー名は 、リポジトリの名前 (
best-notebooks
など) に設定したままにしておきます。 - 「Git フォルダを作成 」をクリックします。
- [Git リポジトリ URL ] に、GitHub リポジトリの [GitHub Clone with HTTPS URL] を入力します。この記事では、URL の末尾が (
手順 2: ノートブックをインポートして実行する
このステップでは、既存の外部ノートブックをリポジトリにインポートします。このチュートリアル用に独自のノートブックを作成することもできますが、チュートリアルを迅速に完了するために、ここではノートブックを提供しています。
ステップ 2.1: リポジトリに作業ブランチを作成する
このサブステップでは、リポジトリにeda
という名前のブランチを作成します。このブランチを使用すると、リポジトリのmain
ブランチから独立してファイルやコードを操作できるようになります。これは、ソフトウェアエンジニアリングのベストプラクティスです(ブランチに別の名前を付けることもできます)。
レポジトリによっては、main
ブランチの代わりにmaster
という名前が付けられることもあります。その場合は、このチュートリアル全体を通してmain
をmaster
に置き換えてください。
Gitブランチでの作業に慣れていない場合は、Git Webサイトの「Gitブランチ - ブランチの概要」を参照してください。
-
ステップ 1.2 の Git フォルダが開いているはずです。 そうでない場合は、 ワークスペース のサイドバーで「 ワークスペース」>「ユーザー 」を展開し、ユーザー名フォルダを展開して、Gitフォルダをクリックします。
-
ワークスペース ナビゲーション階層リンクの下にあるフォルダー名の横にある、 メイン の Git ブランチ ボタンをクリックします。
-
best-ノートブック ダイアログで、[ ブランチの作成 ] ボタンをクリックします。
リポジトリの名前がbest-notebooks
以外の場合、このダイアログのタイトルは、ここと、このチュートリアル全体で異なります。
-
「
eda
」と入力し、「 作成 」をクリックします。 -
このダイアログを閉じます。
手順 2.2: ノートブックをリポジトリにインポートする
このサブステップでは、既存のノートブックを別のリポジトリからお客様のリポジトリにインポートします。このノートブックでは、以下の処理を行います。
- owid/covid-19-dataのGitHubリポジトリからCSVファイルをワークスペースのクラスターにコピーします。このCSVファイルには、COVID-19の入院状況と世界中の集中治療指標に関する公開データが含まれています。
- CSVファイルの内容をpandas DataFrameに読み込みます。
- 米国の指標のみが含まれるようにデータをフィルタリングします。
- データのプロットを表示します。
- pandas DataFrameをSpark DataFrameのPandas APIとして保存します。
- Spark DataFrame上のPandas APIでデータクレンジングを実行します。
- Spark DataFrame に Pandas API をワークスペースの Delta テーブル として書き込みます。
- Deltaテーブルの内容を表示します。
ここのリポジトリに独自のノートブックを作成することもできますが、代わりに既存のノートブックをインポートすると、このチュートリアルを高速化するのに役立ちます。 このブランチでノートブックを作成するか、ノートブックをインポートする代わりに既存のノートブックをこのブランチに移動するには、「 ワークスペース ファイルの基本的な使用方法」を参照してください。
-
best-ノートブック Git フォルダから、[ >フォルダの作成 ] をクリックします。
-
「新規フォルダ 」ダイアログで、「
notebooks
」と入力し、「 作成 」をクリックします。 -
ノートブック フォルダーで、ケバブをクリックし、[ インポート] をクリックします。
-
[インポート ] ダイアログで、次の操作を行います。
-
「 インポート元 」で「 URL 」を選択します。
-
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. [Raw] をクリックします。v. Web ブラウザのアドレスバーから完全な URL を [インポート ] ダイアログにコピーします。
-
[インポート ] ダイアログは、公開リポジトリの Git URL でのみ機能します。
- 「 インポート 」をクリックします。
手順 2.3: ノートブックを実行する
- ノートブックがまだ表示されていない場合は、 ノートブック フォルダを開き、フォルダ内の covid_eda_raw ノートブックをクリックします。
- このノートブックをアタッチするクラスタリングを選択します。 クラスタリングの作成手順については、「 クラスタリングの作成」を参照してください。
- 「 すべて実行 」をクリックします。
- ノートブックが実行されるまで待ちます。
ノートブックの実行が完了すると、ノートブックには、データのプロットと、Deltaテーブル内の600行を超える生データが表示されます。このノートブックの実行を開始したときにクラスターがまだ実行されていない場合は、クラスターが起動して結果が表示されるまでに数分かかることがあります。
手順 2.4: ノートブックをチェックインしてマージする
このサブステップでは、これまでの作業をGitHubリポジトリに保存します。次に、ノートブックを作業ブランチからリポジトリのmain
ブランチにマージします。
- ノートブックの名前の横にある [eda Git ブランチ] ボタンをクリックします。
- 「 best-notebooks 」ダイアログの「 変更 」タブで、 notebook/covid_eda_raw.py ファイルが選択されていることを確認します。
- [コミット メッセージ (必須)] に「
Added raw notebook
」と入力します。 - 「 概要(任意) 」を入力します。
This is the first version of the notebook.
- 「 コミット&プッシュ 」をクリックします。
- バナーの「 Git プロバイダーで pull request を作成する 」の pull request リンクをクリックします。
- GitHub でプル要求を作成し、プル要求を
main
ブランチにマージします。 - Databricksワークスペースに戻り、「 best-notebooks 」ダイアログがまだ表示されている場合は閉じます。
ステップ 3: 共有モジュールにコードを移動する
このステップでは、ノートブック内のコードの一部をノートブックの外部の共有関数セットに移動します。これにより、これらの関数を他の同様のノートブックで使用できるようになり、今後のコーディングが高速化され、より予測可能で一貫性のあるノートブックの結果が保証されます。このコードを共有すると、これらの関数をより簡単にテストできるようになります。これは、ソフトウェアエンジニアリングのベストプラクティスとして、コードの全体的な品質の向上につながります。
ステップ 3.1: リポジトリに別の作業ブランチを作成する
- ノートブックの名前の横にある [eda Git ブランチ] ボタンをクリックします。
- 「 best-notebooks 」ダイアログで、 eda ブランチの横にあるドロップダウン矢印をクリックし、 main を選択します。
- 「 プル 」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「 確認 」をクリックします。
- 「ブランチを作成」 ボタンをクリックします。
- 「
first_modules
」と入力し、「 作成 」をクリックします。 (ブランチに別の名前を付けることができます。 - このダイアログを閉じます。
手順 3.2: ノートブックをリポジトリにインポートする
このチュートリアルを高速化するために、このサブステップでは、別の既存のノートブックをリポジトリにインポートします。このノートブックは前のノートブックと同じことを行いますが、このノートブックはノートブックの外部に格納されている共有コード関数を呼び出す点が異なります。ここでも、リポジトリに独自のノートブックを作成し、実際のコード共有を自分で行うことができます。
-
ワークスペース ブラウザーで、 ノートブック フォルダーを右クリックし、[ インポート] をクリックします。
-
[インポート ] ダイアログで、次の操作を行います。
-
「 インポート元 」で「 URL 」を選択します。
-
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. [Raw] をクリックします。v. Webブラウザのアドレスバーから完全なURLを[ ノートブックのインポート ]ダイアログにコピーします。
-
「 ノートブックをインポート 」ダイアログは、パブリックリポジトリのGit URLでのみ機能します。
- 「 インポート 」をクリックします。
ステップ 3.3: ノートブックの対応する共有コード関数を追加する
-
ワークスペース ブラウザーで、 best-ノートブック Git フォルダーを右クリックし、[ > フォルダーの作成 ] をクリックします。
-
「新規フォルダ 」ダイアログで、「
covid_analysis
」と入力し、「 作成 」をクリックします。 -
covid_analysis フォルダから、「 >ファイルの作成 」をクリックします。
-
「 新しいファイル名 」ダイアログで、
transforms.py
と入力し、「 ファイルを作成 」をクリックします。 -
transforms.py エディタウィンドウで、次のコードを入力します。
Pythonimport 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-ノートブック 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
上記のファイルには、特定のパッケージ バージョンが一覧表示されます。 互換性を高めるために、これらのバージョンをAll-Purposeクラスターにインストールされているバージョンと相互参照できます。 クラスタリングの バージョンについては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行を超える生データが表示されます。このノートブックとの主な違いは、別のフィルタ(USA
の代わりにDZA
のiso_code
)が使用されていることです。このノートブックの実行を開始したときにクラスターがまだ実行されていない場合は、クラスターが起動して結果が表示されるまでに数分かかることがあります。
手順 3.6: ノートブックとその関連コードをチェックインする
-
ノートブックの名前の横にある [ Git ブランチfirst_modules ] ボタンをクリックします。
-
「 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 でプル要求を作成し、プル要求を
main
ブランチにマージします。 -
Databricksワークスペースに戻り、「 best-notebooks 」ダイアログがまだ表示されている場合は閉じます。
ステップ 4: 共有コードをテストする
このステップでは、先程のステップの共有コードをテストします。ただし、covid_eda_modular
ノートブック自体を実行せずにこのコードをテストする必要があります。これは、共有コードの実行が失敗すると、ノートブック自体の実行も失敗する可能性が高いためです。メインのノートブックが失敗する前に、まず共有コードでエラーを発見することをお勧めします。このテスト手法は、ソフトウェアエンジニアリングのベストプラクティスです。
ノートブックのテスト、および R と Scala ノートブックのテストに関するその他の方法については、「 ノートブックの単体テスト」を参照してください。
ステップ 4.1: リポジトリに別の作業ブランチを作成する
- ノートブックの名前の横にある [ Git ブランチfirst_modules ] ボタンをクリックします。
- 「 best-notebooks 」ダイアログで、 first_modules ブランチの横にあるドロップダウン矢印をクリックし、 main を選択します。
- 「 プル 」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「 確認 」をクリックします。
- 「ブランチを作成」 をクリックします。
- 「
first_tests
」と入力し、「 作成 」をクリックします。 (ブランチに別の名前を付けることができます。 - このダイアログを閉じます。
ステップ 4.2: テストを追加する
このサブステップでは、pytestフレームワークを使用して共有コードをテストします。これらのテストでは、特定のテスト結果が達成されたかどうかをアサートします。いずれかのテストで予期しない結果が発生した場合、その特定のテストではアサーションが失敗し、テスト自体も失敗します。
-
ワークスペース ブラウザーで、Git フォルダーを右クリックし、[ > フォルダーの作成 ] をクリックします。
-
「新規フォルダ 」ダイアログで、「
tests
」と入力し、「 作成 」をクリックします。 -
tests フォルダから、「 Create > File 」をクリックします。
-
「 新しいファイル名 」ダイアログで、
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 フォルダから、「 Create > File 」をクリックします。
-
「 新しいファイル名 」ダイアログで、
transforms_test.py
と入力し、「 ファイルを作成 」をクリックします。 -
エディタtransforms_test.py ウィンドウで、次のテストコードを入力します。これらのテストでは、標準の
pytest
フィクスチャ と、モックされたメモリ内 Pandas DataFrameを使用します。Python# 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
の形式に従うすべてのファイルが実行されます。
-
ワークスペース ブラウザーで、 ノートブック フォルダーを右クリックし、[ インポート] をクリックします。
-
「 ノートブックをインポート 」ダイアログで、
-
「 インポート元 」で「 URL 」を選択します。
-
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. [Raw] をクリックします。v. Webブラウザのアドレスバーから完全なURLを[ ノートブックのインポート ]ダイアログにコピーします。
-
「 ノートブックをインポート 」ダイアログは、パブリックリポジトリのGit URLでのみ機能します。
-
「 インポート 」をクリックします。
-
「 すべて実行 」をクリックします。
-
ノートブックが実行されるまで待ちます。
ノートブックの実行が完了すると、ノートブックに、成功したテストと失敗したテストの数に関する情報と、その他の関連詳細が表示されます。このノートブックの実行を開始したときにクラスターがまだ実行されていない場合は、クラスターが起動して結果が表示されるまでに数分かかることがあります。
リポジトリ構造は以下のようになります。
├── covid_analysis
│ └── transforms.py
├── notebooks
│ ├── covid_eda_modular
│ ├── covid_eda_raw (optional)
│ └── run_unit_tests
├── requirements.txt
└── tests
├── testdata.csv
└── transforms_test.py
ステップ 4.4: ノートブックと関連テストをチェックインする
-
ノートブックの名前の横にある [ Git ブランチfirst_tests ] ボタンをクリックします。
-
「 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 でプル要求を作成し、プル要求を
main
ブランチにマージします。 -
Databricksワークスペースに戻り、「 best-notebooks 」ダイアログがまだ表示されている場合は閉じます。
手順 5: ノートブックを実行するジョブを作成する
前のステップでは、共有コードを手動でテストし、ノートブックを手動で実行しました。このステップでは、Databricksジョブを使用して共有コードをテストし、オンデマンドまたは定期的なスケジュールでノートブックを自動的に実行します。
ステップ 5.1: テスト ノートブックを実行するジョブ タスクを作成する
-
ワークスペースのサイドバーで、[ ワークフロー] をクリックします。
-
「 ジョブ 」タブで、「 ジョブを作成 」をクリックします。
-
covid_report
するジョブの名前を編集します。 -
「 タスク名 」に
run_notebook_tests
と入力します。 -
「 タイプ 」で「 ノートブック 」を選択します。
-
[ソース ] で [ Git プロバイダー ] を選択します。
-
「 gitリファレンスを追加 」をクリックします。
-
「 Git情報 」ダイアログで、
- [Git リポジトリ URL ] に、GitHub リポジトリの [GitHub Clone with HTTPS URL] を入力します。この記事では、URL の末尾が (
https://github.com/<your-GitHub-username>/best-notebooks.git
など)best-notebooks.git
であることを前提としています。 - Gitプロバイダー として、 GitHub を選択します。
- 「 Gitリファレンス(ブランチ/タグ/コミット) 」に、
main
と入力します。 - 「 Gitリファレンス(ブランチ/タグ/コミット) 」の横にある「 ブランチ 」を選択します。
- 確認 をクリックします。
- [Git リポジトリ URL ] に、GitHub リポジトリの [GitHub Clone with HTTPS URL] を入力します。この記事では、URL の末尾が (
-
「 パス 」に
notebooks/run_unit_tests
と入力します。.py
ファイル拡張子は追加しないでください。 -
「 クラスター 」で、前のステップのクラスターを選択します。
-
「 タスクを作成 」をクリックします。
このシナリオでは、「Databricks スケジュールされたノートブックジョブの作成と管理 」で説明されているように、ノートブックのスケジュール ボタンを使用して、このノートブックを定期的に実行するようにジョブをスケジュールすることはお勧めしません 。これは、スケジュール ボタンがワークスペース リポジトリ内のノートブックの最新の 作業 コピーを使用してジョブを作成するためです。 代わりに、Databricks では、前の手順に従って、リポジトリ内の最新の コミット されたバージョンのノートブックを使用するジョブを作成することをお勧めします。
ステップ 5.2: メイン ノートブックを実行するジョブ タスクを作成する
- [ + タスクの追加 ] アイコンをクリックします。
- ポップアップメニューが表示されます。[ ノートブック ] を選択します。
- 「 タスク名 」に
run_main_notebook
と入力します。 - 「 タイプ 」で「 ノートブック 」を選択します。
- 「 パス 」に
notebooks/covid_eda_modular
と入力します。.py
ファイル拡張子は追加しないでください。 - 「 クラスター 」で、前のステップのクラスターを選択します。
- 「 Depends on value 」が
run_notebook-tests
であることを確認します。 - 「 タスクを作成 」をクリックします。
ステップ 5.3 ジョブを実行する
-
「 今すぐ実行 」をクリックします。
-
ポップアップで、「 実行結果を表示 」をクリックします。
ポップアップがすぐに消えてしまう場合は、以下を実行してください。
-
データサイエンス & エンジニアリング または Databricks Mosaic AI 環境のサイドバーで、 ワークフロー をクリックします。
-
「 ジョブ実行 」タブで、「 ジョブ 」列の covid_report を含む最新ジョブの「 開始時刻 」値をクリックします。
- ジョブ結果を見るには、 run_notebook_tests タイル、 run_main_notebook タイル、またはその両方をクリックします。各タイルの結果は、ノートブックを1つずつ自分で実行した場合と同じです。
このジョブはオンデマンドで実行されました。 このジョブを定期的に実行するように設定するには、 スケジュールとトリガーを使用したジョブの自動化を参照してください。
(オプション)手順 6: コードをテストし、コードが変更されるたびにノートブックを自動的に実行するようにリポジトリを設定する
前のステップでは、ジョブを使用して共有コードを自動的にテストし、ノートブックをある時点または定期的に実行しました。 ただし、変更が GitHub リポジトリにマージされたときに、 GitHub Actions などの CI/CD ツールを使用して、テストを自動的にトリガーすることをお勧めします。
ステップ 6.1: ワークスペースへの GitHub アクセスを設定する
このサブステップでは、変更がリポジトリにマージされるたびにワークスペースでジョブを実行する GitHub Actions ワークフローを設定します。 これを行うには、GitHub にアクセス用の一意の Databricks トークンを提供します。
セキュリティ上の理由から、Databricksでは、DatabricksワークスペースユーザーのパーソナルアクセストークンをGitHubに提供することはお勧めしていません。代わりに、Databricksでは、Databricksサービスプリンシパルに関連付けられたDatabricksアクセストークンをGitHubに提供することをお勧めしています。手順については、GitHub Actions Marketplaceの「Databricksノートブック実行のGitHub Action」の「AWS」セクションを参照してください。
ノートブック は、トークンに関連付けられている ID のすべてのワークスペース アクセス許可で実行されるため、 Databricks サービスプリンシパルを使用することをお勧めします。 Databricks ワークスペース ユーザーの個人用アクセス トークンを個人用探索目的でのみ GitHub に付与することを本当に望んでおり、セキュリティ上の理由から Databricks がこの方法を推奨しないことを理解している場合は、 ワークスペース ユーザーの個人用アクセス トークンを作成する手順を参照してください。
ステップ 6.2: GitHub Actions ワークフローを追加する
このサブステップでは、リポジトリへのプルリクエストがあるたびにrun_unit_tests
ノートブックを実行するGitHub Actionsワークフローを追加します。
このサブステップでは、GitHub リポジトリの複数のフォルダー レベルに格納されているファイルに GitHub Actions ワークフローが格納されます。 GitHub Actions が正しく機能するには、リポジトリに特定のネストされたフォルダー階層が存在する必要があります。 この手順を完了するには、Databricks Git フォルダーのユーザー インターフェイスでは入れ子になったフォルダー階層の作成がサポートされていないため、GitHub リポジトリの Web サイトを使用する必要があります。
-
GitHubリポジトリのWebサイトで、「 コード 」タブをクリックします。
-
[main ] の横にある矢印をクリックして、[ Switch branches or tags ] ドロップダウン リストを展開します。
-
「 ブランチを検索または作成 」ボックスに
adding_github_actions
と入力します。 -
「 ブランチを作成:adding_github_actions from 'main' 」をクリックします。
-
「ファイルを追加」>「新しいファイルを作成」 をクリックします。
-
「 ファイルに名前を付ける 」に
.github/workflows/databricks_pull_request_tests.yml
と入力します。 -
エディターウィンドウで、次のコードを入力します。 このコードでは、
run_unit_tests
ノートブックを実行するために、Databricks ノートブック GitHub Actions の pull_request フックを使用します。以下のコードで、以下のように置き換えます。
<your-workspace-instance-URL>
を Databricks インスタンス名に置き換えます。<your-access-token>
を、以前生成したトークンで置き換えます。<your-cluster-id>
をターゲット クラスタリング ID に置き換えます。
YAMLname: 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 Actions に基づいてテストがすぐに自動的にトリガーされます。
ステップ 7.1: リポジトリに別の作業ブランチを作成する
- ワークスペース ブラウザーから、 best-ノートブック Git フォルダーを開きます。
- フォルダ名の横にある [ Git ブランチfirst_tests ] ボタンをクリックします。
- [best-ノートブック ] ダイアログで、 first_tests 分岐の横にあるドロップダウン矢印をクリックし、[ main ] を選択します。
- 「 プル 」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「 確認 」をクリックします。
- + ( ブランチを作成 )ボタンをクリックします。
- 「
trigger_tests
」と入力し、「 作成 」をクリックします。 (ブランチに別の名前を付けることができます。 - このダイアログを閉じます。
ステップ 7.2: 共有コードを変更する
-
ワークスペース ブラウザーの best-ノートブック Git フォルダーで、 covid_analysis/transforms.py ファイルをクリックします。
-
このファイルの 3 行目を変更します。
Python# Filter by country code.
を以下のように変更します。
Python# Filter by country code. If not specified, use "USA."
ステップ 7.3: 変更をチェックインしてテストをトリガーする
- ファイル名の横にある [Git ブランチ trigger_tests ] ボタンをクリックします。
- 「 best-notebooks 」ダイアログの「 変更 」タブで、 covid_analysis/transforms.py が選択されていることを確認します。
- [コミット メッセージ (必須)] に「
Updated comment
」と入力します。 - 「 概要(任意) 」を入力します。
This updates the comment for filter_country.
- 「 コミット&プッシュ 」をクリックします。
- バナーの「 Git プロバイダーで pull request を作成する 」の pull request リンクをクリックし、GitHub で pull request を作成します。
- プルリクエストページで、「 マージ前のDatabricksテスト/unit-test-notebook(pull_request)を実行 」の横にあるアイコンに緑色のチェックマークが表示されるまで待ちます(アイコンが表示されるまでに少し時間がかかる場合があります)。緑色のチェックマークではなく赤色のXが表示されている場合は、「 詳細 」をクリックして理由を確認してください。アイコンまたは「 詳細 」が表示されていない場合は、「 すべてのチェックを表示 」をクリックします。
- 緑のチェックマークが表示されたら、プルリクエストを
main
ブランチにマージします。