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

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

要求

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

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

身份验证方法

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

本地开发

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

1. 使用 CLI 登录：

   databricks auth login --host https://<workspace-url> --profile my-env
   

   Azure Databricks 建议使用 OAuth 用户到计算机 （U2M） 身份验证。

2. 生成访问令牌：

   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。

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

2. 使用 Azure 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()

指定用户授权的 OAuth 范围

使用 Azure Databricks CLI 或 SDK 进行统一身份验证时，如上一部分所示，工具会自动请求基本 all-apis 范围。 但是，如果你的应用使用 用户授权，则必须使用自定义 OAuth 流手动请求具有其他范围的访问令牌。

确保访问令牌包括 编辑>用户授权中配置的作用域。 如果令牌没有所需的范围，则请求可能会失败，并出现 401 或 403 错误。

例如，以下请求显式请求具有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}"}
)

使用 SDK 的 Python

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 权限范围。 CLI 和 SDK 工具仅提供基本的权限范围，这可能不足以满足用户授权需求。

权限被拒绝（403 错误）

检查下列各项：

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

找不到应用（404 错误）

检查下列各项：

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

网络连接问题

检查下列各项：

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

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

其他资源

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

• 手册：从本地计算机进行连接
• 指南：从外部应用程序进行连接
• 食谱：从其他应用进行连接
• 为 Databricks 应用配置权限
• 设置 Databricks Apps 工作区和开发环境
• Databricks CLI 的身份验证
• Databricks 统一身份验证