Azure Databricks REST API

このページではAzure Databricks REST APIの使い方、呼び出し方法、そしていくつかのベストプラクティスについて説明します。

Databricks REST APIの完全な参照については、 Databricks REST APIリファレンスを参照してください。

Workspace と Account REST API の違い

Azure Databricksは2セットのREST APIを提供しています。 Workspace APIはクラスタ、ジョブ、ノートブック、Unity Catalogオブジェクトなどのリソースを単一のワークスペース内で管理し、ホストとしてワークスペースの URL を使って呼び出します。 アカウントAPIはユーザーおよびグループのプロビジョニング、ワークスペースの作成、ネットワークおよび課金設定、アカウントレベルのUnity Catalog設定などのアカウント全体のリソースを管理し、アカウントコンソールの ログインURLとアカウントIDを使ってそれらを呼び出します。

各セットで利用可能な操作については、 ワークスペースAPI参照 および アカウントAPI参照を参照してください。

REST API を呼び出す

Databricks REST APIの呼び出しには以下のコンポーネントが含まれます:

• ワークスペースエンドポイントかアカウントエンドポイントかによって、以下のいずれかがあります:
  • あなたのDatabricks ワークスペースのURL
  • あなたのDatabricksアカウントコンソールの ログインURL と アカウントID
• REST API操作タイプ( GET、 POST、 PATCH、 DELETEなど)。
• REST APIの操作パス、例えば /api/2.0/clusters/get。
• Databricksの認証 情報、例えばDatabricks OAuthトークンなどです。
• クラスターのIDなど、REST API操作でサポートされているリクエストペイロードやリクエストクエリパラメータ。

REST APIリクエストの構造化方法や、希望する開発者ツールのレスポンスペイロードの解析方法については、プロバイダーのドキュメントをご覧ください。

例1:クラスタを取得する

以下の例では 、Cluster, Listエンドポイント を呼び出して利用可能なクラスタのリストを返します。 DATABRICKS_HOST環境変数がDatabricksのワークスペースURLに設定され、DATABRICKS_TOKENがDatabricksトークンに設定されていると仮定しています。

curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"

import requests
import os

headers = {"Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}"}
response = requests.get(f"{os.getenv('DATABRICKS_HOST')}/api/2.0/clusters/list", headers=headers)

print(response.json())

例2:仕事を実行する

以下の例では、Job, Run Now endpointを呼び出して、既存のジョブのドライランを実行します。 DATABRICKS_HOST環境変数がDatabricksのワークスペースURLに設定され、DATABRICKS_TOKENがDatabricksトークンに設定されていると仮定しています。

curl -X POST "$DATABRICKS_HOST/api/2.1/jobs/run-now" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": 45678,
    "notebook_params": {
      "dry_run": "true",
      "start_date": "2026-08-27"
    }
  }'

import requests
import os

url = f"{os.getenv('DATABRICKS_HOST')}/api/2.1/jobs/run-now"
headers = {
    "Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "job_id": 45678,
    "notebook_params": {"dry_run": "true", "start_date": "2026-08-27"}
}

response = requests.post(url, headers=headers, json=payload)
print(f"Run ID: {response.json().get('run_id')}")

例3:アカウントの返却

以下の例では、<account_id>で識別される Databricks アカウントのユーザーを返すために、Account User, List エンドポイントを呼び出します:

curl -X GET '<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users' \
  --header "Authorization: Bearer $OAUTH_TOKEN"

import requests
import os

url = "<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users"
headers = {"Authorization": f"Bearer {os.getenv('OAUTH_TOKEN')}"}

response = requests.get(url, headers=headers)
print(response.json())

ベスト プラクティス

以下のセクションでは、ワークスペース内のデータが増加する際のパフォーマンスベストプラクティスについて説明します。

Paginate LIST APIレスポンス

LIST APIは単一の大きなレスポンスではなくページ単位で結果を返します。 完全な結果セットを取得するには、最初のページを要求し、その後応答のトークンを使って次の各ページを要求し、トークンが返ってこないまで続きます。

結果セット全体をページ単位で表示するには:

• リクエストで max_results=0 を設定してください。 これにより、サーバーは適切なページサイズを選択でき、ページごとに固定数の結果を要求するよりも効率的です。
• 各回答の next_page_token 欄を読みましょう。 次のページをリクエストするには、次のリクエストの page_token クエリパラメータにその値を渡します。
• これを繰り返し、応答が next_page_token を省略するか空の値として返すまで続けます。 その返答が最後のページです。
• 最初のリクエストには page_token を含めないでください。 フォローアップの依頼時のみ追加してください。

以下の例では、このパターンを使って Unity Catalog Table, Listエンドポイントからスキーマ内のすべてのテーブルを取得します。 同じループはどの LIST APIでも機能します。 応答の端点と配列フィールドの名前だけが変わります。 例えば、Grantのエンドポイントの返す結果はtablesではなくprivilege_assignments配列になります。

import requests

base_url = "https://example.cloud.databricks.com"  # No trailing slash
bearer_token = "<your-personal-access-token>"
catalog_name = "main"
schema_name = "default"


def list_tables(base_url, bearer_token, catalog_name, schema_name):
    endpoint = f"{base_url}/api/2.1/unity-catalog/tables"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {
        "catalog_name": catalog_name,
        "schema_name": schema_name,
        "max_results": 0,  # Let the server choose the page size.
    }

    tables = []
    while True:
        response = requests.get(endpoint, headers=headers, params=params)
        response.raise_for_status()
        body = response.json()

        tables.extend(body.get("tables", []))

        # Stop when the response no longer includes a page token.
        page_token = body.get("next_page_token")
        if not page_token:
            break
        params["page_token"] = page_token

    return tables

429のレート制限応答を処理

DatabricksはREST API呼び出しにレート制限を設け、重負荷でもワークスペースの応答性を保ちます。 フェアユースと可用性をサポートするために、エンドポイントごとワークスペースごとに制限が適用されます。 レート制限を超えるリクエストはHTTP 429 Too Many Requests 応答を返します。

指数バックオフとジッターを使用して再試行し、429 応答を適切に処理してください:

• 指数的バックオフ: 429の後に再挑戦を待ち、その後の各 429で待ち時間を倍にします。 リクエストが無期限に再試行しないように、最大待ち時間と最大リトライ回数を設定します。
• ジッター:待機時間に少しだけランダムな時間を加えましょう。 ジッターは複数のクライアントからの再試行を分散させ、すべてのクライアントが同時に再試行して繰り返しトラフィックのバーストを起こさないようにします。
• もし返信に Retry-After ヘッダーが含まれている場合は、少なくともそれだけの期間は待ってから再試行してください。

ほとんどのHTTPクライアントライブラリでは、この再試行処理を自動的に行えます。 アルゴリズムの背景については、 指数的バックオフとジッターを参照してください。

特定のAPIに適用されるレート制限については、 API レート制限の「API rate limits」をご覧ください。

パフォーマンス向上のために応答フィールドを削減

一部の LIST APIは、計算コストが高くなったり、応答が大きくなるフィールドを返します。 これらのフィールドが不要な場合は、それらを省略するリクエストパラメータを使って応答サイズを減らし、レイテンシを改善しましょう。

例えば、 Unity Catalog Tables API は以下のパラメータをサポートしています:

• omit_properties=true: は回答の各表から properties フィールドを省略します。
• omit_columns=true: は回答の各表から columns フィールドを省略します。

テーブル名を取得するためだけにリストアップする場合は、両方のパラメータを設定することで応答が小さくなり、テーブルのリストも速くなります。 各エンドポイントがサポートするフィールドトリミングパラメータについては REST APIのリファレンス を確認してください。

その他のリソース

• Databricks SDK
• Databricks CLI
• API レートの制限
• REST API リファレンス