メインコンテンツまでスキップ

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

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

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

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

必要条件

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

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

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

ステップ 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という名前が付けられることもあります。その場合は、このチュートリアル全体を通してmainmasterに置き換えてください。

ヒント

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

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

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

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

注記

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

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

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

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

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

  • owid/covid-19-dataのGitHubリポジトリからCSVファイルをワークスペースのクラスターにコピーします。このCSVファイルには、COVID-19の入院状況と世界中の集中治療指標に関する公開データが含まれています。
  • CSVファイルの内容をpandas DataFrameに読み込みます。
  • 米国の指標のみが含まれるようにデータをフィルタリングします。
  • データのプロットを表示します。
  • pandas DataFrameをSpark DataFramePandas 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 でのみ機能します。

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

手順 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でのみ機能します。

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

ステップ 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 フォルダーのルートに配置する必要があります。

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

  2. 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の代わりにDZAiso_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でのみ機能します。

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

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

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

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

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

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

├── 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 を含む最新ジョブの「 開始時刻 」値をクリックします。

  1. ジョブ結果を見るには、 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ブランチにマージします。