本页介绍了 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 调用包含以下组件:
- 根据其是工作区端点还是账户端点,则为以下两者之一:
- 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 以页面形式返回结果,而不是单个大型响应。 要获取完整的结果集,先请求第一个页面,然后在响应中使用令牌请求后续每一个页面,直到没有令牌返回为止。
要逐页查看完整结果集:
- 读取每个响应中的
next_page_token字段。 要请求下一页,只需在下一个请求的page_token查询参数中传递该值,其他请求参数保持不变。 - 重复执行,直到响应中不包含
next_page_token或将其返回为空值。 那条回复是最后一页。 即使页面没有结果,也要继续请求页面。 - 不要在第一个请求中包含
page_token。 仅在后续请求中添加它。
控制页面大小的参数因 API 而异。 例如,有些API使用max_results,有些使用page_size,另一些使用limit。 查看 REST API参考 ,了解每个端点支持的参数。
注释
一些较旧的 Unity Catalog LIST API 只有在你指定 max_results 时才会以分页形式返回结果。 设置 max_results=0 以便允许服务器选择页面大小,或者设置一个正数值以请求页面大小。 有关详细信息,请参阅对 Unity Catalog REST API 操作进行分页。
处理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 参考文档,了解各个端点支持的字段裁剪参数。