Visual Studio Code で dbx を使用する

重要

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

Databricks では、Databricks Labs の dbx ではなく、Databricks アセット バンドルを使用することをお勧めします。 Databricks アセットバンドルとはおよびdbx からバンドルへの移行を参照してください。

Visual Studio Code で Databricks を使用するには、「 Visual Studio Code の Databricks 拡張機能」の記事を参照してください。

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

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

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

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

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

CI/CD の場合、 dbx は次の CI/CD プラットフォームをサポートします。

• GitHub Actions
• Azure パイプライン
• GitLabのCI/CD

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

コード サンプルの要件

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

• Databricks アカウント内の 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 以降。 Python Package Index (PyPI) から dbx パッケージをインストールするには、 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. コードがリモート Databricks ワークスペースの Delta テーブルにデータを書き込むことができるように、 dbx プロジェクト構成と設定を提供します。

コード サンプルを設定する

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

注記

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

ステップ 1: Python 仮想環境を作成する

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

   LinuxまたはmacOSの場合：

   Bash

   mkdir ide-demo
   cd ide-demo
   code .

ヒント

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

Windowsの場合：

PowerShell

md ide-demo
cd ide-demo
code .

2. Visual Studio Code のメニュー バーで、 表示 > ターミナル をクリックします。

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

   Bash

   pipenv --python <version>

   次のステップで必要になるため、 pipenv コマンドの出力にある Virtualenv location の値をメモしておきます。

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

   1. メニューバーで [表示] > [コマンドパレット] をクリックし、Python: Select と入力して [Python：インタープリターの選択] をクリックします。

   2. 作成したばかりのPython仮想環境へのパス内でPythonインタープリターを選択します。（このパスは、 pipenv コマンドの出力に Virtualenv location 値としてリストされます。）

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

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

      Bash

      pipenv shell

      pipenvシェルを終了するには、コマンド を exit実行すると、括弧が消えます。

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

ステップ 2: GitHub からコード サンプルを複製する

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

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

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

   Bash

   pip install dbx

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

   Bash

   dbx --version

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

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

   Bash

   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) がインストールされていることを確認するには、次のコマンドを実行します。

   Bash

   databricks --version

   Databricks CLI バージョン 0.17 が返された場合は、従来の Databricks CLI がインストールされます。

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

   Bash

   databricks workspace ls /

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

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

   Bash

   pip install -r unit-requirements.txt

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

   Bash

   pip list

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

注記

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

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

1. リポジトリの dbx プロジェクト設定をカスタマイズします。これを行うには、 .dbx/project.json ファイルで、 profile オブジェクトの値を DEFAULT から、従来の Databricks CLI (Databricks CLI バージョン 0.17) で認証用に設定したプロファイルの名前に変更します。デフォルト以外のプロファイルを設定しなかった場合は、 DEFAULT そのままにしておきます。例えば：

   JSON

   {
     "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.largeDatabricksこれを行うには、 Databricksファイルで、 オブジェクトと オブジェクトの値を と から、 ワークスペースでデプロイの実行に使用する ランタイム バージョンの文字列 と クラスター ノード タイプ に変更します。

   たとえば、Databricks Runtime 10.4 LTS と i3.xlarge ノードの種類を指定するには、次のようにします。

   YAML

   environments:
     default:
       workflows:
         - name: 'covid_analysis_etl_integ'
           new_cluster:
             spark_version: '10.4.x-scala2.12'
             num_workers: 1
           node_type_id: 'i3.xlarge'
           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: 'i3.xlarge'
             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: 'i3.xlarge'
             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 ドキュメントの設定リファレンスを参照してください。

requirements.txt ファイルは、以前に pipで実行した unit-requirements.txt ファイルのサブセットであり、ユニット・テストも依存するパッケージのリストが含まれています。

パッケージング

setup.pyファイルは、pip Pythonsetuptools を使用して プロジェクトをパッケージ化するための コマンドなどのコンソールで実行されるコマンド (コンソールスクリプト) を提供します。setuptools のドキュメントのエントリ ポイントを参照してください。

その他のファイル

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

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

コード サンプルを実行する

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

dbx で実行

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

   Bash

   pip install -e .

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

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

   Bash

   pytest tests/

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

ヒント

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

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

   Bash

   coverage run -m pytest tests/

注記

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

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

Bash

coverage report -m

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

   Bash

   dbx deploy --environment=default

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

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

5. ワークスペース内の本番運用前のバージョンのコードを実行するには、次のコマンドを実行します。

   Bash

   dbx launch covid_analysis_etl_integ

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

   Bash

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

   Web ブラウザーでこのリンクをたどると、ワークスペースで実行の結果が表示されます。

6. ワークスペース内のコードの本番運用バージョンを実行するには、次のコマンドを実行します。

   Bash

   dbx launch covid_analysis_etl_prod

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

   Bash

   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 を使用するように設定する

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

1. Databricks サービスプリンシパルを作成します。
2. Databricks サービスプリンシパルの Databricks アクセス トークンを作成します。

セキュリティのベスト プラクティスとして、 Databricksでは、GitHub がDatabricks ワークスペースで認証できるようにするために、ワークスペースユーザーのDatabricks 個人用アクセス トークンではなく、Databricks サービス プリンシパルの Databricks アクセス トークンを使用することをお勧めします。

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

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://dbc-a1b2345c-d6e7.cloud.databricks.comなど) に設定します。
• DATABRICKS_TOKENという名前の暗号化されたシークレットを作成し、DatabricksサービスプリンシパルのDatabricksアクセストークンの値に設定します。

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

1. Visual Studio Code の ソース管理 ビュー ( 表示 > ソース管理 ) で、 ... ( ビューとその他のアクション ) アイコンをクリックします。
2. ブランチ > ブランチの作成元 をクリックします。
3. ブランチの名前を入力します (例: my-branch)。
4. ブランチを作成するブランチ ( main など) を選択します。
5. ローカル リポジトリ内のファイルの 1 つに小さな変更を加え、ファイルを保存します。 たとえば、 tests/transforms_test.py ファイル内のコード コメントに小さな変更を加えます。
6. ソース管理 ビューで、 ... ( ビューとその他のアクション ) アイコンをもう一度クリックします。
7. 変更 >すべての変更をステージング をクリックします。
8. [...] ( [ビューとその他のアクション ]) アイコンをもう一度クリックします。
9. 「コミット」>「コミット・ステージング」 をクリックします。
10. コミットのメッセージを入力します。
11. [...] ( [ビューとその他のアクション ]) アイコンをもう一度クリックします。
12. 「ブランチ」>「ブランチの公開」 をクリックします。

ステップ 4: pull request を作成してマージする

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