Azure Databricks REST API

本頁介紹 Azure Databricks REST API、如何呼叫它，以及一些最佳實務。

欲了解 Databricks REST API 的完整參考，請參閱 Databricks REST API 參考資料。

Note

除了進階情境外，Databricks 建議使用 Databricks SDK 或 Databricks CLI 來程式化管理 Databricks 物件，而非 Databricks REST API。

Workspace 與 Account REST API 的比較

Azure Databricks 提供兩組 REST API。 Workspace API 管理單一工作區內的資源，例如叢集、工作、筆記本和 Unity 目錄物件，你可以用工作區 URL 作為主機來呼叫它們。帳號 API 管理帳號範圍的資源，例如使用者與群組配置、工作區建立、網路與帳單設定，以及帳號層級的 Unity 目錄設定，你可以用帳號主控台的登入 URL 和帳號 ID 呼叫它們。

關於每個集合中可用的操作，請參見工作區 API 參考與帳戶 API 參考。

呼叫 REST API

Databricks REST API 呼叫包含以下元件：

視其為工作區端點或帳戶端點而定，會是下列其中一種：
- 您的 Databricks 工作區網址
- 你的 Databricks 帳號主控台登入網址與帳號 ID
REST API 操作類型，例如 GET、 POST、 PATCH或 DELETE。
REST API 操作路徑，例如 /api/2.0/clusters/get。
Databricks 的認證資訊，例如 Databricks OAuth 令牌。
任何由 REST API 操作支援的請求有效載荷或請求查詢參數，例如叢集的 ID。

關於如何結構化 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 User， List 端點，以返回 Databricks 帳號中由下列 <account_id>識別的使用者：

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())

最佳做法

以下章節將說明隨著工作區資料成長的一些效能最佳實踐。

分頁 LIST API 回應

LIST API 會以頁面形式回傳結果，而非單一大型回應。要取得完整的結果集，先請求第一個頁面，然後在回應中使用該標記請求後續頁面，直到沒有標記回傳為止。

若要逐頁瀏覽完整的結果集：

在您的請求中設定 max_results=0。這讓伺服器能選擇適當的頁面大小，比起每頁請求固定數量的結果更有效率。
從每個回應中讀取 next_page_token 欄位。要請求下一頁，請將該值輸入 page_token 下一次請求的查詢參數。
重複此程序，直到回應中省略 next_page_token 或將其作為空值傳回。那個回覆是最後一頁。
不要在第一個請求中包含 page_token 。僅在後續要求時新增。

以下範例使用此模式，從 Unity 目錄資料表、List 端點擷取結構中的每個資料表。同樣的迴圈適用於任何 LIST API。只有響應中陣列欄位的端點和名稱會改變。例如，Grants 端點會以 privilege_assignments 陣列傳回結果，而非 tables。

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 速率限制。

精簡回應欄位以提升效能

有些 LIST API 回傳的欄位計算成本高或回應量很大。當你不需要這些欄位時，可以使用省略它們的請求參數來減少回應大小並改善延遲。

例如， Unity 目錄資料表 API 支援以下參數：

omit_properties=true：在回應中省略了每個表格中的欄位 properties 。
omit_columns=true：在回應中省略了每個表格中的欄位 columns 。

如果你只是為了取得資料表名稱而列出資料表，設定兩個參數會回傳較小的回應，且列出資料表的速度會更快。請參考 REST API 參考，了解每個端點支援的欄位修剪參數。

其他資源

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-29