次の方法で共有

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

  • [アーティクル]

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

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

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

必要条件

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

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

    注意

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

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

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

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

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

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

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

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

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

  1. ワークスペース サイドバーにある [ワークスペース] をクリックします。
  2. ワークスペース ブラウザーで [ワークスペース] > [ユーザー] を展開します。
  3. ユーザー名フォルダーを右クリックし、[作成] > [Git フォルダー] をクリックします。
  4. [Git フォルダーの作成] ダイアログで次の手順を実行します。
    1. [Git リポジトリ URL] に、お使いの GitHub リポジトリの GitHub [Clone with HTTPS] (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 ブランチ - Nutshell のブランチ」を参照してください。

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

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

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

    注意

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

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

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

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

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

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

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

  1. best-notebooks Git フォルダーから[作成] > [フォルダー] をクリックします。
  2. [新しいフォルダー] ダイアログで「notebooks」と入力し、[作成] をクリックします。
  3. notebooks フォルダーから kebab をクリックし、[インポート] をクリックします。
  4. [インポート] ダイアログで次の手順を実行します。

    1. [インポート元] で、[URL] を選択します。

    2. GitHub の covid_eda_raw リポジトリに databricks/notebook-best-practices ノートブックの生コンテンツへの 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. ノートブックがまだ表示されていない場合は、notebooks フォルダーを開き、フォルダー内の covid_eda_raw ノートブックをクリックします。
  2. このノートブックをアタッチするクラスターを選びます。 クラスターの作成手順については、「クラスターの作成」を参照してください。
  3. [すべて実行] をクリックします。
  4. ノートブックが実行している間待ちます。

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

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

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

  1. ノートブック名の横にある eda Git ブランチ ボタンをクリックします。
  2. [best-notebooks] ダイアログの [変更] タブで、notebooks/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 で pull request を作成し、その pull request を main ブランチにマージします。
  8. Azure Databricks ワークスペースに戻り、まだ表示されている場合は [best-notebooks] ダイアログを閉じます。

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

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

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

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

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

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

  1. ワークスペース ブラウザーで notebooks フォルダーを右クリックし、[インポート] をクリックします。
  2. [インポート] ダイアログで次の手順を実行します。

    1. [インポート元] で、[URL] を選択します。

    2. GitHub の covid_eda_modular リポジトリに databricks/notebook-best-practices ノートブックの生コンテンツへの URL を入力します。 この URL を取得する方法は次のとおりです。i. https://github.com/databricks/notebook-best-practices にアクセスします。 ii. notebooks フォルダーをクリックします。 iii. covid_eda_modular.py ファイルをクリックします。 iv. [Raw] (未加工) をクリックします。 .v Web ブラウザーのアドレス バーから [Import Notebooks] (ノートブックのインポート) ダイアログに完全な URL をコピーします。

      注意

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

    3. [インポート] をクリックします。

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

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

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

    注意

    パッケージの依存関係を列挙したファイルは、notebooks または 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

    注意

    上記のファイルには、特定のパッケージ バージョンが一覧表示されています。 互換性を向上させるために、これらのバージョンと、汎用クラスターにインストールされているバージョンを相互参照できます。 お使いのクラスターの 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. ワークスペース ブラウザーで notebooks フォルダー内の covid_eda_modular ノートブックをクリックします。
  2. このノートブックをアタッチするクラスターを選びます。
  3. [すべて実行] をクリックします。
  4. ノートブックが実行している間待ちます。

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

  1. ノートブック名の横にある first_modules Git ブランチ ボタンをクリックします。
  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 で pull request を作成し、その pull request を main ブランチにマージします。
  8. Azure Databricks ワークスペースに戻り、まだ表示されている場合は [best-notebooks] ダイアログを閉じます。

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

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

ヒント

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

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

  1. ノートブック名の横にある first_modules Git ブランチ ボタンをクリックします。
  2. [best-notebooks] ダイアログで、first_modules ブランチの横にあるドロップダウン矢印をクリックし、[main] を選びます。
  3. [プル] ボタンをクリックします。 プルの続行を求めるメッセージが表示されたら、[確認] をクリックします。
  4. [Create Branch] \(ブランチの作成\) をクリックします。
  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 パッケージをダウンロードして、ワークスペースにインストールし、テストを実行して、テストの結果を報告します。 クラスターの pytestから を実行できますが、ノートブックから pytest を実行する方が便利な場合があります。

注意

pytest を実行すると、現在のディレクトリとそのサブディレクトリで、test_*.py または /*_test.py の形式に従う名前が付けられたすべてのファイルが実行されます。

  1. ワークスペース ブラウザーで notebooks フォルダーを右クリックし、[インポート] をクリックします。
  2. [Import Notebooks] (ノートブックのインポート) ダイアログで、以下の手順を実行します。

    1. [インポート元] で、[URL] を選択します。

    2. GitHub の run_unit_tests リポジトリに databricks/notebook-best-practices ノートブックの生コンテンツへの URL を入力します。 この URL を取得する方法は次のとおりです。i. https://github.com/databricks/notebook-best-practices にアクセスします。 ii. notebooks フォルダーをクリックします。 iii. run_unit_tests.py ファイルをクリックします。 iv. [Raw] (未加工) をクリックします。 .v Web ブラウザーのアドレス バーから [Import Notebooks] (ノートブックのインポート) ダイアログに完全な 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
  1. ノートブック名の横にある first_tests Git ブランチ ボタンをクリックします。
  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 で pull request を作成し、その pull request を main ブランチにマージします。
  8. Azure Databricks ワークスペースに戻り、まだ表示されている場合は [best-notebooks] ダイアログを閉じます。

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

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

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

  1. ワークスペース サイドバーにある [ワークフロー] をクリックします。
  2. [ジョブ] タブで、[ジョブの作成] をクリックします。
  3. ジョブの名前を「covid_report」に編集します。
  4. [タスク名] に、「run_notebook_tests」と入力します。
  5. [種類] に、[ノートブック] を選択します。
  6. [ソース] で [Git プロバイダー] を選びます。
  7. [Add a git reference] (Git 参照の追加) をクリックします。
  8. [Git 情報] ダイアログで、以下の手順を実行します。
    1. [Git リポジトリ URL] に、お使いの GitHub リポジトリの GitHub [Clone with HTTPS] (HTTPS で複製する) URL を入力します。 この記事では、URL の末尾が best-notebooks.git であることを前提としています (例: https://github.com/<your-GitHub-username>/best-notebooks.git)。
    2. [Git プロバイダー] で、[GitHub] を選択します。
    3. [Git reference (branch / tag / commit)] (Git 参照 (ブランチ/タグ/コミット)) に、「main」と入力します。
    4. [Git reference (branch / tag / commit)] (Git 参照 (ブランチ/タグ/コミット)) の横で、[ブランチ] を選択します。
    5. [Confirm](確認) をクリックします。
  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. [依存先] の値が run_notebook-tests であることを確認します。
  8. [タスクの作成] をクリックします。

手順 5.3 ジョブを実行する

  1. [今すぐ実行] をクリックします。

  2. ポップアップで、[実行の表示] をクリックします。

    注意

    ポップアップの表示時間が短すぎる場合は、次の操作を行います。

    1. Data Science & Engineering または 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 にアクセス用の一意の Azure Databricks トークンを付与します。

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

重要

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

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

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

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

  1. お使いの GitHub リポジトリの Web サイトで、[コード] タブをクリックします。

  2. main の横にある矢印をクリックして、[ブランチまたはタグの切り替え] ドロップダウン リストを展開します。

  3. [Find or create a branch] (ブランチの検索または作成) ボックスに、「adding_github_actions」と入力します。

  4. [Create branch: adding_github_actions from ‘main’] (‘main’ からブランチ adding_github_actions を作成) をクリックします。

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

  6. [ファイル名を指定する] に、「.github/workflows/databricks_pull_request_tests.yml」と入力します。

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

  8. [変更をコミットする] をクリックします。

  9. [変更のコミット] ダイアログで Create databricks_pull_request_tests.yml に「」と入力します

  10. [adding_github_actions ブランチに直接コミットする] を選び、[変更のコミット] をクリックします。

  11. [コード] タブで、[Compare & pull request] (比較と pull request) をクリックし、pull request を作成します。

  12. [pull request] ページで、[Run pre-merge Databricks tests / unit-test-notebook (pull_request)] (マージ前の Databricks テスト / 単体テスト ノートブック (pull_request) の実行) の横にあるアイコンが緑色のチェック マークを表示するまで待ちます。 (アイコンが表示されるまでにしばらく時間がかかる場合があります)。緑色のチェック マークではなく赤い X がある場合は、[詳細] をクリックして理由を確認します。 アイコンまたは [詳細] が表示されなくなった場合は、[Show all checks] (すべてのチェックを表示) をクリックします。

  13. 緑色のチェック マークが表示されたら、pull request を main ブランチにマージします。

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

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

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

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

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

  1. ワークスペース ブラウザーの best-notebooks Git フォルダーで、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 プロバイダー上に pull request を作成する] の pull request リンクをクリックし、GitHub で pull request を作成します。
  7. [pull request] ページで、[Run pre-merge Databricks tests / unit-test-notebook (pull_request)] (マージ前の Databricks テスト / 単体テスト ノートブック (pull_request) の実行) の横にあるアイコンが緑色のチェック マークを表示するまで待ちます。 (アイコンが表示されるまでにしばらく時間がかかる場合があります)。緑色のチェック マークではなく赤い X がある場合は、[詳細] をクリックして理由を確認します。 アイコンまたは [詳細] が表示されなくなった場合は、[Show all checks] (すべてのチェックを表示) をクリックします。
  8. 緑色のチェック マークが表示されたら、pull request を main ブランチにマージします。