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

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

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

  • 各応答からnext_page_tokenフィールドを読み取ります。次のページを要求するには、その値を次の要求のクエリーパラメーターpage_tokenで渡し、他のすべての要求パラメーターを同じままにします。
  • 応答が next_page_token を省略するか、空の値として返すまで繰り返します。その応答が最後のページです。ページに結果が含まれていない場合でも、ページの要求を継続します。
  • 最初の要求にはpage_tokenを含めないでください。フォローアップ依頼の場合のみ追加してください。

ページサイズを制御するパラメーターはAPIによって異なります。たとえば、一部のAPIはmax_resultsを使用し、他のAPIはpage_sizeを使用し、その他のAPIはlimitを使用します。各endpointでサポートされているパラメーターについては、REST API リファレンスを確認してください。

注記

一部の古い Unity Catalog LIST APIs は、max_resultsを指定した場合にのみページ単位で結果を返します。max_results=0をサーバーがページサイズを選択できるように設定するか、正の値を設定してページサイズを要求します。情報については、「Unity Catalog REST API 操作のページ分割」を参照してください。

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リファレンスを確認してください。

その他のリソース​

このページの見出し