使用令牌身份验证连接到 API Databricks 应用

可以使用 OAuth 2.0 持有者令牌身份验证调用 Databricks 的应用，该应用公开了 HTTP API（例如 FastAPI 或 Gradio 应用）。此方法适用于本地开发环境、外部应用程序和其他Azure Databricks应用。

注释

此方法仅适用于公开 API 或终结点的应用（可通过路由访问 /api/ ）。对于仅提供用户界面或后台处理的应用，无法使用令牌身份验证进行连接。

要求

若要使用令牌身份验证连接到 Databricks 应用，必须满足以下要求：

应用必须公开至少一个可以使用路由访问的 /api/ API 终结点。
你必须对应用具有 CAN USE 权限。请参阅配置 Databricks 应用的权限。
必须使用受支持的身份验证方法之一生成Azure Databricks访问令牌。

身份验证方法

注释

不能使用 Azure Entra ID 令牌直接调用 Databricks 应用。令牌联合需要客户端令牌交换步骤，该过程中 Azure Databricks 不在服务器端执行。若要使用Azure Entra ID令牌进行身份验证，必须先将其交换为 OAuth 令牌。请参阅使用标识提供者令牌进行身份验证。

选择与连接方案匹配的身份验证方法：

本地开发

若要从本地开发环境进行连接，请使用 Databricks CLI 或 SDK 和用户凭据。

使用 CLI 登录：
```
databricks auth login --host https://<workspace-url> --profile my-env
```
Azure Databricks建议使用 OAuth 用户到计算机（U2M）身份验证。

生成访问令牌：

CLI

databricks auth token --profile my-env

Python

from databricks.sdk.core import Config
config = Config(profile="my-env")
token = config.oauth_token().access_token

外部应用程序

若要从外部应用程序进行编程访问，请使用服务主体身份验证和计算机到计算机（M2M）凭据。请参阅使用 OAuth 授权服务主体访问 Azure Databricks。

创建服务主体并获取客户端 ID 和机密。请参阅服务主体。

使用 Databricks SDK 生成访问令牌：

from databricks.sdk import WorkspaceClient
import requests

# Option 1: Explicit credentials
wc = WorkspaceClient(
    host="https://<workspace-url>",
    client_id="<service-principal-client-id>",
    client_secret="<service-principal-client-secret>"
)

# Option 2: Environment variables
# Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
wc = WorkspaceClient()

# Generate Bearer token
headers = wc.config.authenticate()

从其他 Databricks 应用程序

从一个 Databricks 应用连接到另一个应用时，该应用会使用分配的服务主体自动处理身份验证。

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

从 Azure Databricks 笔记本

若要从Azure Databricks笔记本调用应用 API，必须交换笔记本的内部令牌以获取受众范围的 OAuth 令牌，然后使用该令牌查询应用。

获取应用的 OAuth 客户端 ID。使用 Azure Databricks SDK 检索 ID：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
app_client_id = w.apps.get("<app-name>").oauth2_app_client_id

将笔记本令牌交换为针对受众范围的访问令牌。

import requests

url = "https://<workspace-url>/oidc/v1/token"
notebook_token = (
    dbutils.notebook.entry_point.getDbutils()
    .notebook().getContext().apiToken().get()
)

data = {
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": notebook_token,
    "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "all-apis",
    "audience": app_client_id,
}

response = requests.post(url=url, data=data)
audience_token = response.json()["access_token"]

请将audience_token作为Bearer令牌用于调用应用程序。有关示例，请参阅向应用发送请求。

注释

交换令牌的范围限定为特定应用，因此不能使用它来调用其他Azure Databricks API。 scope令牌交换请求中的参数必须与用户授权中为应用配置的作用域相匹配，或成为这些作用域的超集。

指定用户授权的 OAuth 范围

如果应用使用用户授权，则访问令牌必须包含一个为应用配置的作用域的超集。如果令牌没有所需的范围，则请求可能会失败，并出现 401 或 403 错误。

默认情况下，使用 Databricks CLI 生成的令牌包括 all-apis 范围，满足任何应用的用户授权要求：

databricks auth token --profile my-env

要请求特定范围而不是all-apis，可以使用自定义 OAuth 流手动请求具有限定范围的访问令牌。例如，以下请求显式请求具有sql、file.files和dashboards.genie作用域的访问令牌：

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

有关完整说明，请参阅手动生成 OAuth U2M 访问令牌。

向应用发送请求

调用应用的 API 终结点时，请将持有者令牌包含在授权标头中，并替换为 <your-endpoint> 应用的实际 API 路径：

CURL

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

具有请求的Python

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

使用 Python 的 SDK

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

安全注意事项

从本地环境连接到应用时，请遵循以下安全最佳做法：

从不对源代码中的访问令牌进行硬编码。使用环境变量或安全凭据存储。
定期刷新令牌，以最大程度地降低安全风险（如果遭到入侵）。
避免在应用程序日志中记录访问令牌或敏感数据。

Troubleshooting

如果在从本地计算机连接到应用时遇到问题，请尝试这些解决方案。

身份验证失败（401 错误）

检查下列各项：

令牌有效（运行 databricks auth token --profile my-env）
用户配置已正确配置 databricks auth login
令牌尚未过期
令牌包含所需的 OAuth 权限范围。令牌的作用域必须是用户授权中为应用配置的作用域的超集。

权限被拒绝（403 错误）

检查下列各项：

你对应用具有 CAN USE 权限
令牌包含所需的 OAuth 权限范围。范围不足可能会导致 403 错误，即使具有有效权限。

找不到应用（404 错误）

检查下列各项：

ID 和工作区 URL 正确
应用已部署并运行
应用中存在终结点路径

网络连接问题

检查下列各项：

您的网络允许外发 HTTPS 连接
*.databricksapps.com 域可以从您的网络访问

此外，请检查组织是否使用需要配置的代理。

其他资源

有关详细信息，请参阅以下资源：

反馈

此页面是否有帮助？

Last updated on 2026-04-11