次の方法で共有

Visual Studio Code で dbx を使用する

重要

このドキュメントは廃止され、更新されない可能性があります。

Databricks では、Databricks Labs の dbx ではなく、Databricks アセット バンドルを使用することが推奨されています。 「Databricks アセット バンドルとは?」と「dbx からバンドルへの移行」参照してください。

Visual Studio Code で Azure Databricks を使用するには、Visual Studio Code 用の Databricks 拡張機能に関する記事をご覧ください。

この記事では、Python と互換性がある任意の IDE で操作できる Python ベースのコード サンプルについて説明します。 具体的には、この記事では、次の開発者の生産性特徴を提供する Visual Studio Code でこのコード サンプルを操作する方法について説明します。

この記事では、Databricks Labs による dbx と Visual Studio Code を使用して、リモートの Azure Databricks ワークスペースにコード サンプルを送信します。 dbxは、そのワークスペース内の Azure Databricks ジョブ クラスターで送信されたコードを実行するように Azure Databricks に Lakeflow ジョブに指示します。

一般的なサード パーティの Git プロバイダーを使用して、コードのバージョン管理と継続的インテグレーションと継続的デリバリー、継続的デプロイ (CI/CD) を行うことができます。 バージョン コントロールの場合、これらの Git プロバイダーには次のものが含まれます。

CI/CD の場合、dbx では次の CI/CD プラットフォームがサポートされます。

バージョン コントロールと CI/CD のしくみを示すために、この記事では、Visual Studio Code dbx の使用方法と、このコード サンプル、および GitHub と GitHub Actions について説明します。

コード サンプルの要件

このコード サンプルを使用するには、次のものが必要です。

さらに、ローカル開発マシンに次のものがある必要があります。

  • Python バージョン 3.8 以降。

    ターゲット クラスターにインストールされているバージョンと一致するバージョンの Python を使用する必要があります。 既存のクラスターにインストールされている Python のバージョンを取得するには、クラスターの Web ターミナル を使用して python --version コマンドを実行します。 ターゲット クラスターの Databricks Runtime バージョンについては、Databricks Runtime リリース ノートのバージョンと互換性」の「システム環境」セクションも参照してください。 いずれの場合も、Python のバージョンは 3.8 以降である必要があります。

    ローカル コンピューターで現在参照されている Python のバージョンを取得するには、ローカル ターミナルから python --version を実行します。 (ローカル コンピューターで Python を設定する方法によっては、この記事の python3 ではなく python の実行が必要になる場合があります。)「Python インタープリターを選択する」も参照してください。

  • pip。 pip は、新しいバージョンの Python で自動的にインストールされます。 pip が既にインストールされているかどうかを確認するには、ローカル ターミナルから pip --version を実行します。 (ローカル コンピューターで Python や pip を設定する方法によっては、この記事の pip3 ではなく pip の実行が必要になる場合があります。)

  • dbx バージョン 0.8.0 以上。 dbx を実行することで、Python パッケージ インデックス (PyPI) から pip install dbx パッケージをインストールできます。

    注意

    今すぐ dbx をインストールする必要はありません。 後でコード サンプルの [セットアップ] セクションでインストールできます。

  • Python 仮想環境を作成して、dbx プロジェクトで正しいバージョンの Python とパッケージの依存関係を使用していることを確認します。 この記事では、pipenv について説明しています。

  • Databricks CLI バージョン 0.18 以前では、認証を使って設定します。

    注意

    レガシ Databricks CLI (Databricks CLI バージョン 0.17) をここでインストールする必要はありません。 後でコード サンプルの [セットアップ] セクションでインストールできます。 後でインストールする場合は、代わりにその時点で認証を設定する必要があります。

  • Visual Studio Code。

  • Visual Studio Code 用の Python 拡張機能。

  • Visual Studio Code 用の GitHub Pull Requests and Issues 拡張機能。

  • Git。

コード サンプルについて

この記事の Python コード サンプルは、GitHubの databricks/ide-best-practices リポジトリで入手でき、次の処理を行います。

  1. GitHub の owid/covid-19-data リポジトリからデータを取得します。
  2. 特定の ISO 国番号のデータをフィルター処理します。
  3. データからピボット テーブルを作成します。
  4. データに対してデータ クレンジングを実行します
  5. コード ロジックを再利用可能な関数にモジュール化します。
  6. 関数を単体テストします。
  7. リモート Azure Databricks ワークスペースの Delta テーブルにデータを書き込むコードを有効にするプロジェクト構成と設定を dbx に入力します。

コード サンプルを設定します。

このコード サンプルの要件を満たしたら、次の手順を実行してコード サンプルの使用を開始します。

注意

これらの手順には、CI/CD 用のこのコード サンプルの設定は含まれません。 このコード サンプルを実行するために CI/CD を設定する必要はありません。 後で CI/CD を設定する場合は、「GitHub Actions で実行する」を参照してください。

手順 1: Python 仮想環境を作成する

  1. ターミナルから、このコード サンプルの仮想環境を含む空のフォルダーを作成します。 この手順では、ide-demo という名前の親フォルダーを使用します。 このフォルダーには任意の名前を付けることができます。 別の名前を使用する場合は、この記事に出てくる名前を置き換えます。 フォルダーを作成したら、そこに切り替えて、そのフォルダーから Visual Studio Code を開始します。 . コマンドの後には必ずドット (code) を含めてください。

    Linux および macOS の場合:

    mkdir ide-demo
cd ide-demo
code .

    ヒント

    エラー command not found: code が表示される場合は、Microsoft Web サイトの「コマンド ラインからの起動」を参照してください。

    Windows の場合:

    md ide-demo
cd ide-demo
code .

  2. Visual Studio Code のメニュー バーで、[ビュー] > [ターミナル] の順にクリックします。

  3. ide-demo フォルダーのルートから、次のオプションを使用して pipenv コマンドを実行します。ここで、<version>は、既にローカルにインストールされている Python のターゲット バージョン (および、ターゲット クラスターの Python のバージョンに一致するバージョン) です (たとえば、3.8.14)。

    pipenv --python <version>

    次の手順で必要になるため、Virtualenv location コマンドの出力の pipenv 値を書き留めます。

  4. ターゲットの Python インタープリターを選択し、Python 仮想環境をアクティブにします。

    1. メニュー バーで、[ビュー] > [コマンド パレット] の順にクリックし、Python: Select を入力し、次に [Python: インタープリターを選択する] をクリックします。

    2. 先ほど作成した Python 仮想環境へのパス内で Python インタープリターを選択します (このパスは、Virtualenv location コマンドの出力の pipenv 値として一覧表示されます)。

    3. メニュー バーで、[ビュー] > [コマンド パレット] の順にクリックし、Terminal: Create を入力し、次に [ターミナル: 新しいターミナルの作成] をクリックします。

    4. コマンド プロンプトで、pipenv シェル内にいることを確認します。 確認のため、コマンド プロンプトの前に (<your-username>) のようなものが表示されます。 表示されない場合は、次のコマンドを実行します。

      pipenv shell

      pipenv シェルを終了する場合にはコマンド exit を実行すると、かっこが消えます。

    詳細については、Visual Studio Code ドキュメントの「VS Code での Python 環境の使用」を参照してください。

手順 2: GitHub からコード サンプルを複製する

  1. Visual Studio Code で、まだ開いていない場合は、ide-demo フォルダー ([ファイル] > [フォルダーを開く]) を開きます。
  2. [表示] > [コマンド パレットの表示] の順にクリックして Git: Clone を入力し、[Git: 複製] をクリックします。
  3. リポジトリ URL を指定するか、リポジトリ ソースを選択するには、https://github.com/databricks/ide-best-practices を入力します
  4. ide-demo フォルダーを参照し、[リポジトリの場所の選択] をクリックします。

手順 3: コード サンプルの依存関係をインストールする

  1. お使いのバージョンの Python と互換性のあるバージョンの dbx と Databricks CLI バージョン 0.18 以前をインストールします。 これを行うには、ターミナルの Visual Studio Code で、ide-demo シェルがアクティブ化された pipenv フォルダー (pipenv shell) から次のコマンドを実行します。

    pip install dbx

  2. dbx がインストールされていることを確認します。 そのためには、次のコマンドを実行します。

    dbx --version

    バージョン番号が返された場合は、dbx がインストールされています。

    バージョン番号が 0.8.0 未満の場合は、次のコマンドを実行して dbx をアップグレードし、バージョン番号をもう一度検査します。

    pip install dbx --upgrade
dbx --version

# Or ...
python -m pip install dbx --upgrade
dbx --version

  3. dbx をインストールすると、レガシ Databricks CLI (Databricks CLI バージョン 0.17) も自動的にインストールされます。 レガシ Databricks CLI (Databricks CLI バージョン 0.17) がインストールされていることを確認するには、次のコマンドを実行します。

    databricks --version

    Databricks CLI バージョン 0.17 が返された場合、レガシ Databricks CLI がインストールされています。

  4. 認証でレガシ Databricks CLI (Databricks CLI バージョン 0.17) を設定していない場合、今すぐ設定する必要があります。 認証が設定されていることを確認するには、次の基本コマンドを実行して、Azure Databricks ワークスペースの概要情報を取得します。 / サブコマンドの後に必ずスラッシュ (ls) を含めてください。

    databricks workspace ls /

    ワークスペースのルート レベルのフォルダー名の一覧が返された場合は、認証が設定されています。

  5. このコード サンプルが依存する Python パッケージをインストールします。 これを行うには、ide-demo/ide-best-practices フォルダーから次のコマンドを実行します。

    pip install -r unit-requirements.txt

  6. コード サンプルの依存パッケージがインストールされていることを確認します。 そのためには、次のコマンドを実行します。

    pip list

    requirements.txt にリストされているパッケージと unit-requirements.txt ファイルがこのリストのどこかにある場合は、依存パッケージがインストールされています。

    注意

    requirements.txt にリストされているファイルは、特定のパッケージ バージョン用です。 互換性を高めるために、これらのバージョンを、後でデプロイを実行するために Azure Databricks ワークスペースで使用するクラスター ノードの種類と相互参照できます。 Databricks Runtime リリース ノートのバージョンと互換性については、クラスターの Databricks Runtime バージョンの「システム環境」セクションを参照してください。

手順 4: Azure Databricks ワークスペースのコード サンプルをカスタマイズする

  1. リポジトリの dbx プロジェクト設定をカスタマイズします。 これを行うには、.dbx/project.json ファイル内の profile オブジェクトの値を DEFAULT から、レガシ Databricks CLI (Databricks CLI バージョン 0.17) を使用して認証用に設定したものと一致するプロファイルの名前に変更します。 既定以外のプロファイルを設定していない場合は、DEFAULT をそのままにしておきます。 次に例を示します。

    {
  "environments": {
    "default": {
      "profile": "DEFAULT",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/covid_analysis",
        "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
      }
    }
  },
  "inplace_jinja_support": false
}

  2. dbx プロジェクトの配置設定をカスタマイズします。 これを行うには、conf/deployment.yml ファイルの spark_version および node_type_id オブジェクトの値を、10.4.x-scala2.12 および m6gd.large から、Azure Databricks ワークスペースでデプロイの実行に使用する Azure Databricks ランタイム バージョン文字列とクラスター ノードの型に変更します。

    たとえば、Databricks Runtime 10.4 LTS と Standard_DS3_v2 ノードの型を指定するには、次のようにします。

    environments:
  default:
    workflows:
      - name: 'covid_analysis_etl_integ'
        new_cluster:
          spark_version: '10.4.x-scala2.12'
          num_workers: 1
        node_type_id: 'Standard_DS3_v2'
        spark_python_task:
          python_file: 'file://jobs/covid_trends_job.py'
      - name: 'covid_analysis_etl_prod'
        new_cluster:
          spark_version: '10.4.x-scala2.12'
          num_workers: 1
          node_type_id: 'Standard_DS3_v2'
          spark_python_task:
            python_file: 'file://jobs/covid_trends_job.py'
          parameters: ['--prod']
      - name: 'covid_analysis_etl_raw'
        new_cluster:
          spark_version: '10.4.x-scala2.12'
          num_workers: 1
          node_type_id: 'Standard_DS3_v2'
          spark_python_task:
            python_file: 'file://jobs/covid_trends_job_raw.py'

ヒント

この例では、これら 3 つのジョブ定義には同じ spark_version 値と node_type_id 値があります。 ジョブ定義ごとに異なる値を使用できます。 また、共有値を作成し、ジョブ定義間で再利用して、入力エラーやコード メンテナンスの手間を減らすこともできます。 ドキュメントの dbx の例を参照してください。

コード サンプルを検証する

コード サンプルを設定した後、次の情報を使用して、ide-demo/ide-best-practices フォルダー内のさまざまなファイルがどのように動作するかを確認します。

コードのモジュール化

変更されていないコード

jobs/covid_trends_job_raw.py ファイルは、コード ロジックの変更されていないバージョンです。 このファイルは単独で実行できます。

モジュール化されているコード

jobs/covid_trends_job.py ファイルはモジュール化されているコード ロジックのバージョンです。 このファイルは、covid_analysis/transforms.py ファイル内の共有コードに依存します。 covid_analysis/__init__.py ファイルは covide_analysis フォルダーを、パッケージを含むものとして扱います。

テスト

単体テスト

この tests/testdata.csv ファイルには、テスト目的で covid-hospitalizations.csv ファイル内の少量のデータが含まれています。 tests/transforms_test.py ファイルには、covid_analysis/transforms.py ファイルの単体テストが含まれています。

単体テスト ランナー

この pytest.ini ファイルには、pytest を使用してテストを実行するための構成オプションが含まれています。 ドキュメントの「pytest.iniとpytest」を参照してください。

この .coveragerc ファイルには、coverage.py を使用した Python コード カバレッジ測定の構成オプションが含まれています。 ドキュメントの「coverage.py」を参照してください。

前に requirements.txt を使用して実行した unit-requirements.txt ファイルのサブセットである pip ファイルには、単体テストも依存するパッケージの一覧が含まれています。

梱包

この setup.py ファイルには、pip コマンドなど、コンソールで実行するコマンド (コンソール スクリプト) が用意されています。このコマンドでは、Python プロジェクトを setuptools でパッケージ化します。 ドキュメントの「setuptools」を参照してください。

他のファイル

このコード サンプルには、前に説明していない他のファイルがあります。

  • .github/workflows フォルダーには、GitHub Actions を表す 3 つのファイルである databricks_pull_request_tests.yml、onpush.yml、および onrelease.yaml が含まれています。このファイルについては、後の GitHub Actions セクションで説明します。
  • この .gitignore ファイルには、Git がリポジトリに対して無視するローカル フォルダーとファイルの一覧が含まれています。

コード サンプルの実行

次のサブセクションで説明されているように、dbx をローカル コンピューターで使用して、リモート ワークスペースでコード サンプルをオンデマンドで実行するように Azure Databricks に指示できます。 または、GitHub Actions を使用して、コードの変更を GitHub リポジトリにプッシュするたびに GitHub にコード サンプルを実行させることができます。

dbx を使用して実行する

  1. covid_analysis プロジェクトのルート (setuptools フォルダーなど) から次のコマンドを実行して、Python dbxで ide-demo/ide-best-practices フォルダーの内容をパッケージとしてインストールします。 このコマンドの末尾のドット (.) を忘れずに含めてください。

    pip install -e .

    このコマンドは、covid_analysis.egg-info のコンパイル済みバージョンと covid_analysis/__init__.py ファイルに関する情報を含む covid_analysis/transforms.py フォルダーを作成します。

  2. 次のコマンドを実行して、テストを実行します。

    pytest tests/

    テストの結果がターミナルに表示されます。 4 つのテストがすべて合格と表示される必要があります。

    ヒント

    R ノートブックと Scala ノートブックのテストなど、テストのその他の方法については、ノートブックの単体テストに関するページを参照してください。

  3. 必要に応じて、次のコマンドを実行して、テストのテスト カバレッジ メトリックを取得します。

    coverage run -m pytest tests/

    注意

    coverage が見つからないというメッセージが表示された場合は、pip install coverage を実行して、もう一度やり直してください。

    テスト カバレッジの結果を表示するには、次のコマンドを実行します。

    coverage report -m

  4. 4 つのテストがすべて成功した場合は、次のコマンドを実行して、 dbx プロジェクトの内容を Azure Databricks ワークスペースに送信します。

    dbx deploy --environment=default

    プロジェクトとその実行に関する情報は、workspace_directory ファイル内の .dbx/project.json オブジェクトで指定された場所に送信されます。

    プロジェクトの内容は、artifact_location ファイル内の.dbx/project.json オブジェクトで指定された場所に送信されます。

  5. 次のコマンドを実行して、ワークスペースで実稼働前バージョンのコードを実行します。

    dbx launch covid_analysis_etl_integ

    実行の結果へのリンクがターミナルに表示されます。 これは、次のようになります。

    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345

    Web ブラウザーで次のリンクに従って、実行の結果をワークスペースに表示します。

  6. 次のコマンドを実行して、ワークスペースでコードの実稼働バージョンを実行します。

    dbx launch covid_analysis_etl_prod

    実行の結果へのリンクがターミナルに表示されます。 これは、次のようになります。

    https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456

    Web ブラウザーで次のリンクに従って、実行の結果をワークスペースに表示します。

GitHub Actions を使用してスキャンする

プロジェクトの .github/workflows フォルダーで、 onpush.yml ファイルと GitHub Actions ファイル onrelease.yml 次の操作を行います。

  • v で始まるタグへのプッシュごとに、dbx を使用して covid_analysis_etl_prod ジョブをデプロイします。
  • 各プッシュは、v で始まるタグに対しては行われません。
    1. pytest を使用して単体テストを実行します。
    2. dbx を使用して、covid_analysis_etl_integ ジョブで指定されたファイルをリモート ワークスペースにデプロイします。
    3. dbx を使用して、リモート ワークスペース上の covid_analysis_etl_integ ジョブで指定されている既にデプロイされているファイルを起動し、完了するまでこの実行をトレースします。

注意

追加の GitHub Actions ファイルである databricks_pull_request_tests.yml は、onpush.yml および onrelease.yml の GitHub Actions ファイルに影響を与えることなく、実験のためのテンプレートとして提供されます。 このコード サンプルは、databricks_pull_request_tests.yml GitHub Actions ファイルなしで実行できます。 その使用法はこの記事では扱われていません。

次のサブセクションでは、onpush.yml および onrelease.yml の GitHub Actions ファイルをセットアップして実行する方法について説明します。

GitHub Actions を使用するように設定する

CI/CD のサービス プリンシパルの手順に従って、Azure Databricks ワークスペースを設定します。 これには、次のアクションが含まれます。

  1. サービス プリンシパルを作成する。
  2. サービス プリンシパルの Microsoft Entra ID トークンを作成します。

Databricks は、セキュリティのベスト プラクティスとして、GitHub を Azure Databricks ワークスペースで認証するために、ワークスペース ユーザーの Databricks 個人用アクセス トークンではなく、サービス プリンシパルの Microsoft Entra ID トークンを使用することを推奨しています。

サービス プリンシパルとその Microsoft Entra ID トークンを作成したら、作業を止めて、次のセクションで使用する Microsoft Entra ID トークンの値をメモします。

GitHub Actions を実行する

手順 1: 複製したリポジトリを公開する
  1. Visual Studio Code のサイドバーで、GitHub アイコンをクリックします。 アイコンが表示されない場合は、最初に [拡張機能] ビュー (拡張機能の表示) を使用して >GitHub Pull Requests and Issues 拡張機能を有効にします。
  2. [サインイン] ボタンが表示されている場合は、それをクリックし、画面の指示に従って GitHub アカウントにサインインします。
  3. メニュー バーで、[ビュー] > [コマンド パレット] の順にクリックし、Publish to GitHub を入力し、次に [GitHub に公開する] をクリックします。
  4. 複製したリポジトリを GitHub アカウントに公開するオプションを選択します。
手順 2: 暗号化されたシークレットをリポジトリに追加する

次の暗号化されたシークレットについては、公開したリポジトリの GitHub Web サイトのリポジトリの暗号化されたシークレットの作成に関するページの手順に従います。

  • DATABRICKS_HOST など、ワークスペースごとの URL の値に設定された、https://adb-1234567890123456.7.azuredatabricks.net という名前の暗号化されたシークレットを作成します。
  • サービス プリンシパルの Microsoft Entra ID トークンの値に設定された、DATABRICKS_TOKEN という名前の暗号化されたシークレットを作成します。
手順 3: リポジトリにブランチを作成して公開する
  1. Visual Studio Code の[ソース管理] ビュー ([ビュー] > [ソース管理]) で、...([ビューと他のアクション]) アイコンをクリックします。
  2. [ブランチ] > [次からブランチを作成] の順にクリックします。
  3. ブランチの名前を入力します (例: my-branch)。
  4. ブランチの作成元のブランチ (例: main) を選択します。
  5. ローカル リポジトリ内のいずれかのファイルを少し変更し、ファイルを保存します。 たとえば、tests/transforms_test.py ファイル内のコード コメントを少し変更します。
  6. [ソース管理] ビューで、もう一度 […] ([ビューと他のアクション]) アイコンをクリックします。
  7. [変更] > [すべての変更をステージする] の順にクリックします。
  8. もう一度 […] ([ビューと他のアクション]) アイコンをクリックします。
  9. [コミット] > [ステージング済みをコミット] の順にクリックします。
  10. コミットのメッセージを入力します。
  11. もう一度 […] ([ビューと他のアクション]) アイコンをクリックします。
  12. [ブランチ] > [ブランチの公開] の順にクリックします。
手順 4: pull request を作成してマージする
  1. 公開したリポジトリ https://github/<your-GitHub-username>/ide-best-practices の GitHub Web サイトに移動します。
  2. [Pull requests] タブで、my-branch had recent pushes の横の [比較 & pull request] をクリックします。
  3. [Pull request の作成] をクリックします。
  4. pull request ページで、CI pipleline/ci-pipeline (push) の横にあるアイコンが緑色のチェック マークに変わるまで待ちます。 (アイコンが表示されるまでに数分かかる場合があります)。緑色のチェック マークではなく赤い X がある場合は、[詳細] をクリックして理由を確認します。 アイコンまたは [詳細] が表示されなくなった場合は、[すべてのチェックを表示] をクリックします。
  5. 緑色のチェック マークが表示されたら、main をクリックして、pull request を ブランチにマージします。
  • Last updated on