Visual Studio Code で dbx を使用する

important

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

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 ワークスペースに送信します。は、dbx Databricksジョブを使用してオーケストレーションDatabricksを行い、送信されたコードをそのワークスペース内のジョブクラスタリングで実行するように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 と共に使用する方法について説明します。

コードサンプルの要件

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

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 は、新しいバージョンの 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 のデータブリック/ide ベストプラクティス Repo ジトリで入手でき、次のことを行います。

GitHub の owid/covid-19-data Repo ジトリからデータを取得します。
特定の ISO 国コードのデータをフィルタリングします。
データからピボットテーブルを作成します。
データに対してデータクレンジングを実行します。
コードロジックを再利用可能な関数にモジュール化します。
ユニットは関数をテストします。
コードがリモート Databricks ワークスペースの Delta テーブルにデータを書き込むことができるように、 dbx プロジェクト構成と設定を提供します。

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

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

注記

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

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

ターミナルから、このコードサンプルの仮想環境を格納する空白のフォルダーを作成します。これらの手順では、 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 .

Visual Studio Code のメニューバーで、[ ターミナルの表示] > をクリックします。
ide-demo フォルダのルートから、次のオプションを指定して pipenv コマンドを実行します。ここでは、 <version> はローカルにすでにインストールされているPythonのターゲットバージョン（Pythonのターゲットクラスターのバージョンと一致するのが理想）です。（例：3.8.14）
Bash
```
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>) のようなものが表示されます。表示されない場合は、次のコマンドを実行します。
  Bash
```
pipenv shell
```
  pipenvシェルを終了するには、コマンドを exit実行すると、括弧が消えます。
詳しくはVisual Studio Codeドキュメントの「VS CodeにおけるPython環境の使用」を参照してください。

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

Visual Studio Code で、 ide-demo フォルダー ( [ファイル] > [フォルダーを開く ]) を開きます (まだ開いていない場合)。
[ 表示] > [コマンドパレット] をクリックし、「 Git: Clone」と入力して、[ Git: Clone ] をクリックします。
[リポジトリ 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)から、次のコマンドを実行します。
Bash
```
pip install dbx
```
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
```
dbxをインストールすると、従来の Databricks CLI (Databricks CLI バージョン 0.17) も自動的にインストールされます。従来の Databricks CLI (Databricks CLI バージョン 0.17) がインストールされていることを確認するには、次のコマンドを実行します。
Bash
```
databricks --version
```
Databricks CLI バージョン 0.17 が返された場合は、従来の Databricks CLI がインストールされます。
従来の Databricks CLI (Databricks CLI バージョン 0.17) を認証で設定していない場合は、ここで設定する必要があります。認証が設定されていることを確認するには、次の基本コマンドを実行して、Databricks ワークスペースに関する概要情報を取得します。 ls サブコマンドの後にスラッシュ (/) を必ず含めてください。
Bash
```
databricks workspace ls /
```
ワークスペースのルートレベルのフォルダー名のリストが返された場合は、認証が設定されます。
このコードサンプルが依存する Python パッケージをインストールします。これを行うには、 ide-demo/ide-best-practices フォルダーから次のコマンドを実行します。
Bash
```
pip install -r unit-requirements.txt
```
コードサンプルの依存パッケージがインストールされていることを確認します。これを行うには、次のコマンドを実行します。
Bash
```
pip list
```
requirements.txt ファイルと unit-requirements.txt ファイルにリストされているパッケージがこのリストのどこかにある場合は、従属パッケージがインストールされます。

注記

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

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

リポジトリの 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
}
```

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 で実行

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 フォルダーを作成します。
次のコマンドを実行して、テストを実行します。
Bash
```
pytest tests/
```
テストの結果はターミナルに表示されます。 4 つのテストすべてが合格と表示されます。

ヒント

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

必要に応じて、次のコマンドを実行して、テストの test coverage メトリクスを取得します。
Bash
```
coverage run -m pytest tests/
```

注記

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

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

Bash

coverage report -m

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

プロジェクトのコンテンツは、.dbx/project.json ファイル内の artifact_location オブジェクトで指定された場所に送信されます。
ワークスペース内の本番運用前のバージョンのコードを実行するには、次のコマンドを実行します。
Bash
```
dbx launch covid_analysis_etl_integ
```
実行の結果へのリンクがターミナルに表示されます。次のようになります。
Bash
```
https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
```
Web ブラウザーでこのリンクをたどると、ワークスペースで実行の結果が表示されます。
ワークスペース内のコードの本番運用バージョンを実行するには、次のコマンドを実行します。
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」の手順に従います。これには、次のアクションが含まれます。

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

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

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

GitHub Actions を実行する

手順 1: クローン作成されたリポジトリを発行する

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

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

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

DATABRICKS_HOSTという名前の暗号化されたシークレットを作成し、ワークスペースインスタンスの URL の値 (https://dbc-a1b2345c-d6e7.cloud.databricks.comなど) に設定します。
DATABRICKS_TOKENという名前の暗号化されたシークレットを作成し、DatabricksサービスプリンシパルのDatabricksアクセストークンの値に設定します。

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

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

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

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

コード サンプルの要件​

コード サンプルについて​

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

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

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

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

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

コード サンプルを調べる​

コードのモジュール化​

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

モジュール化されたコード​

テスティング​

ユニットテスト​

単体テストランナー​

包装​

その他のファイル​

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

dbx で実行​

GitHub Actions での実行​

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

GitHub Actions を実行する​

手順 1: クローン作成されたリポジトリを発行する​

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

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

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