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

この記事では、バージョン管理、コード共有、テスト、そしてオプションとして継続的インテグレーションと継続的デリバリーまたはデプロイメント（CI/CD）を含む、ソフトウェアエンジニアリングのベストプラクティスをDatabricksノートブックに適用する方法を示す実践的なチュートリアルをご紹介します。

このチュートリアルでは、以下のことを行います。

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

必要条件

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

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

注記

新しいリポジトリを作成する場合は、少なくとも1つのファイル、例えばREADMEファイルでリポジトリを初期化してください。

• Databricks ワークスペース。 ワークスペースをまだ作成していない場合は、作成します。

• ワークスペース内の Databricks All-Purposeクラスター 。 設計フェーズでノートブックを実行するには、 実行中の All-Purposeクラスターにノートブックをアタッチします。 後で、このチュートリアルでは Databricks ジョブ を使用して、このクラスタリングでのノートブックの実行を自動化します。 (ジョブの有効期間中のみ存在する ジョブ クラスタリング でジョブを実行することもできます。 All-Purposeクラスターを まだお持ちでない場合は、作成してください。

ステップ 1: Databricks Git フォルダーを設定する

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

ワークスペースをGitHubリポジトリに接続できるようにするには、まずワークスペースにGitHubの認証情報を入力する必要があります（まだ行っていない場合）。

ステップ 1.1: GitHub の資格情報を入力する

1. ワークスペースの右上にあるユーザー名をクリックし、ドロップダウンリストの [設定 ]をクリックします。
2. 「設定 」サイドバーの 「ユーザー 」で、「 リンクされたアカウント 」をクリックします。
3. [Git 統合 ] の [ Git プロバイダー ] で [ GitHub ] を選択します。
4. [個人用アクセストークン ]をクリックします。
5. 「 Gitプロバイダーのユーザー名またはEメールアドレス 」に、GitHubユーザー名を入力します。
6. 「 トークン 」にGitHubパーソナルアクセストークン（クラシック）を入力します。このパーソナルアクセストークン（クラシック）には、 リポジトリ と ワークフロー の権限が必要です。
7. [ 保存 ]をクリックします。

ステップ 1.2: GitHub リポジトリに接続する

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

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

このステップでは、既存の外部ノートブックをリポジトリにインポートします。このチュートリアル用に独自のノートブックを作成することもできますが、チュートリアルを迅速に完了するために、ここではノートブックを提供しています。

ステップ 2.1: リポジトリに作業ブランチを作成する

このサブステップでは、リポジトリにedaという名前のブランチを作成します。このブランチを使用すると、リポジトリのmainブランチから独立してファイルやコードを操作できるようになります。これは、ソフトウェアエンジニアリングのベストプラクティスです（ブランチに別の名前を付けることもできます）。

注記

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

ヒント

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

1. ステップ 1.2 の Git フォルダが開いているはずです。 そうでない場合は、 ワークスペース のサイドバーで「 ワークスペース」>「ユーザー 」を展開し、ユーザー名フォルダを展開して、Gitフォルダをクリックします。

2. ワークスペース ナビゲーション階層リンクの下にあるフォルダー名の横にある、 メイン の Git ブランチ ボタンをクリックします。

3. best-ノートブック ダイアログで、[ ブランチの作成 ] ボタンをクリックします。

注記

リポジトリの名前がbest-notebooks以外の場合、このダイアログのタイトルは、ここと、このチュートリアル全体で異なります。

4. 「 eda」と入力し、「 作成 」をクリックします。

5. このダイアログを閉じます。

手順 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テーブルの内容を表示します。

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

1. best-ノートブック Git フォルダから、[ >フォルダの作成 ] をクリックします。

2. 「新規フォルダ 」ダイアログで、「notebooks」と入力し、「 作成 」をクリックします。

3. ノートブック フォルダーで、ケバブをクリックし、[ インポート] をクリックします。

4. [インポート ] ダイアログで、次の操作を行います。

   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. [Raw] をクリックします。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 」ダイアログの「 変更 」タブで、 notebook/covid_eda_raw.py ファイルが選択されていることを確認します。
3. [コミット メッセージ (必須)] に「Added raw notebook」と入力します。
4. 「 概要（任意） 」を入力します。 This is the first version of the notebook.
5. 「 コミット＆プッシュ 」をクリックします。
6. バナーの「 Git プロバイダーで pull request を作成する 」の pull request リンクをクリックします。
7. GitHub でプル要求を作成し、プル要求を main ブランチにマージします。
8. 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 の 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.3: ノートブックの対応する共有コード関数を追加する

1. ワークスペース ブラウザーで、 best-ノートブック Git フォルダーを右クリックし、[ > フォルダーの作成 ] をクリックします。

2. 「新規フォルダ 」ダイアログで、「covid_analysis」と入力し、「 作成 」をクリックします。

3. covid_analysis フォルダから、「 >ファイルの作成 」をクリックします。

4. 「 新しいファイル名 」ダイアログで、transforms.pyと入力し、「 ファイルを作成 」をクリックします。

5. transforms.py エディタウィンドウで、次のコードを入力します。

   Python

   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-ノートブック Git フォルダーを右クリックし、[ > ファイルの作成 ] をクリックします。

注記

パッケージの依存関係を一覧表示するファイルは、 ノートブック や covid_analysis フォルダーではなく、Git フォルダーのルートに配置する必要があります。

2. 「 新しいファイル名 」ダイアログで、requirements.txtと入力し、「 ファイルを作成 」をクリックします。

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

注記

上記のファイルには、特定のパッケージ バージョンが一覧表示されます。 互換性を高めるために、これらのバージョンを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の共有コードを呼び出します。

1. ワークスペース ブラウザーで、 ノートブック フォルダー内の covid_eda_modular ノートブックをクリックします。
2. このノートブックをアタッチするクラスタリングを選択します。
3. 「 すべて実行 」をクリックします。
4. ノートブックが実行されるまで待ちます。

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

手順 3.6: ノートブックとその関連コードをチェックインする

1. ノートブックの名前の横にある [ Git ブランチfirst_modules ] ボタンをクリックします。

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 プロバイダーで pull request を作成する 」の pull request リンクをクリックします。

7. GitHub でプル要求を作成し、プル要求を main ブランチにマージします。

8. Databricksワークスペースに戻り、「 best-notebooks 」ダイアログがまだ表示されている場合は閉じます。

ステップ 4: 共有コードをテストする

このステップでは、先程のステップの共有コードをテストします。ただし、covid_eda_modularノートブック自体を実行せずにこのコードをテストする必要があります。これは、共有コードの実行が失敗すると、ノートブック自体の実行も失敗する可能性が高いためです。メインのノートブックが失敗する前に、まず共有コードでエラーを発見することをお勧めします。このテスト手法は、ソフトウェアエンジニアリングのベストプラクティスです。

ヒント

ノートブックのテスト、および R と Scala ノートブックのテストに関するその他の方法については、「 ノートブックの単体テスト」を参照してください。

ステップ 4.1: リポジトリに別の作業ブランチを作成する

1. ノートブックの名前の横にある [ Git ブランチfirst_modules ] ボタンをクリックします。
2. 「 best-notebooks 」ダイアログで、 first_modules ブランチの横にあるドロップダウン矢印をクリックし、 main を選択します。
3. 「 プル 」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「 確認 」をクリックします。
4. 「ブランチを作成」 をクリックします。
5. 「 first_tests」と入力し、「 作成 」をクリックします。 (ブランチに別の名前を付けることができます。
6. このダイアログを閉じます。

ステップ 4.2: テストを追加する

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

1. ワークスペース ブラウザーで、Git フォルダーを右クリックし、[ > フォルダーの作成 ] をクリックします。

2. 「新規フォルダ 」ダイアログで、「tests」と入力し、「 作成 」をクリックします。

3. tests フォルダから、「 Create > File 」をクリックします。

4. 「 新しいファイル名 」ダイアログで、testdata.csvと入力し、「 ファイルを作成 」をクリックします。

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. tests フォルダから、「 Create > File 」をクリックします。

7. 「 新しいファイル名 」ダイアログで、transforms_test.pyと入力し、「 ファイルを作成 」をクリックします。

8. エディタ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の形式に従うすべてのファイルが実行されます。

1. ワークスペース ブラウザーで、 ノートブック フォルダーを右クリックし、[ インポート] をクリックします。

2. 「 ノートブックをインポート 」ダイアログで、

   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. [Raw] をクリックします。v. Webブラウザのアドレスバーから完全なURLを[ ノートブックのインポート ]ダイアログにコピーします。

注記

「 ノートブックをインポート 」ダイアログは、パブリックリポジトリのGit URLでのみ機能します。

3. 「 インポート 」をクリックします。

4. このノートブックをアタッチするクラスタリングを選択します。

5. 「 すべて実行 」をクリックします。

6. ノートブックが実行されるまで待ちます。

ノートブックの実行が完了すると、ノートブックに、成功したテストと失敗したテストの数に関する情報と、その他の関連詳細が表示されます。このノートブックの実行を開始したときにクラスターがまだ実行されていない場合は、クラスターが起動して結果が表示されるまでに数分かかることがあります。

リポジトリ構造は以下のようになります。

├── 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: ノートブックと関連テストをチェックインする

1. ノートブックの名前の横にある [ Git ブランチfirst_tests ] ボタンをクリックします。

2. 「 best-notebooks 」ダイアログの「 変更 」タブで、以下が選択されていることを確認します。

   • tests/transforms_test.py
   • notebooks/run_unit_tests.py
   • tests/testdata.csv

3. [コミット メッセージ (必須)] に「Added tests」と入力します。

4. 「 概要（任意） 」にThese are the unit tests for the shared code.と入力します。

5. 「 コミット＆プッシュ 」をクリックします。

6. バナーの「 Git プロバイダーで pull request を作成する 」の pull request リンクをクリックします。

7. GitHub でプル要求を作成し、プル要求を main ブランチにマージします。

8. Databricksワークスペースに戻り、「 best-notebooks 」ダイアログがまだ表示されている場合は閉じます。

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

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

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

1. ワークスペースのサイドバーで、[ ワークフロー] をクリックします。

2. 「 ジョブ 」タブで、「 ジョブを作成 」をクリックします。

3. covid_reportするジョブの名前を編集します。

4. 「 タスク名 」にrun_notebook_testsと入力します。

5. 「 タイプ 」で「 ノートブック 」を選択します。

6. [ソース ] で [ Git プロバイダー ] を選択します。

7. 「 gitリファレンスを追加 」をクリックします。

8. 「 Git情報 」ダイアログで、

   1. [Git リポジトリ URL ] に、GitHub リポジトリの [GitHub Clone with HTTPS URL] を入力します。この記事では、URL の末尾が (https://github.com/<your-GitHub-username>/best-notebooks.gitなど) best-notebooks.gitであることを前提としています。
   2. Gitプロバイダー として、 GitHub を選択します。
   3. 「 Gitリファレンス（ブランチ/タグ/コミット） 」に、mainと入力します。
   4. 「 Gitリファレンス（ブランチ/タグ/コミット） 」の横にある「 ブランチ 」を選択します。
   5. 確認 をクリックします。

9. 「 パス 」にnotebooks/run_unit_testsと入力します。.pyファイル拡張子は追加しないでください。

10. 「 クラスター 」で、前のステップのクラスターを選択します。

11. 「 タスクを作成 」をクリックします。

注記

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

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

1. [ + タスクの追加 ] アイコンをクリックします。
2. ポップアップメニューが表示されます。[ ノートブック ] を選択します。
3. 「 タスク名 」にrun_main_notebookと入力します。
4. 「 タイプ 」で「 ノートブック 」を選択します。
5. 「 パス 」にnotebooks/covid_eda_modularと入力します。.pyファイル拡張子は追加しないでください。
6. 「 クラスター 」で、前のステップのクラスターを選択します。
7. 「 Depends on value 」がrun_notebook-testsであることを確認します。
8. 「 タスクを作成 」をクリックします。

ステップ 5.3 ジョブを実行する

1. 「 今すぐ実行 」をクリックします。

2. ポップアップで、「 実行結果を表示 」をクリックします。

注記

ポップアップがすぐに消えてしまう場合は、以下を実行してください。

1. データサイエンス & エンジニアリング または Databricks Mosaic AI 環境のサイドバーで、 ワークフロー をクリックします。

2. 「 ジョブ実行 」タブで、「 ジョブ 」列の covid_report を含む最新ジョブの「 開始時刻 」値をクリックします。

3. ジョブ結果を見るには、 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」セクションを参照してください。

important

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

ステップ 6.2: GitHub Actions ワークフローを追加する

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

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

1. GitHubリポジトリのWebサイトで、「 コード 」タブをクリックします。

2. [main ] の横にある矢印をクリックして、[ Switch branches or tags ] ドロップダウン リストを展開します。

3. 「 ブランチを検索または作成 」ボックスにadding_github_actionsと入力します。

4. 「 ブランチを作成：adding_github_actions from 'main' 」をクリックします。

5. 「ファイルを追加」>「新しいファイルを作成」 をクリックします。

6. 「 ファイルに名前を付ける 」に.github/workflows/databricks_pull_request_tests.ymlと入力します。

7. エディターウィンドウで、次のコードを入力します。 このコードでは、run_unit_tests ノートブックを実行するために、Databricks ノートブック GitHub Actions の pull_request フックを使用します。

   以下のコードで、以下のように置き換えます。

   • <your-workspace-instance-URL> を Databricks インスタンス名に置き換えます。
   • <your-access-token> を、以前生成したトークンで置き換えます。
   • <your-cluster-id> をターゲット クラスタリング ID に置き換えます。
   YAML

   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 Actions に基づいてテストがすぐに自動的にトリガーされます。

ステップ 7.1: リポジトリに別の作業ブランチを作成する

1. ワークスペース ブラウザーから、 best-ノートブック Git フォルダーを開きます。
2. フォルダ名の横にある [ Git ブランチfirst_tests ] ボタンをクリックします。
3. [best-ノートブック ] ダイアログで、 first_tests 分岐の横にあるドロップダウン矢印をクリックし、[ main ] を選択します。
4. 「 プル 」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「 確認 」をクリックします。
5. + （ ブランチを作成 ）ボタンをクリックします。
6. 「 trigger_tests」と入力し、「 作成 」をクリックします。 (ブランチに別の名前を付けることができます。
7. このダイアログを閉じます。

ステップ 7.2: 共有コードを変更する

1. ワークスペース ブラウザーの best-ノートブック Git フォルダーで、 covid_analysis/transforms.py ファイルをクリックします。

2. このファイルの 3 行目を変更します。

   Python

   # Filter by country code.

   を以下のように変更します。

   Python

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

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

1. ファイル名の横にある [Git ブランチ trigger_tests ] ボタンをクリックします。
2. 「 best-notebooks 」ダイアログの「 変更 」タブで、 covid_analysis/transforms.py が選択されていることを確認します。
3. [コミット メッセージ (必須)] に「Updated comment」と入力します。
4. 「 概要（任意） 」を入力します。 This updates the comment for filter_country.
5. 「 コミット＆プッシュ 」をクリックします。
6. バナーの「 Git プロバイダーで pull request を作成する 」の pull request リンクをクリックし、GitHub で pull request を作成します。
7. プルリクエストページで、「 マージ前のDatabricksテスト/unit-test-notebook（pull_request）を実行 」の横にあるアイコンに緑色のチェックマークが表示されるまで待ちます（アイコンが表示されるまでに少し時間がかかる場合があります）。緑色のチェックマークではなく赤色のXが表示されている場合は、「 詳細 」をクリックして理由を確認してください。アイコンまたは「 詳細 」が表示されていない場合は、「 すべてのチェックを表示 」をクリックします。
8. 緑のチェックマークが表示されたら、プルリクエストをmainブランチにマージします。