Visual Studio Code で dbx を使用する

[アーティクル]
08/02/2024

重要

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

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

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

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

コード補完
リンティング
テスト
リモートの Azure Databricks リソースへのリアルタイム接続を必要としないコードオブジェクトのデバッグ。

この記事では、Databricks Labs による dbx と Visual Studio Code を使用して、リモートの Azure Databricks ワークスペースにコードサンプルを送信します。 dbx からの指示により、Azure Databricks では送信されたコードを、そのワークスペース内の Azure Databricks ジョブクラスター上で実行するために、ワークフローをスケジュールおよび調整します。

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

GitHub
Bitbucket
GitLab
Azure DevOps (Azure China リージョンでは利用できません)
AWS CodeCommit
GitHub AE

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

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

コードサンプルの要件

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

Azure Databricks アカウント内の Azure Databricks ワークスペース。ワークスペースがまだない場合は、ワークスペースを作成します。
GitHub アカウント。アカウントがまだない場合は、GitHub アカウントを作成します。

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

Python バージョン 3.8 以降。

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

ローカルコンピューターで現在参照されている Python のバージョンを取得するには、ローカルターミナルから python --version を実行します。 (ローカルコンピューターで Python を設定する方法によっては、この記事の python ではなく python3 の実行が必要になる場合があります。)「Python インタープリターを選択する」も参照してください。
pip。 pip は、新しいバージョンの Python で自動的にインストールされます。 pip が既にインストールされているかどうかを確認するには、ローカルターミナルから pip --version を実行します。 (ローカルコンピューターで Python や pip を設定する方法によっては、この記事の pip ではなく pip3 の実行が必要になる場合があります。)
dbx バージョン 0.8.0 以上。 pip install dbx を実行することで、Python パッケージインデックス (PyPI) から dbx パッケージをインストールできます。

注意

今すぐ dbx をインストールする必要はありません。後でコードサンプルの [セットアップ] セクションでインストールできます。
Python 仮想環境を作成して、dbx プロジェクトで正しいバージョンの Python とパッケージの依存関係を使用していることを確認します。この記事では、pipenv について説明しています。
Databricks CLI バージョン 0.18 以前では、認証を使って設定します。

Note

レガシ 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 リポジトリで入手でき、次の処理を行います。

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

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

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

注意

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

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

ターミナルから、このコードサンプルの仮想環境を含む空のフォルダーを作成します。この手順では、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 .
```
Visual Studio Code のメニューバーで、[ビュー] > [ターミナル] の順にクリックします。
ide-demo フォルダーのルートから、次のオプションを使用して pipenv コマンドを実行します。ここで <version> は、既にローカルにインストールされている Python のターゲットバージョン (理想的には、ターゲットクラスターの Python のバージョンに一致するバージョン) です (たとえば 3.8.14)。
```
pipenv --python <version>
```
次の手順で必要になるため、pipenv コマンドの出力の Virtualenv location 値を書き留めます。
ターゲットの Python インタープリターを選択し、Python 仮想環境をアクティブにします。
1. メニューバーで、[ビュー] > [コマンドパレット] の順にクリックし、Python: Select を入力し、次に [Python: インタープリターを選択する] をクリックします。
2. 先ほど作成した Python 仮想環境へのパス内で Python インタープリターを選択します (このパスは、pipenv コマンドの出力の Virtualenv location 値として一覧表示されます)。
3. メニューバーで、[ビュー] > [コマンドパレット] の順にクリックし、Terminal: Create を入力し、次に [ターミナル: 新しいターミナルの作成] をクリックします。
4. コマンドプロンプトで、pipenv シェル内にいることを確認します。確認のため、コマンドプロンプトの前に (<your-username>) のようなものが表示されます。表示されない場合は、次のコマンドを実行します。
```
pipenv shell
```
  pipenv シェルを終了する場合にはコマンド exit を実行すると、かっこが消えます。
詳細については、Visual Studio Code ドキュメントの「VS Code での Python 環境の使用」を参照してください。

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

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

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

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

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

# Or ...
python -m pip install dbx --upgrade
dbx --version
```
dbx をインストールすると、レガシ Databricks CLI (Databricks CLI バージョン 0.17) も自動的にインストールされます。レガシ Databricks CLI (Databricks CLI バージョン 0.17) がインストールされていることを確認するには、次のコマンドを実行します。
```
databricks --version
```
Databricks CLI バージョン 0.17 が返された場合、レガシ Databricks CLI がインストールされています。
認証でレガシ Databricks CLI (Databricks CLI バージョン 0.17) を設定していない場合、今すぐ設定する必要があります。認証が設定されていることを確認するには、次の基本コマンドを実行して、Azure Databricks ワークスペースの概要情報を取得します。 ls サブコマンドの後に必ずスラッシュ (/) を含めてください。
```
databricks workspace ls /
```
ワークスペースのルートレベルのフォルダー名の一覧が返された場合は、認証が設定されています。
このコードサンプルが依存する Python パッケージをインストールします。これを行うには、ide-demo/ide-best-practices フォルダーから次のコマンドを実行します。
```
pip install -r unit-requirements.txt
```
コードサンプルの依存パッケージがインストールされていることを確認します。そのためには、次のコマンドを実行します。
```
pip list
```
requirements.txt にリストされているパッケージと unit-requirements.txt ファイルがこのリストのどこかにある場合は、依存パッケージがインストールされています。

注意

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

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

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

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 ドキュメントの YAML の例を参照してください。

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

コードサンプルを設定した後、次の情報を使用して、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 ドキュメントの「pytest.iniと構成オプション」を参照してください。

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

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

梱包

この 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 を使用して実行する

dbx プロジェクトのルート (ide-demo/ide-best-practices フォルダーなど) から次のコマンドを実行して、Python setuptools 開発モードで covid_analysis フォルダーの内容をパッケージとしてインストールします。このコマンドの末尾のドット (.) を忘れずに含めてください。
```
pip install -e .
```
このコマンドは、covid_analysis/__init__.py のコンパイル済みバージョンと covid_analysis/transforms.py ファイルに関する情報を含む covid_analysis.egg-info フォルダーを作成します。
次のコマンドを実行して、テストを実行します。
```
pytest tests/
```
テストの結果がターミナルに表示されます。 4 つのテストがすべて合格と表示される必要があります。

ヒント

R ノートブックと Scala ノートブックのテストなど、テストのその他の方法については、ノートブックの単体テストに関するページを参照してください。
必要に応じて、次のコマンドを実行して、テストのテストカバレッジメトリックを取得します。
```
coverage run -m pytest tests/
```
注意

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

テストカバレッジの結果を表示するには、次のコマンドを実行します。
```
coverage report -m
```
4 つのテストにすべて合格した場合は、次のコマンドを実行して、dbx プロジェクトの内容を Azure Databricks ワークスペースに送信します。
```
dbx deploy --environment=default
```
プロジェクトとその実行に関する情報は、.dbx/project.json ファイル内の workspace_directory オブジェクトで指定された場所に送信されます。

プロジェクトの内容は、.dbx/project.json ファイル内の artifact_location オブジェクトで指定された場所に送信されます。
次のコマンドを実行して、ワークスペースで実稼働前バージョンのコードを実行します。
```
dbx launch covid_analysis_etl_integ
```
実行結果へのリンクがターミナルに表示されます。これは、次のようになります。
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
```
Web ブラウザーのこのリンクをたどって、実行結果をワークスペースに表示します。
次のコマンドを実行して、ワークスペースでコードの実稼働バージョンを実行します。
```
dbx launch covid_analysis_etl_prod
```
実行結果へのリンクがターミナルに表示されます。これは、次のようになります。
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
```
Web ブラウザーのこのリンクをたどって、実行結果をワークスペースに表示します。

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

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

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 ワークスペースを設定します。これには、次のアクションが含まれます。

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

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

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

GitHub Actions を実行する

手順 1: 複製したリポジトリを公開する

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

手順 2: 暗号化されたシークレットをリポジトリに追加する

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

https://adb-1234567890123456.7.azuredatabricks.net など、ワークスペースごとの URL の値に設定された、DATABRICKS_HOST という名前の暗号化されたシークレットを作成します。
サービスプリンシパルの Microsoft Entra ID トークンの値に設定された、DATABRICKS_TOKEN という名前の暗号化されたシークレットを作成します。

手順 3: リポジトリにブランチを作成して公開する

Visual Studio Code の[ソース管理] ビュー ([ビュー] > [ソース管理]) で、...([ビューと他のアクション]) アイコンをクリックします。
[ブランチ] > [次からブランチを作成] の順にクリックします。
ブランチの名前を入力します (例: my-branch)。
ブランチの作成元のブランチ (例: main) を選択します。
ローカルリポジトリ内のいずれかのファイルを少し変更し、ファイルを保存します。たとえば、tests/transforms_test.py ファイル内のコードコメントを少し変更します。
[ソース管理] ビューで、もう一度 […] ([ビューと他のアクション]) アイコンをクリックします。
[変更] > [すべての変更をステージする] の順にクリックします。
もう一度 […] ([ビューと他のアクション]) アイコンをクリックします。
[コミット] > [ステージング済みをコミット] の順にクリックします。
コミットのメッセージを入力します。
もう一度 […] ([ビューと他のアクション]) アイコンをクリックします。
[ブランチ] > [ブランチの公開] の順にクリックします。

手順 4: pull request を作成してマージする

公開したリポジトリ https://github/<your-GitHub-username>/ide-best-practices の GitHub Web サイトに移動します。
[Pull requests] タブで、my-branch had recent pushes の横の [比較 & pull request] をクリックします。
[Pull request の作成] をクリックします。
pull request ページで、CI pipleline/ci-pipeline (push) の横にあるアイコンが緑色のチェックマークに変わるまで待ちます。 (アイコンが表示されるまでに数分かかる場合があります)。緑色のチェックマークではなく赤い X がある場合は、[詳細] をクリックして理由を確認します。アイコンまたは [詳細] が表示されなくなった場合は、[すべてのチェックを表示] をクリックします。
緑色のチェックマークが表示されたら、[pull request のマージ] をクリックして、pull request を main ブランチにマージします。

次の方法で共有

Visual Studio Code で dbx を使用する

コードサンプルの要件

コードサンプルについて

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

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

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

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

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

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

コードのモジュール化

変更されていないコード

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

テスト

単体テスト

単体テストランナー

梱包

他のファイル

コードサンプルの実行

dbx を使用して実行する

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

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

GitHub Actions を実行する

手順 1: 複製したリポジトリを公開する

手順 2: 暗号化されたシークレットをリポジトリに追加する

手順 3: リポジトリにブランチを作成して公開する

手順 4: pull request を作成してマージする

フィードバック

その他のリソース

次の方法で共有

Visual Studio Code で dbx を使用する

コード サンプルの要件

コード サンプルについて

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

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

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

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

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

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

コードのモジュール化

変更されていないコード

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

テスト

単体テスト

単体テスト ランナー

梱包

他のファイル

コード サンプルの実行

dbx を使用して実行する

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

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

GitHub Actions を実行する

手順 1: 複製したリポジトリを公開する

手順 2: 暗号化されたシークレットをリポジトリに追加する

手順 3: リポジトリにブランチを作成して公開する

手順 4: pull request を作成してマージする

フィードバック

その他のリソース

コードサンプルの要件

コードサンプルについて

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

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

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

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

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

単体テストランナー

コードサンプルの実行