Azure Databricks REST API

本页介绍了 Azure Databricks REST API、如何调用它以及一些最佳实践。

有关Databricks REST API的完整参考，请参见 Databricks REST API参考文献。

注释

除高级场景外，Databricks 建议使用 Databricks SDK 或 Databricks CLI 代替 Databricks REST API 来程序管理 Databricks 对象。

Workspace 与 Account REST API 的区别

Azure Databricks 提供两组 REST API。 Workspace API 管理单个工作区内的资源，比如集群、作业、笔记本和 Unity 目录对象，你用工作区 URL 作为主机调用它们。账户API管理全账户资源，如用户和组配置、工作区创建、网络和计费配置以及账户级Unity Catalog设置，你通过账户控制台登录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 端点，触发已有作业的预演。假定 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 端点，返回由 <account_id> 标识的 Databricks 账户中的用户：

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 Catalog Table, List 端点检索某个架构中的所有表。同样的循环适用于任何 LIST API。只有响应中数组字段的端点和名称会发生变化。例如， Grant 端点返回的结果是一个 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