连接到外部 HTTP 服务

2025-06-05

重要

此功能目前以公共预览版提供。

本文介绍如何设置 Lakehouse Federation，以便对不受 Azure Databricks 管理的外部服务数据运行联合查询。若要详细了解 Lakehouse Federation，请参阅“什么是 Lakehouse Federation？”。

若要使用 Lakehouse Federation 连接到外部服务数据库，必须在 Azure Databricks Unity Catalog 元存储中创建以下内容：

与外部服务数据库建立的连接。
一个外部目录，它镜像 Unity Catalog 中的外部服务数据库，以便你可以使用 Unity Catalog 查询语法和数据治理工具来管理 Azure Databricks 用户对数据库的访问权限。

在您开始之前

工作区要求：

已为 Unity Catalog 启用工作区。

计算要求：

计算资源与目标数据库系统之间的网络连接。请参阅 Lakehouse Federation 网络建议。
Azure Databricks 计算必须使用 Databricks Runtime 15.4 LTS 或更高版本以及标准或专用访问模式。
SQL 仓库必须是专业或无服务器，并且必须使用 2023.40 或更高版本。

所需的权限：

若要创建连接，你必须是元存储管理员或对附加到工作区的 Unity Catalog 元存储具有 CREATE CONNECTION 权限的用户。
若要创建外部目录，你必须对元存储具有 CREATE CATALOG 权限，并且是连接的所有者或对连接具有 CREATE FOREIGN CATALOG 特权。

后面的每个基于任务的部分中都指定了其他权限要求。

使用以下方法之一设置外部服务的身份验证：
- Bearer令牌：获取用于简单令牌身份验证的Bearer令牌。
- OAuth 2.0 计算机到计算机：创建和配置应用以启用计算机到计算机身份验证。
- OAuth 2.0 用户到计算机共享：通过用户交互进行身份验证，以便在服务标识和计算机之间共享访问权限。
- OAuth 2.0 用户对机器的逐个用户认证：通过每个用户的交互进行身份验证，以便访问用户身份与机器之间的连接。

外部服务的身份验证方法

持有者令牌： 持有者令牌是一种简单的基于令牌的身份验证机制，其中令牌颁发给客户端，用于访问资源，而无需其他凭据。令牌包含在请求标头中，只要令牌有效，就授予访问权限。

OAuth 计算机到计算机（建议）： 当两个系统或应用程序在没有直接用户参与的情况下进行通信时，将使用 OAuth 计算机到计算机（M2M）身份验证。令牌颁发给已注册的计算机客户端，该客户端使用自己的凭据进行身份验证。这非常适合不需要用户上下文的服务器到服务器通信、微服务和自动化任务。 Databricks 建议在可用时使用 OAuth 机器对机器。

OAuth 用户到计算机共享： OAuth 用户到计算机共享身份验证允许单个用户标识在多个客户端或用户之间进行身份验证和共享同一组凭据。所有用户共享相同的访问令牌。此方法适用于具有一致用户标识的共享设备或环境，但会降低个人责任和跟踪。在需要标识登录的情况下，请选择“用户到计算机共享”。

每用户的 OAuth 用户到机器认证： OAuth 用户到机器的每用户身份认证允许每个用户身份进行认证，并使用自己的凭据访问资源。每个用户都颁发了唯一的访问令牌，可实现单个访问控制、审核和问责。当需要用户特定的数据访问以及代表单个用户访问外部服务时，此方法适用。

外部服务必须符合 OAuth 2.0 规范

使用 OAuth 的 HTTP 连接必须连接到符合官方 OAuth 2.0 规范的服务，以便处理和返回访问令牌数据。这意味着服务的响应必须使用规范中描述的确切字段名称和数据格式，例如 access_token， expires_in等等。

如果在使用 OAuth 2.0 连接到外部服务时遇到问题，请检查服务的响应是否遵循这些要求。

创建与外部服务的连接

首先，创建与外部服务的 Unity 目录连接，该连接指定用于访问该服务的路径和凭据。

使用 Unity 目录连接的好处包括：

安全凭据管理： 机密和令牌安全地存储在 Unity 目录中和管理，确保它们永远不会向用户公开。
精细访问控制： Unity Catalog 允许对具有 USE_CONNECTION 和 MANAGE_CONNECTION 权限的连接实施精细控制，决定谁可以使用或管理这些连接。
针对特定主机的令牌强制实施： 令牌仅限于连接创建时指定的主机 host_name 上使用，以确保它们不能用于未经授权的主机。

所需的权限：具有 CREATE CONNECTION 特权的元存储管理员或用户。

使用以下方法之一创建连接：

使用目录资源管理器用户界面。
在 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中执行 CREATE CONNECTION SQL 命令。
使用 Databricks REST API 或 Databricks CLI 创建连接。请参阅 POST /api/2.1/unity-catalog/connections 和 Unity Catalog 命令。

目录资源管理器

使用 Catalog Explorer UI 创建连接。

在 Azure Databricks 工作区中，单击目录。
在目录窗格顶部，单击“添加”或“加号”图标，然后从菜单中选择“添加连接”。

或者，在“快速访问”页中，单击“外部数据 >”按钮，转到“连接”选项卡，然后单击“创建连接。
单击“ 创建连接”。
输入用户友好的连接名称。
选择“HTTP”作为“连接类型”。
从以下选项中选择 身份验证类型：
- 持有者令牌
- OAuth 计算机到计算机
- OAuth 用户到计算机共享
- OAuth 用户与每用户对应的机器

在 身份验证 页上，输入 HTTP 连接的以下连接属性。

对于持有者令牌：

资产	DESCRIPTION	示例值
主机	Databricks 工作区或部署的基本 URL。	`https://databricks.com`
端口	用于连接的网络端口，通常 `443` 用于 HTTPS。	`443`
持有者令牌	用于授权 API 请求的身份验证令牌。	`bearer-token`
基本路径	API 终结点的根路径。	`/api/`

对于 OAuth 计算机到计算机令牌：

资产	DESCRIPTION
客户端 ID	所创建应用程序的唯一标识符。
客户端密码	为创建的应用程序生成的机密或密码。
OAuth 权限	在用户授权过程中需要授予的权限范围。范围参数表示为以空格分隔的区分大小写的字符串列表。例如：`channels:read channels:history chat:write`
令牌接口	由客户端用来通过演示其授权授予或刷新令牌来获取访问令牌。通常采用以下格式： `https://authorization-server.com/oauth/token`

对于 OAuth 用户到计算机共享令牌：

系统将提示你使用 OAuth 凭据登录。你使用的凭据将由使用此连接的任何人共享。某些提供程序需要重定向 URL 的允许列表，请包含 <databricks_workspace_url>/login/oauth/http.html 为重定向 URL 允许列表。示例：https://databricks.com/login/oauth/http.html

资产	DESCRIPTION
客户端 ID	所创建应用程序的唯一标识符。
客户端密码	为创建的应用程序生成的机密或密码。
OAuth 权限	在用户授权过程中需要授予的权限范围。范围参数表示为以空格分隔的区分大小写的字符串列表。例如：`channels:read channels:history chat:write`
授权终结点	用于通过用户代理重定向向资源所有者进行身份验证。通常采用以下格式： `https://authorization-server.com/oauth/authorize`
令牌接口	由客户端用来通过演示其授权授予或刷新令牌来获取访问令牌。通常采用以下格式： `https://authorization-server.com/oauth/token`

对于 OAuth 用户到计算机每用户令牌：

首次使用 HTTP 连接时，系统会提示每个用户使用其单独的 OAuth 凭据登录。某些提供程序需要重定向 URL 的允许列表，请包含 <databricks_workspace_url>/login/oauth/http.html 为重定向 URL 允许列表。示例：https://databricks.com/login/oauth/http.html

资产	DESCRIPTION
客户端 ID	所创建应用程序的唯一标识符。授权服务器用于在 OAuth 流期间标识客户端应用程序。
客户端密码	为创建的应用程序生成的机密或密码。它用于在交换令牌的授权代码时对客户端应用程序进行身份验证，必须保密。[1][5][6]
OAuth 权限	在用户授权过程中需要授予的权限范围。以空格分隔的、区分大小写的字符串列表表示，用于定义应用程序请求的权限。例如：`channels:read channels:history chat:write`
授权终结点	用于通过用户代理对资源所有者的重定向进行身份验证并获得授权的端点。通常采用以下格式： `https://authorization-server.com/oauth/authorize` 客户端将用户定向到此终结点以登录并同意权限。
令牌接口	客户端使用的终结点，用于将授权凭证（例如授权码）或刷新令牌交换为访问令牌。通常采用以下格式： `https://authorization-server.com/oauth/token`

单击“ 创建连接”。

SQL

使用 CREATE CONNECTION SQL 命令创建连接。

注释

不能使用 SQL 命令创建使用“OAuth 计算机到用户共享”的连接。请参阅目录资源管理器用户界面说明。

若要使用 Bearer 令牌创建新连接，请在笔记本或 Databricks SQL 查询编辑器中运行以下命令：

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token '<bearer-token>'
);

Databricks 建议对敏感值（如凭据）使用机密而不是纯文本字符串。例如：

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token secret ('<secret-scope>','<secret-key-password>')
)

若要使用 OAuth 计算机到计算机创建新连接，请在笔记本或 Databricks SQL 查询编辑器中运行以下命令：

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  client_id '<client-id>'
  client_secret '<client-secret>'
  oauth_scope '<oauth-scope1> <oauth-scope-2>'
  token_endpoint '<token-endpoint>'
)

将 HTTP 请求发送到外部系统

有了连接后，了解如何使用 http_request 内置 SQL 函数将 HTTP 请求发送到服务。

所需的权限：连接对象上的 USE CONNECTION。

在笔记本或 Databricks SQL 编辑器中运行以下命令。替换占位符的值：

connection-name：指定主机、端口、base_path和访问凭据的连接对象。
http-method：用于进行调用的 HTTP 请求方法。例如：GET、POST、PUT、DELETE
path：用于在 base_path 后连接以调用服务资源的路径。
json：与请求一起发送的 JSON 正文。
headers：用于指定请求头的映射。

SELECT http_request(
  conn => <connection-name>,
  method => <http-method>,
  path => <path>,
  json => to_json(named_struct(
    'text', text
  )),
  headers => map(
    'Accept', "application/vnd.github+json"
  )
);

注释

针对“用户到机器每用户”连接类型，阻止了 SQL 访问 http_request。请改用 Python Databricks SDK。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod

WorkspaceClient().serving_endpoints.http_request(
  conn="connection-name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra-header-key": "extra-header-value"},
)

将 HTTP 连接用于代理工具

AI 代理可以使用 HTTP 连接通过 HTTP 请求通过 API 访问外部应用程序，例如 Slack、Google Calendar 或任何服务。代理可以使用外部连接的工具自动执行任务、发送消息以及从第三方平台检索数据。

请参阅将 AI 代理工具连接到外部服务。

通过