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

この記事では、バージョン管理、コード共有、テスト、そしてオプションとして継続的インテグレーションと継続的デリバリーまたはデプロイメント（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. 「Git フォルダーの作成」ダイアログで:

    1. 「GitリポジトリURL」に、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 Webサイトの「Gitブランチ - ブランチの概要」を参照してください。

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

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

  3. ベストノートブックダイアログで、 「ブランチの作成」ボタンをクリックします。

    注

    リポジトリの名前が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でデータクレンジングを実行します。

  • ワークスペースに Delta テーブル として Spark DataFrame に PandasAPI を書き込みます。

  • Deltaテーブルの内容を表示します。

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

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

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

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

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

    1. 「インポート元」で「URL」を選択します。

    2. GitHubのdatabricks/notebook-best-practicesリポジトリにcovid_eda_rawノートブックの生コンテンツのURLを入力します。このURLを取得するには：

      1. https://github.com/databricks/notebook-best-practicesに移動します。

      2. notebooksフォルダをクリックします。

      3. covid_eda_raw.pyファイルをクリックします。

      4. 「生データ」をクリックします。

      5. 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. バナーの [Create a pull request on your git provider] (git プロバイダーでプル要求を作成する ) の 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を取得するには：

      1. https://github.com/databricks/notebook-best-practicesに移動します。

      2. notebooksフォルダをクリックします。

      3. covid_eda_modular.pyファイルをクリックします。

      4. 「生データ」をクリックします。

      5. Webブラウザのアドレスバーから完全なURLを「ノートブックをインポート」ダイアログにコピーします。

        注

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

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

ステップ3.3：ノートブックのサポートする共有コード関数を追加する

  1. ワークスペースブラウザから、 best-NotebookGitフォルダを右クリックし、 [作成] > [フォルダ]をクリックします。

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

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

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

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

  1. ワークスペースブラウザから、 bestNote ブック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）が使用されていることです。このノートブックの実行を開始したときにクラスターがまだ実行されていない場合は、クラスターが起動して結果が表示されるまでに数分かかることがあります。

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

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

ヒント

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

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

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

  2. 「best-notebooks」ダイアログで、first_modulesブランチの横にあるドロップダウン矢印をクリックし、mainを選択します。

  3. 「プル」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「確認」をクリックします。

  4. 「 ブランチの作成」をクリックします。

  5. 「 first_tests」と入力し、「 作成」をクリックします。 (ブランチに別の名前を付けることができます。

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

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

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

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

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

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

  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フォルダから、「>ファイルの作成」をクリックします。

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

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

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

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

    1. 「インポート元」で「URL」を選択します。

    2. GitHubのdatabricks/notebook-best-practicesリポジトリにrun_unit_testsノートブックの生コンテンツのURLを入力します。このURLを取得するには：

      1. https://github.com/databricks/notebook-best-practicesに移動します。

      2. notebooksフォルダをクリックします。

      3. run_unit_tests.pyファイルをクリックします。

      4. 「生データ」をクリックします。

      5. Webブラウザのアドレスバーから完全なURLを「ノートブックをインポート」ダイアログにコピーします。

        注

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

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

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

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

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

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

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

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

ステップ5：ノートブックを実行するジョブを作成する

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

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

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

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

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

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

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

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

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

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

    1. 「GitリポジトリURL」に、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. 「確認」をクリックします。

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

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

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

注

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

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

  1. [+ タスクの追加] アイコンをクリックします。

  2. ポップアップメニューが表示されます。[ノートブック] を選択します。

  3. 「タスク名」にrun_main_notebookと入力します。

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

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

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

  7. [Depends on] の値が [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 ワークスペース ユーザーの個人用アクセストークンを GitHub に提供することはお勧めしません。 手順については、GitHub Actions Marketplace の Databricks ノートブックの GitHub Action の実行 ページの GCP セクションを参照してください。

重要

ノートブックは、トークンに関連付けられている 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の横にある矢印をクリックして、 [ブランチまたはタグの切り替え] ドロップダウン リストを展開します。

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

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

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

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

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

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

    • <your-workspace-instance-URL> を 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"

  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. ワークスペースブラウザから、 bestnotebookGitフォルダを開きます。

  2. フォルダー名の横にある「first_tests Git ブランチ」ボタンをクリックします。

  3. best-notebookダイアログで、 first_testsブランチの横にあるドロップダウン矢印をクリックし、 mainを選択します。

  4. 「プル」ボタンをクリックします。プルを続行するかどうかを確認するプロンプトが表示されたら、「確認」をクリックします。

  5. +（ブランチを作成）ボタンをクリックします。

  6. 「 trigger_tests」と入力し、「 作成」をクリックします。 (ブランチに別の名前を付けることができます。

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

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

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

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

    # Filter by country code.

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

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

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

  1. ファイル名の横にある「trigger_tests Git ブランチ」ボタンをクリックします。

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

  3. [コミット メッセージ (必須)]に、 Updated commentと入力します。

  4. 「概要（任意）」を入力します。 This updates the comment for filter_country.

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

  6. バナーの「Git プロバイダーでプル リクエストを作成する」のプル リクエスト リンクをクリックし、GitHub でプル リクエストを作成します。

  7. プルリクエストページで、「マージ前のDatabricksテスト/unit-test-notebook（pull_request）を実行」の横にあるアイコンに緑色のチェックマークが表示されるまで待ちます（アイコンが表示されるまでに少し時間がかかる場合があります）。緑色のチェックマークではなく赤色のXが表示されている場合は、「詳細」をクリックして理由を確認してください。アイコンまたは「詳細」が表示されていない場合は、「すべてのチェックを表示」をクリックします。

  8. 緑のチェックマークが表示されたら、プルリクエストをmainブランチにマージします。