メインコンテンツまでスキップ
に最終更新

Databricks REST API

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

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

注記

高度なシナリオを除き、Databricks オブジェクトをプログラムで管理する場合は、Databricks REST API ではなく Databricks SDK または Databricks CLI を使用することを推奨します。

ワークスペースとアカウントのREST APIs​

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

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

REST API を呼び出す​

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

  • ワークスペースEndpointかアカウントEndpointかに応じて、以下のいずれかを行います：

  • GET、POST、PATCH、またはDELETEなどのREST API操作タイプ。

  • REST APIの操作パス、例えば /api/2.0/clusters/get。

  • Databricks OAuthトークンなどのDatabricks認証情報。

  • クラスターのIDなど、REST API操作でサポートされているリクエストペイロードまたはリクエストクエリーパラメーター。

REST APIリクエストの構造化方法や、使用する開発者ツール向けの応答ペイロードの解析方法に関する情報については、プロバイダーのドキュメントを参照してください。

例 1: クラスターの取得​

次の例では、クラスターのリスト (Cluster, List) Endpointを呼び出して、使用可能なクラスターのリストを返します。DATABRICKS_HOST 環境変数が Databricks ワークスペース URL に設定され、DATABRICKS_TOKEN が Databricks トークンに設定されていることを前提としています。

Bash
curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"
Python
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:ジョブを実行する​

次の例では、ジョブの「今すぐ実行」Endpointを呼び出して、既存のジョブのドライRunをTriggerします。DATABRICKS_HOST 環境変数が Databricks ワークスペース URL に設定され、DATABRICKS_TOKEN が Databricks トークンに設定されていることを前提としています。

Bash
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"
    }
  }'
Python
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：アカウントユーザーを返す​

次の例では、アカウントユーザーのリストEndpointを呼び出して、<account_id> で識別される Databricks アカウント内のユーザーを返します。

Bash
curl -X GET '<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users' \
  --header "Authorization: Bearer $OAUTH_TOKEN"
Python
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())

ベストプラクティス​

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

LIST API レスポンスのページ分割​

LIST APIs は、単一の大きなレスポンスではなく、ページ単位で結果を返します。完全な結果セットを取得するには、最初のページをリクエストし、レスポンスに含まれるトークンを使用して、トークンが返されなくなるまで後続の各ページをリクエストします。

完全な結果セットをページ単位で表示するには：

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

次の例では、このパターンを使用して、Unity Catalogテーブル、LIST Endpointからスキーマ内のすべてのテーブルを取得します。同じループが、すべてのLIST APIで機能します。変更されるのは、Endpointと応答内の配列フィールドの名前のみです。たとえば、Grants Endpointは、tables ではなく privilege_assignments 配列で結果を返します。

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

指数バックオフとジッターを使用して再試行し、429 レスポンスを適切に処理します：

  • 指数関数的バックオフ : 429の後、再試行する前に待機し、その後の429ごとに待機時間を倍にします。リクエストが無限に再試行されないように、最大待機時間と最大再試行回数を設定します。
  • ジッター : 各待機時間に少量のランダムな時間を追加します。ジッターは、複数のクライアントからの再試行を分散させるため、すべてのクライアントが同時に再試行してトラフィックのバーストが繰り返されることを防ぎます。
  • レスポンスに Retry-After ヘッダーが含まれている場合は、その時間以上待機してから再試行してください。

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

特定のAPIに適用されるレート制限については、APIレート制限のAPIレート制限を参照してください。

パフォーマンスのための応答フィールドのトリミング​

一部のLIST APIは、コンピュートにコストがかかる、またはレスポンスを大きくするフィールドを返します。これらのフィールドが不要な場合は、それらを省略するリクエストパラメーターを使用して、レスポンスサイズを削減し、レイテンシを改善します。

たとえば、Unity Catalog Tables APIは、次のパラメーターをサポートしています。

  • omit_properties=true: レスポンス内の各テーブルから properties フィールドを省略します。
  • omit_columns=true: レスポンス内の各テーブルから columns フィールドを省略します。

名前を取得するためだけにテーブルを一覧表示する場合は、両方のパラメーターを設定することで、より小さな応答が返され、テーブルのリスティングが高速化されます。各Endpointがサポートするフィールドトリミングパラメーターについては、REST APIリファレンスを確認してください。

その他のリソース​

このページの見出し