Databricks APIは、ワークスペースのジョブ、クラスタ、カタログ、ユーザーなどをHTTPで操作するための公式のREST APIです。外部の業務システムやワークフロー基盤からジョブを起動したり、実行結果を監視したりするときの入口になります。この記事では2026年11月16日時点の公式ドキュメントをもとに、ワークスペースAPIとアカウントAPIの呼び分け、OAuth M2Mでのトークン取得、Jobs API 2.2でのジョブ実行と状態の判定、Python SDKでの書き方、レート制限への備えまでをcurlとPythonのコード付きで整理します。
まとめ:Databricks APIはOAuth M2Mで認証しJobs API 2.2で動かす
押さえることは3つです。1つ目は、認証に個人アクセストークン(PAT)ではなくサービスプリンシパルのOAuth M2Mを使うことです。PATは公式ドキュメントでレガシー扱いになっています。2つ目は、ジョブの操作にJobs API 2.2を使い、実行状態は非推奨のstateではなくstatusで判定することです。
3つ目は、Pythonから呼ぶならREST APIを直接書かずにDatabricks SDK for Pythonを使うことです。待機、ページング、429の再試行をSDKが引き受けるため、自前で書くコードが減ります。Databricksの全体像と料金の考え方は、親記事のDatabricksとは?できること・DBU課金の料金と業種別の費用・導入事例にまとめています。
Databricks REST APIの全体像:ワークスペースAPIとアカウントAPI
公式のREST APIの概要ページ(2026年10月30日更新)は、APIを2種類に分けています。ジョブやクラスタなどワークスペースの中のリソースを扱うワークスペースAPIと、ユーザーやワークスペースそのものなどアカウント全体を扱うアカウントAPIです。
ワークスペースURLとアカウントURLで変わるエンドポイントの組み立て
ワークスペースAPIはワークスペースのURLをホストにし、その後ろに/api/<版>/<リソース>を続けます。アカウントAPIはアカウントコンソールのURLをホストにし、パスにアカウントIDを含めます。
# ワークスペースAPI:クラスタの一覧
curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
-H "Authorization: Bearer $DATABRICKS_TOKEN"
# アカウントAPI:アカウントのユーザー一覧(ACCOUNT_IDはアカウントコンソールで確認)
curl -X GET "https://accounts.cloud.databricks.com/api/2.0/identity/accounts/$ACCOUNT_ID/users" \
-H "Authorization: Bearer $OAUTH_TOKEN"
公式ページは、高度な用途を除いてREST APIを直接呼ぶよりSDKかCLIを使うよう勧めています。REST APIを直接書く場面は、Python以外の言語から呼ぶときや、外部のワークフロー基盤のHTTPタスクから呼ぶときに絞るのが現実的です。
Jobs API 2.2を選ぶ理由とhas_more廃止・ページングの変更点
ジョブのAPIには2.0、2.1、2.2の版があり、2.1から2.2への移行ガイド(2026年11月5日更新)は、スクリプトやクライアントで2.2を使うよう推奨しています。古い記事のコードを流用するときは、次の違いで動きが変わります。
- 2.2で作ったジョブはキューイングが既定で有効になる(2.0・2.1で作ったジョブは既定で無効)
- ジョブ1件や実行1件の取得で、tasksやjob_clustersなどの配列は1レスポンス100要素までになり、超えると
next_page_tokenが返る - ジョブ一覧と実行一覧のレスポンス直下の
has_moreが削除され、続きの有無はnext_page_tokenの有無で判断する - 実行の取得に
only_latestが加わり、リトライや修復で置き換えられた実行を除外できる
has_moreを見てループを止める2.1向けのコードは、2.2に切り替えると判定を誤ります。版を上げるときは、一覧の取得処理から先に書き直します。
OAuth M2Mでアクセストークンを取得しcurlでAPIを呼ぶ手順
外部システムから人の操作なしにAPIを呼ぶ場合、サービスプリンシパルのクライアントIDとOAuthシークレットでトークンを取得します。手順はサービスプリンシパルのOAuthのページ(2026年11月12日更新)に沿っています。
サービスプリンシパルにOAuthシークレットを発行する際の上限と失効
シークレットは、ワークスペースの設定画面の「Identity and access」からサービスプリンシパルを選び、「Secrets」タブで発行します。運用の前に、次の制約を把握しておきます。
- 有効期間は日数で指定し、最大730日
- 1つのサービスプリンシパルに持てるシークレットは最大5個
- 90日間使われなかったシークレットは自動で削除される
- シークレットの値は発行時に1回しか表示されない
5個まで持てるので、期限が来る前に新しいシークレットを発行し、呼び出し側を切り替えてから古い方を消す手順で無停止の差し替えができます。
トークンエンドポイントにclient_credentialsで要求するcurlの例
ワークスペース単位のトークンエンドポイントはhttps://<ワークスペースのホスト>/oidc/v1/tokenです。取得したトークンの有効期間は1時間で、レスポンスのexpires_inは3600になります。
export DATABRICKS_HOST=https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
export CLIENT_ID=00000000-0000-0000-0000-000000000000
export CLIENT_SECRET="$(cat /run/secrets/dbx_sp_secret)"
# アクセストークンを取得する(jqでaccess_tokenだけを取り出す)
export DATABRICKS_TOKEN=$(curl -s --request POST \
--url "$DATABRICKS_HOST/oidc/v1/token" \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis' | jq -r '.access_token')
# 取得したトークンでワークスペースAPIを呼ぶ
curl -s "$DATABRICKS_HOST/api/2.2/jobs/list?limit=5" \
-H "Authorization: Bearer $DATABRICKS_TOKEN"
トークンは1時間で切れるため、長く動く処理では期限の前に取り直す作りにします。SDKを使えばこの更新は内部で行われるので、次の章の書き方では意識しなくて済みます。
PATを使う既存連携での90日未使用による失効と管理者による無効化
PATのページ(2026年10月7日更新)は、タイトルにレガシーと明記し、ユーザーの認証にはOAuthを推奨しています。90日間使われなかったPATは自動で失効し、ワークスペース管理者によるトークンの利用自体の無効化も可能です。既存の連携がPATで動いている場合、ある日突然401になる原因はこの2つを疑います。新しく作る連携はOAuth M2Mで組み、PATは手元の検証用にとどめるのが安全です。
REST APIでジョブを実行しrun_idで完了まで状態を追う手順
ジョブの起動はPOST /api/2.2/jobs/run-now、実行状態の取得はGET /api/2.2/jobs/runs/getです。run-nowはジョブの完了を待たず、実行IDを返した時点で戻ります。
run-nowでのジョブ引数と冪等トークンの指定による二重起動の防止
run-nowのリファレンスによると、idempotency_tokenを付けると、同じトークンの実行が既にある場合は新しい実行を作らず既存の実行IDを返します。トークンは64文字以内です。通信エラーで応答を受け取れなかったときに同じトークンで再送すれば、ジョブが2回走る事故を防げます。
curl -s -X POST "$DATABRICKS_HOST/api/2.2/jobs/run-now" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"job_id": 123456789012345,
"job_parameters": { "target_date": "2026-11-15" },
"idempotency_token": "daily-orders-2026-11-15"
}'
# 応答の例:{"run_id": 455644833, "number_in_job": 455644833}
応答のnumber_in_jobは非推奨で、run_idと同じ値です。後続の処理ではrun_idだけを使います。冪等トークンには、上の例のようにジョブ名と対象日を組み合わせた値を使うと、同じ日の処理を二重に起動しない意味をそのまま表せます。
runs/getでの実行状態と終了詳細の取得によるジョブの成否判定
実行取得のリファレンスでは、従来のstate(life_cycle_stateとresult_state)は非推奨とされ、statusを使うよう案内されています。status.stateがTERMINATEDになったら、status.termination_details.codeで成否を見ます。
RUN_ID=455644833
while true; do
RES=$(curl -s "$DATABRICKS_HOST/api/2.2/jobs/runs/get?run_id=$RUN_ID" \
-H "Authorization: Bearer $DATABRICKS_TOKEN")
STATE=$(echo "$RES" | jq -r '.status.state')
echo "state=$STATE"
[ "$STATE" = "TERMINATED" ] && break
sleep 30
done
echo "$RES" | jq '.status.termination_details | {code, type, message}'
echo "$RES" | jq -r '.run_page_url'
codeがSUCCESSなら成功です。typeはSUCCESS、CLIENT_ERROR、INTERNAL_ERROR、CLOUD_FAILUREのいずれかで、CLIENT_ERRORはジョブの設定やコードの側、CLOUD_FAILUREはクラウド側の要因と切り分けられます。通知にはrun_page_urlを添えると、受け取った担当者が実行画面へすぐ移れます。
Python SDKでジョブ実行とクラスタ操作を書き待機とページングを任せる
Databricks SDK for Pythonのページ(2026年11月11日更新)によると、SDKはBetaですが本番で使ってよいとされ、Beta期間中はマイナー版を固定するよう推奨されています。最新版は2026年11月12日公開のv0.166.0で、リリースはほぼ毎日出ています。
WorkspaceClientの環境変数認証とPython SDKの導入手順
Python 3.8以上の環境にdatabricks-sdkを入れます。WorkspaceClient()を引数なしで作ると、SDKが環境変数や.databrickscfgから認証情報を探します。OAuth M2Mなら、ホスト、クライアントID、シークレットの3つを環境変数で渡すだけです。
# マイナー版を固定して入れる
pip install "databricks-sdk==0.166.*"
export DATABRICKS_HOST=https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
export DATABRICKS_CLIENT_ID=00000000-0000-0000-0000-000000000000
export DATABRICKS_CLIENT_SECRET="$(cat /run/secrets/dbx_sp_secret)"
SDKのリポジトリの説明では、認証情報の探索順は、コードに直接書いた値、Databricks固有の環境変数、.databrickscfgのDEFAULTプロファイルの順です。コードへの直書きは非推奨とされているので、本番では環境変数かシークレット管理の仕組みから渡します。
run_nowのWaitによる完了待機と既存クラスタの起動確認
SDKのジョブのリファレンスでは、w.jobs.run_now()の戻り値はWait[Run]です。.response.run_idで実行IDを取り出せ、.result()を呼ぶと完了まで待ちます。
import datetime
from databricks.sdk import WorkspaceClient
w = WorkspaceClient() # 環境変数のOAuth M2Mで認証される
# 既存のクラスタを使うジョブなら、先に起動しておく(停止中なら起動して待つ)
w.clusters.ensure_cluster_is_running("0123-456789-abcdefgh")
# ジョブを起動し、実行IDを控えてから完了を待つ
waiter = w.jobs.run_now(
job_id=123456789012345,
job_parameters={"target_date": "2026-11-15"},
idempotency_token="daily-orders-2026-11-15",
)
print("run_id:", waiter.response.run_id)
run = waiter.result(timeout=datetime.timedelta(minutes=60))
print(run.status.state, run.status.termination_details.code, run.run_page_url)
# 一覧はイテレータで返り、次ページの取得はSDKが行う
for r in w.jobs.list_runs(job_id=123456789012345, completed_only=True, limit=25):
print(r.run_id, r.status.state if r.status else None)
完了を待つ用途にはrun_now_and_wait()もあり、こちらは既定のタイムアウトが20分です。20分を超えるジョブでは、上の例のようにtimeoutを明示します。ジョブの完了を外部システム側で長時間待てない場合は、run_idだけを保存して処理を返し、別の定期処理で状態を確かめる構成に分けます。
レート制限429とページングを踏まえた本番スクリプトの組み方
単発の動作確認では問題なく動いても、本番で件数が増えると、制限値とページングの扱いで止まります。
run-now毎秒20件などワークスペース単位の上限と指数バックオフ
リソースの上限のページ(2026年11月13日更新)では、ワークスペース単位で次のような上限が決まっています。
| 対象 | 上限 |
|---|---|
| jobs/run-now | 毎秒20リクエスト |
| jobs/runs/get | 毎秒100リクエスト |
| jobs/runs/submit | 毎秒35リクエスト |
| jobs/list | 毎秒20リクエスト |
| 同時に実行できるタスク | 2,000 |
| 1時間に作成できるジョブ | 10,000 |
上限を超えるとHTTP 429が返ります。REST APIの概要ページは、指数バックオフとジッターで再試行し、Retry-Afterヘッダーがあればその秒数以上待つよう推奨しています。SDKは429と503を既定で最大300秒まで再試行するため、Pythonで書く場合はSDKに再試行を任せる構成が可能です。REST APIを直接呼ぶ場合は、状態の確認を数十件のジョブに対して並列に回すと上限に当たりやすいので、確認の間隔を空けるか、一覧の取得でまとめて状態を見る形にします。
next_page_tokenで一覧を取り切りリトライは冪等トークンと組む
一覧系のAPIは結果をページに分けて返し、レスポンスのnext_page_tokenを次のリクエストのpage_tokenに渡して続きを取ります。next_page_tokenが無くなったら終わりです。REST APIを直接使う場合の書き方を示します。
import os, random, time, requests
HOST = os.environ["DATABRICKS_HOST"]
HEADERS = {"Authorization": f"Bearer {os.environ['DATABRICKS_TOKEN']}"}
def get(path, params):
# 429のときはRetry-Afterか指数バックオフ+ジッターで待って再試行する
for attempt in range(6):
res = requests.get(f"{HOST}{path}", headers=HEADERS, params=params, timeout=60)
if res.status_code != 429:
res.raise_for_status()
return res.json()
wait = float(res.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait + random.uniform(0, 1))
raise RuntimeError("429が続いたため中断")
jobs, token = [], None
while True:
params = {"limit": 100, **({"page_token": token} if token else {})}
page = get("/api/2.2/jobs/list", params)
jobs.extend(page.get("jobs", []))
token = page.get("next_page_token")
if not token:
break
print(len(jobs), "件")
GETの再試行は何度行っても副作用がありません。一方でrun-nowのような起動系のPOSTを再試行するときは、前の章のidempotency_tokenを必ず付けます。付けずに再送すると、1回目が実は受け付けられていた場合にジョブが2回走ります。
Databricks APIの採用条件とCLI・バンドルで足りる場面の判断
判断の軸は、呼び出し元がDatabricksの外の仕組みか、人やCI/CDか、の2つです。
外部システムからジョブを起動するならSDKかREST APIを採用する判断
採用すべきなのは、基幹システムのバッチ完了や受注データの取り込み完了など、Databricksの外で起きた出来事をきっかけにジョブを動かしたい場合です。固定時刻のスケジュールで動かすと、外部の処理が遅れた日には未完了のデータのまま集計が走ります。外部の処理の最後にAPIを呼べば、その処理の完了時点をジョブの開始タイミングにすることが可能です。呼び出し元がPythonならSDK、Javaや外部のワークフロー基盤のHTTPタスクならREST APIを使い、どちらもOAuth M2Mのサービスプリンシパルで認証します。サービスプリンシパルに与えるのはジョブの実行に必要な権限だけで、テーブルへの権限の制限にはUnity Catalogを使う構成です。権限の継承はUnity Catalogとは?3レベル名前空間と権限継承・移行判断で解説しています。
定義の管理や手元の操作ではAPIを見送りCLIとバンドルに寄せる判断
次の場合は、APIを自前で呼ぶコードを書きません。
- ジョブやパイプラインの定義を作る・変える(バンドルのYAMLで管理し、CI/CDから反映する)
- 開発者が手元で実行や確認をする(CLIの
databricks jobs run-nowやdatabricks apiで足りる) - SQLの結果を取り出して画面に出す(SQLウェアハウスとBIの機能を使う)
CLIのインストール、認証プロファイル、バンドルでのCI/CDはDatabricks CLIの使い方に、SQLウェアハウスでのクエリ実行はDatabricks SQLの使い方にまとめています。外部システムとの連携の設計から、サービスプリンシパルと権限の設計、ジョブの監視までをまとめて任せたい場合は、一創のデータ分析基盤構築・MLOps構築支援で引き受けています。
Databricks APIの認証とジョブ実行で詰まりやすい点のよくある質問
databricks api を使い始めるときによく聞かれる質問に、2026年11月16日時点の公式ドキュメントをもとに答えます。
REST APIのバージョンは2.0・2.1・2.2のどれを使えばよいですか?
ジョブのAPIは2.2を使います。公式の移行ガイドが推奨しているのは2.2で、実行取得のリファレンスに記載されているのも2.2のパスです。クラスタの一覧など、ジョブ以外のAPIは公式リファレンスに載っている版のパスをそのまま使います。版によって一覧の続きの判定方法が違うため、版を混ぜて書いたコードは見直します。
PATとOAuth M2Mのどちらで認証すべきですか?
外部システムからの連携ならOAuth M2Mです。PATは公式ドキュメントでレガシー扱いになっており、人に紐づくため、担当者の異動や退職で連携が止まる要因にもなります。サービスプリンシパルのOAuth M2Mなら人と切り離され、トークンも1時間で失効するため、漏れた場合の影響が小さく済みます。
Python SDKはBetaですが本番で使えますか?
Python SDKはBetaでも本番での使用が可能です。公式ドキュメントは、Betaであっても本番で使ってよいとしたうえで、マイナー版を固定するよう推奨しています。将来の版でインターフェースが変わる可能性があると明記されているので、requirements.txtで版を固定し、上げるときは検証環境で動作を確かめてから本番に反映します。
run-nowの応答はすぐ返るのにジョブが終わっていないのはなぜですか?
run-nowはジョブを起動した時点で実行IDを返し、完了は待たない仕組みだからです。完了を知るには、runs/getでstatus.stateがTERMINATEDになるまで間隔を空けて確かめるか、SDKの.result()で待ちます。2.2で作ったジョブはキューイングが既定で有効なため、同時実行の上限に当たるとQUEUEDのまま待つこともあります。
AWS以外のAzure DatabricksやGoogle Cloudでも同じコードで動きますか?
ワークスペースAPIのパスと、SDKのWorkspaceClientを使う書き方は共通です。違いが出るのは認証で、SDKの既定の認証はDatabricks独自の方式に続いてAzureやGoogle Cloudの方式を順に試します。Azure DatabricksでMicrosoft Entra IDのトークンを使う場合など、クラウド固有の認証を使うときに手順の確認先となるのは、各クラウド版の公式ドキュメントです。練習にはDatabricks Free Editionのワークスペースも使えます。
関連記事
- Databricksとは?できること・DBU課金の料金と業種別の費用・導入事例【2026年10月】:Databricks全体の機能とDBU単価
- Databricks CLIの使い方:インストール・OAuth認証・バンドルでのCI/CD設定【2026年11月】:CLIからのAPI操作とバンドルでの定義管理
- Databricksの使い方:ノートブック作成からDeltaテーブル・ジョブ化までの手順【2026年11月】:APIから起動するジョブの作り方
- Databricks SQLの使い方:SQLウェアハウスの種類・サイズ設計とクエリ実行例【2026年11月】:SQLウェアハウスでのクエリ実行
- Unity Catalogとは?3レベル名前空間と権限継承・移行判断を実装視点で解説【2026年版】:サービスプリンシパルに与える権限の設計