Databricks SDK for Python

[アーティクル]
03/01/2024

この記事では、Databricks SDK for Python を使用して Azure Databricks アカウント、ワークスペース、関連リソースでの操作を自動化する方法を説明します。この記事は、参考資料の Databricks SDK for Python のドキュメントと、GitHub の Databricks SDK for Python リポジトリにあるコードサンプルを補足するものです。

Note

この機能はベータ版であり、運用環境で使用しても問題ありません。

ベータ期間中、Databricks では、コードが依存する Databricks SDK for Python の特定のマイナーバージョンへの依存関係をピン留めすることをお勧めします。たとえば、 venv の requirements.txtや Poetry の pyproject.toml と poetry.lock などのファイルに依存関係をピン留めできます。依存関係のピン留めについて詳しくは、venv で「仮想環境とパッケージ」または Poetryに「依存関係をインストールする」を参照してください。

開始する前に

Databricks SDK for Python は、Azure Databricks ノートブック内かローカル開発用マシンから使用できます。

Azure Databricks ノートブック内から Databricks SDK for Python を使用する方法を確認するには、「Azure Databricks ノートブックから Databricks SDK for Python を使用する」に進んでください。
ローカル開発用マシンから Databricks SDK for Python を使用するには、このセクションで示す手順を実行してください。

Databricks SDK for Python の使用を開始する前に、開発用マシンで次の条件が満たされている必要があります。

Azure Databricks 認証が構成されている。
Python 3.8 以上がインストールされている。 Azure Databricks コンピューティングリソースを自動化する場合は、Databricks で対象の Azure Databricks コンピューティングリソースにインストールされているバージョンと一致する Python メジャーバージョンおよびマイナーバージョンをインストールすることをお勧めします。この記事の例では、Python 3.10 がインストールされている、Databricks Runtime 13.0 を使用するクラスターの自動化が採用されています。ご使用のクラスターの Databricks Runtime について正しいバージョンを確認するには、「Databricks Runtime リリースノートのバージョンと互換性」をご覧ください。
Databricks では、Databricks SDK for Python で使用する Python コードプロジェクトごとに Python 仮想環境 を作成しアクティブ化することが推奨されています。 Python 仮想環境は、コードプロジェクトで必ず互換バージョンの Python および Python パッケージ (この場合は、Databricks SDK for Python パッケージ) が使用されるようにするために役立ちます。この記事では、Python 仮想環境に venv または Potetry を使用する方法について説明します。

`venv` を使用して Python 仮想環境を作成する

ターミナルセットから Python コードプロジェクトのルートディレクトリに移動し、次のコマンドを実行します。このコマンドは、仮想環境に Python 3.10 を使用するように venv に指示し、Python コードプロジェクトのルートディレクトリ内に .venv という名前の隠しディレクトリに仮想環境のサポートファイルを作成します。
```
# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv
```
venv を使用して仮想環境をアクティブにします。オペレーティングシステムとターミナルの種類に基づいた、使用する正しいコマンドについては、venv に関するドキュメントを参照してください。たとえば、zsh を実行している macOS では、次のようになります。
```
source ./.venv/bin/activate
```
ターミナルプロンプトの直前に仮想環境の名前 (例: .venv) がかっこで囲まれて表示されたら、仮想環境がアクティブになったことがわかります。

仮想環境は、コマンド deactivate を実行していつでも非アクティブ化できます。

ターミナルプロンプトの直前のかっこ内に仮想環境の名前が表示されなくなったたら、仮想環境が非アクティブ化されたことがわかります。

「Python 用 Databricks SDK での作業を開始する」に進んでください。

Poetry を使用して仮想環境を作成する

あなたがまだそうしていない場合は、Poetry をインストールします。
ターミナルセットから Python コードプロジェクトのルートディレクトリに移動し、次のコマンドを実行して、Python コードプロジェクトを Poetry 用に初期化するように poetry に指示します。
```
poetry init
```
Poetry には、完了するためのいくつかのプロンプトが表示されます。これらのプロンプトはいずれも、Databricks SDK for Python に固有のものではありません。これらのプロンプトの詳細については、init を参照してください。
プロンプトが完了すると、Poetry で Python プロジェクトに pyproject.toml ファイルが追加されます。 pyproject.toml ファイルの詳細については、pyproject.toml ファイルを参照してください。
ターミナルを Python コードプロジェクトのルートディレクトリに設定したまま、次のコマンドを実行します。このコマンドは、pyproject.toml ファイルの読み取り、依存関係のインストールと解決、依存関係をロックする poetry.lock ファイルの作成、最後に仮想環境の作成を poetry に指示します。
```
poetry install
```
ターミナルセットから Python コードプロジェクトのルートディレクトリに移動し、次のコマンドを実行して、仮想環境をアクティブ化し、シェルを入力するように poetry に指示します。
```
poetry shell
```
ターミナルプロンプトの直前に仮想環境の名前がかっこで囲まれて表示されると、仮想環境がアクティブ化され、シェルが入力されたことがわかります。

仮想環境を非アクティブ化し、いつでもシェルを終了するには、exit コマンドを実行します。

ターミナルプロンプトの直前に仮想環境の名前がかっこで囲まれて表示されなくなったときに、シェルを終了したことがわかります。

Poetry の仮想環境の作成と管理の詳細については、「環境の管理」を参照してください。

Databricks SDK for Python での作業開始

このセクションでは、ローカル開発用マシンから Databricks SDK for Python の使用を開始する方法について説明します。 Azure Databricks ノートブック内から Databricks SDK for Python を使用する方法を確認するには、「Azure Databricks ノートブックから Databricks SDK for Python を使用する」に進んでください。

Azure Databricks 認証が構成され、Python が既にインストールされ、Python 仮想環境が既にアクティブ化されている開発マシンに、次のように Python パッケージインデックス (PyPI) から databricks-sdk パッケージ (およびその依存関係) をインストールします:

Venv

pip を使用して、databricks-sdk パッケージをインストールします。 (一部のシステムでは、ここと全体で、pip3 を pip に置き換える必要がある場合があります。)
```
pip3 install databricks-sdk
```
Poetry
```
poetry add databricks-sdk
```
Databricks SDK for Python がベータ版である間に特定のバージョンの databricks-sdk パッケージをインストールするには、パッケージのリリース履歴を参照してください。たとえば、バージョン 0.1.6 をインストールする場合:

Venv
```
pip3 install databricks-sdk==0.1.6
```
Poetry
```
poetry add databricks-sdk==0.1.6
```
ヒント

Databricks SDK for Python パッケージの既存のインストールを最新バージョンにアップグレードするには、次のコマンドを実行します:

Venv
```
pip3 install --upgrade databricks-sdk
```
Poetry
```
poetry add databricks-sdk@latest
```
Databricks SDK for Python パッケージの現在の Version とその他の詳細を表示するには、次のコマンドを実行します:

Venv
```
pip3 show databricks-sdk
```
Poetry
```
poetry show databricks-sdk
```
Python 仮想環境で、Databricks SDK for Python をインポートする Python コードファイルを作成します。次の例では、次のコンテンツの main.py という名前のファイルで、Azure Databricks ワークスペース内のすべてのクラスターを一覧表示しているだけです。
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)
```
次のように、python コマンドを実行して、main.py という名前のファイルを想定し Python コードファイルを実行します。

Venv
```
python3.10 main.py
```
Poetry

仮想環境のシェル内にある場合:
```
python3.10 main.py
```
仮想環境のシェルにない場合:
```
poetry run python3.10 main.py
```
Note

前述の w = WorkspaceClient() の呼び出しで引数を設定しないと、Databricks SDK for Python で、Azure Databricks 認証の実行を試みるためにその既定のプロセスが使用されます。この既定の動作をオーバーライドする方法については、認証に関する次のセクションをご覧ください。

Azure Databricks アカウントまたはワークスペースで Databricks SDK for Python を認証する

このセクションでは、Azure Databricks アカウントまたはワークスペースによってローカル開発用マシンから Databricks SDK for Python を認証する方法を説明します。 Azure Databricks ノートブック内から Databricks SDK for Python を認証する方法を確認するには、「Azure Databricks ノートブックから Databricks SDK for Python を使用する」に進んでください。

Databricks SDK for Python では、Databricks クライアント統合認証標準が実装されます。これは、統合された、一貫性のある、アーキテクチャとプログラムによる認証手法です。このアプローチは、Azure Databricks を使用した認証の設定と自動化を、より一元的で予測可能なものにするのに役立ちます。これにより、Databricks 認証を一度構成すれば、それ以上認証構成を変更しなくても、複数の Databricks ツールおよび SDK でその構成を使用できます。詳しくは (より完成された Python コード例など)、Databricks クライアント統合認証に関するページをご覧ください。

Note

Databricks SDK for Python では、まだ Azure マネージド ID 認証が実装されていません。

Databricks SDK for Python を使用して Databricks 認証を初期化するために使用できるコーディングパターンをいくつか次に示します。

次のいずれかを行って、Databricks の既定の認証を使用します。
- ターゲットの Databricks 認証の種類に必要なフィールドを含むカスタムの Databricks 構成プロファイルを作成または識別します。次に、DATABRICKS_CONFIG_PROFILE 環境変数をカスタム構成プロファイルの名前に設定します。
- ターゲットの Databricks 認証の種類に必要な環境変数を設定します。
次に、たとえば、以下のように Databricks の既定の認証を使って WorkspaceClient オブジェクトのインスタンスを作成します。
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...
```
必要なフィールドのハードコーディングはサポートされていますが、Azure Databricks 個人用アクセストークンなどの機密情報がコードで公開されるリスクがあるため、推奨されません。次の例では、Databricks トークン認証用に Azure Databricks ホストとアクセストークンの値をハードコードします。
```
from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host  = 'https://...',
  token = '...'
)
# ...
```

Databricks SDK for Python ドキュメントの「Authentication」(認証) も参照してください。

Azure Databricks ノートブックから Databricks SDK for Python を使用する

Azure Databricks クラスターがアタッチされ、Databricks SDK for Python がインストールされている Azure Databricks ノートブックから、Databricks SDK for Python の機能を呼び出すことができます。 Databricks SDK for Python は、Databricks Runtime 13.2 以降を使用するすべての Azure Databricks クラスターに既にインストールされています。 Databricks Runtime 13.1 以前を使用する Azure Databricks クラスターの場合、まず Databricks SDK for Python をインストールする必要があります。「手順 1: Databricks SDK for Python をインストールまたはアップグレードする」を参照してください。

特定バージョンの Databricks Runtime 用に既定でインストールされている Databricks SDK for Python のバージョン番号を確認するには、その Databricks Runtime バージョンの Databricks Runtime リリースノートの「インストールされている Python ライブラリ」セクションを参照してください。

Databricks SDK for Python 0.6.0 以降によって既定の Azure Databricks ノートブック認証が使用されます。既定の Azure Databricks ノートブック認証は、Azure Databricks が独自に使用するためにバックグラウンドで自動的に生成する一時的な Azure Databricks 個人用アクセストークンに依存します。この一時トークンは、ノートブックの実行が停止すると、Azure Databricks によって削除されます。

重要

既定の Azure Databricks ノートブック認証が機能するのは、クラスターのドライバーノード上のみであり、クラスターのワーカーノードや Executor ノード上では機能しません。

Databricks Runtime 13.1 以降では、Databricks SDK for Python 0.1.7 以降がインストールされた既定の Azure Databricks ノートブック認証がサポートされます。 Databricks Runtime 10.4 LTS 以降では、Databricks SDK for Python 0.1.10 以降がインストールされた既定の Azure Databricks ノートブック認証がサポートされます。ただし、Databricks Runtime のバージョンに関係なく、既定の Azure Databricks ノートブック認証との互換性を最大限に高めるために、Databricks SDK for Python 0.6.0 以降をインストールまたはそれにアップグレードすることをお勧めします。

Azure Databricks アカウントレベルの API を呼び出す場合、または既定の Azure Databricks ノートブック認証以外の種類の Azure Databricks 認証を使用する場合は、次のように、Azure Databricks クラスター上に Databricks SDK for Python をインストール (またはアップグレード) する必要があります。

認証の種類	Databricks SDK for Python のバージョン
OAuth マシン間 (M2M) 認証	0.18.0 以降
OAuth ユーザー対マシン (U2M) 認証	0.19.0 以降
Microsoft Entra ID サービスプリンシパル認証	すべてのバージョン
Azure CLI 認証	すべてのバージョン
Databricks 個人用アクセストークン認証	すべてのバージョン

Azure マネージド ID 認証はまだサポートされていません。

Azure Databricks ノートブック認証は、Azure Databricks 構成プロファイルでは機能しません。

手順 1: Databricks SDK for Python をインストールまたはアップグレードする

Azure Databricks Python ノートブックでは、他の Python ライブラリと同様に Databricks SDK for Python を使用できます。アタッチされた Azure Databricks クラスターに Databricks SDK for Python ライブラリをインストールまたはアップグレードするには、次のようにノートブックセルから %pip マジックコマンドを実行します。
```
%pip install databricks-sdk --upgrade
```
%pip マジックコマンドを実行した後、Python を再起動して、インストールまたはアップグレードされたライブラリをノートブックで使用できるようにする必要があります。これを行うには、%pip マジックコマンドがあるセルの直後のノートブックセルから次のコマンドを実行します。
```
dbutils.library.restartPython()
```
Databricks SDK for Python のインストールされているバージョンを表示するには、ノートブックセルから次のコマンドを実行します。
```
%pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
```

手順 2: コードを実行する

ノートブックセルで、Databricks SDK for Python をインポートしてから呼び出す、Python コードを作成します。次の例では、既定の Azure Databricks ノートブック認証を使用して、Azure Databricks ワークスペース内のすべてのクラスターを一覧表示します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)

このセルを実行すると、Azure Databricks ワークスペース内の使用可能なすべてのクラスターの名前が一覧で表示されます。

別の種類の Azure Databricks 認証を使用するには、「サポートされている Azure Databricks 認証の種類」を参照し、対応するリンクをクリックして技術的な詳細を確認してください。

Databricks ユーティリティを使用する

「Databricks Utilities (dbutils) リファレンス」は、ローカル開発用マシンで実行されている Databricks SDK for Python コードから、または Azure Databricks ノートブック内から呼び出すことができます。

ローカル開発用マシンからの場合、Databricks ユーティリティは、dbutils.fs、dbutils.secrets、dbutils.widgets、dbutils.jobs コマンドグループにのみアクセスできます。
Azure Databricks クラスターに関連付けられている Azure Databricks ノートブックからの場合、Databricks ユーティリティは、dbutils.fs、dbutils.secrets、dbutils.widgets のみでなく、使用可能なすべての Databricks ユーティリティコマンドグループにアクセスできます。また、dbutils.notebook コマンドグループは、dbutils.notebook.run や dbutils.notebook.exit など、2 つのレベルのコマンドのみに制限されます。

ローカル開発用マシンまたは Azure Databricks ノートブックから Databricks ユーティリティを呼び出すには、WorkspaceClient 内で dbutils を使用します。このコード例では、既定の Azure Databricks ノートブック認証を使用して、WorkspaceClient 内の dbutils を呼び出して、ワークスペースの DBFS ルート内のすべてのオブジェクトのパスを一覧表示します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
d = w.dbutils.fs.ls('/')

for f in d:
  print(f.path)

または、dbutils を直接呼び出すこともできます。ただし、既定の Azure Databricks ノートブック認証のみを使用するように制限されます。このコード例では、dbutils を直接呼び出して、ワークスペースの DBFS ルート内のすべてのオブジェクトを一覧表示します。

from databricks.sdk.runtime import *

d = dbutils.fs.ls('/')

for f in d:
  print(f.path)

dbutils を単独で、または WorkspaceClient 内で使用して、Unity Catalog ボリュームにアクセスすることはできません。代わりに、WorkspaceClient 内で files を使用します。このコード例では、files を WorkspaceClient 内で呼び出して、指定したボリュームの指定したファイルの内容を出力します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

resp = w.files.download('/Volumes/main/default/my-volume/sales.csv')
print(str(resp.contents.read(), encoding='utf-8'))

「dbutils とのやり取り」もご確認ください。

コード例

次のコード例では、Databricks SDK for Python を使用してクラスターを作成および削除し、ジョブを作成し、アカウントレベルのグループを一覧表示する方法を示します。これらのコード例では、既定の Azure Databricks ノートブック認証を使用します。既定の Azure Databricks ノートブック認証について詳しくは、「Azure Databricks ノートブック内から Databricks SDK for Python を使用する」をご覧ください。ノートブック以外の既定の認証について詳しくは、「Azure Databricks アカウントまたはワークスペースで Databricks SDK for Python を認証する」をご覧ください。

その他のコード例については、GitHub で Databricks SDK for Python リポジトリ内の例を参照してください。関連項目:

クラスターの作成

このコード例では、Databricks Runtime バージョンとクラスターノードの種類を指定してクラスターを作成します。このクラスターには 1 つのワーカーがあり、クラスターは 15 分のアイドル時間の後に自動的に終了します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

print("Attempting to create cluster. Please wait...")

c = w.clusters.create_and_wait(
  cluster_name             = 'my-cluster',
  spark_version            = '12.2.x-scala2.12',
  node_type_id             = 'Standard_DS3_v2',
  autotermination_minutes = 15,
  num_workers              = 1
)

print(f"The cluster is now ready at " \
      f"{w.config.host}#setting/clusters/{c.cluster_id}/configuration\n")

クラスターを完全に削除する

このコード例では、指定したクラスター ID のクラスターをワークスペースから完全に削除しています。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

c_id = input('ID of cluster to delete (for example, 1234-567890-ab123cd4): ')

w.clusters.permanent_delete(cluster_id = c_id)

ジョブの作成

このコード例では、指定したクラスターで指定したノートブックを実行する Azure Databricks ジョブを作成しています。コードを実行すると、ターミナルでユーザーから既存のノートブックのパス、既存のクラスター ID、および関連するジョブ設定が取得されます。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import Task, NotebookTask, Source

w = WorkspaceClient()

job_name            = input("Some short name for the job (for example, my-job): ")
description         = input("Some short description for the job (for example, My job): ")
existing_cluster_id = input("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4): ")
notebook_path       = input("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook): ")
task_key            = input("Some key to apply to the job's tasks (for example, my-key): ")

print("Attempting to create the job. Please wait...\n")

j = w.jobs.create(
  name = job_name,
  tasks = [
    Task(
      description = description,
      existing_cluster_id = existing_cluster_id,
      notebook_task = NotebookTask(
        base_parameters = dict(""),
        notebook_path = notebook_path,
        source = Source("WORKSPACE")
      ),
      task_key = task_key
    )
  ]
)

print(f"View the job at {w.config.host}/#job/{j.job_id}\n")

アカウントレベルのグループを一覧表示する

このコード例では、Azure Databricks アカウント内で使用可能なすべてのグループの表示名を一覧表示します。

from databricks.sdk import AccountClient

a = AccountClient()

for g in a.groups.list():
  print(g.display_name)

その他のリソース

詳細については、以下を参照してください:

Databricks SDK for Python

開始する前に

venv を使用して Python 仮想環境を作成する

Poetry を使用して仮想環境を作成する

Databricks SDK for Python での作業開始

Venv

Poetry

Venv

Poetry

Venv

Poetry

Venv

Poetry

Venv

Poetry

Azure Databricks アカウントまたはワークスペースで Databricks SDK for Python を認証する

Azure Databricks ノートブックから Databricks SDK for Python を使用する

手順 1: Databricks SDK for Python をインストールまたはアップグレードする

手順 2: コードを実行する

Databricks ユーティリティを使用する

コード例

クラスターの作成

クラスターを完全に削除する

ジョブの作成

アカウントレベルのグループを一覧表示する

その他のリソース

その他のリソース

`venv` を使用して Python 仮想環境を作成する