Conexión a servicios HTTP externos

Importante

Esta característica está en versión preliminar pública.

En esta página se describe cómo configurar la federación de Lakehouse para ejecutar consultas federadas en datos de servicio externos que Azure Databricks no administra. Para más información sobre La federación de Lakehouse, consulte ¿Qué es La federación de Lakehouse?

Para conectarse a la base de datos de servicio externo mediante Lakehouse Federation, debe crear lo siguiente en el metastore de Azure Databricks Unity Catalog:

Una conexión a la base de datos del servicio externo.
Catálogo externo que refleja la base de datos del servicio externo en el catálogo de Unity para que pueda usar la sintaxis de consulta del catálogo de Unity y las herramientas de gobernanza de datos para administrar el acceso de usuario de Azure Databricks a la base de datos.

Antes de empezar

Requisitos del área de trabajo:

Área de trabajo habilitada para Unity Catalog.

Requisitos de proceso:

Conectividad de red desde su recurso de computación a los sistemas de bases de datos de destino. Consulte Recomendaciones de redes para Lakehouse Federation.
El cómputo de Azure Databricks debe usar Databricks Runtime 15.4 LTS o superior y el modo de acceso estándar o dedicado.
Los almacenes de SQL deben ser pro o sin servidor y deben usar 2023.40 o superior.

Permisos necesarios:

Para crear una conexión, debe ser administrador del metastore o usuario con el privilegio CREATE CONNECTION en el metastore de Unity Catalog adjunto al área de trabajo.
Para crear un catálogo externo, debe tener el permiso CREATE CATALOG en el metastore, y ser el propietario de la conexión o tener el privilegio CREATE FOREIGN CATALOG en la conexión.

Los requisitos de permisos adicionales se especifican en cada sección basada en tareas que se indica a continuación.

Configure la autenticación en el servicio externo mediante uno de los métodos siguientes:
- Token portador: obtenga un token portador para la autenticación sencilla basada en tokens.
- OAuth 2.0 Machine-to-Machine: cree y configure una aplicación para habilitar la autenticación de máquina a máquina.
- OAuth 2.0 Usuario a máquina compartido: autenticación con interacción del usuario para compartir el acceso entre la identidad de servicio y la máquina.
- OAuth 2.0 Usuario a máquina por usuario: autentíquese mediante la interacción individual de cada usuario para establecer acceso entre la identidad del usuario y la máquina.

Métodos de autenticación para servicios externos

token de portador: Un token de portador es un mecanismo de autenticación simple basado en tokens en el que se emite un token a un cliente y se usa para acceder a los recursos sin necesidad de credenciales adicionales. El token se incluye en el encabezado de solicitud y concede acceso siempre que sea válido.

Máquina a máquina de OAuth: La autenticación de máquina a máquina (M2M) de OAuth se usa cuando dos sistemas o aplicaciones se comunican sin intervención directa del usuario. Los tokens se emiten a un cliente de máquina registrado, que usa sus propias credenciales para autenticarse. Esto es ideal para las tareas de comunicación de servidor a servidor, microservicios y automatización en las que no se necesita ningún contexto de usuario. Databricks recomienda usar OAuth de máquina a máquina cuando esté disponible en lugar de OAuth de usuario a máquina compartida.

OAuth Usuario a máquina compartido: La autenticación compartida de usuario a máquina de OAuth permite que una única identidad de usuario se autentique y comparta el mismo conjunto de credenciales en varios clientes o usuarios. Todos los usuarios comparten el mismo token de acceso. Este enfoque es adecuado para dispositivos o entornos compartidos en los que una identidad de usuario coherente es suficiente, pero reduce la responsabilidad y el seguimiento individuales. En los casos en los que se requiera el inicio de sesión de identidad, seleccione Usuario a máquina compartida. Databricks recomienda usar OAuth de máquina a máquina cuando esté disponible en lugar de OAuth de usuario a máquina compartida.

Usuario a máquina de OAuth por usuario: La autenticación de usuario a máquina por usuario de OAuth permite que cada identidad de usuario se autentique y use sus propias credenciales para acceder a los recursos. Cada usuario emite un token de acceso único, lo que permite el control de acceso individual, la auditoría y la responsabilidad. Este método es adecuado cuando se requiere acceso a datos específicos del usuario y al acceder a servicios externos en nombre del usuario individual.

Los servicios externos deben cumplir las especificaciones de OAuth 2.0

Las conexiones HTTP que usan OAuth deben conectarse a los servicios que cumplen con la especificación oficial de OAuth 2.0 para controlar y devolver datos de token de acceso. Esto significa que las respuestas del servicio deben usar los nombres de campo exactos y los formatos de datos descritos en la especificación, como access_token, expires_in, etc.

Si tiene problemas para conectarse a un servicio externo mediante OAuth 2.0, compruebe que las respuestas del servicio siguen estos requisitos.

Crear una conexión al servicio externo

En primer lugar, cree una conexión de Catálogo de Unity al servicio externo que especifique una ruta de acceso y credenciales para acceder al servicio.

Entre las ventajas de usar una conexión de Catálogo de Unity se incluyen las siguientes:

Administración de credenciales seguras: secretos y tokens se almacenan y administran de forma segura en el catálogo de Unity, lo que garantiza que nunca se exponen a los usuarios.
Control de acceso granular: El Catálogo de Unity permite un control detallado de quién puede usar o administrar las conexiones con los privilegios de USE CONNECTION y MANAGE CONNECTION.
Aplicación de tokens específicos del host: los tokens están restringidos a host_name, que se especifica durante la creación de la conexión, lo que garantiza que no se pueden usar con hosts no autorizados.

Permisos necesarios: administrador del metastore o usuario con el privilegio CREATE CONNECTION.

Cree una conexión mediante uno de los métodos siguientes:

Use la interfaz de usuario del Explorador de catálogos.
Ejecute el comando CREATE CONNECTION SQL en un cuaderno de Azure Databricks o en el editor de consultas SQL de Databricks.
Use la API REST de Databricks o la CLI de Databricks para crear una conexión. Vea POST/api/2.1/unity-catalog/connections y Comandos de Unity Catalog.

Explorador de catálogos

Use la interfaz de usuario del Explorador de catálogos para crear una conexión.

En el área de trabajo de Azure Databricks, haga clic en Catálogo.
En la parte superior del panel Catálogo, haga clic en el icono Agregar y seleccione Agregar una conexión en el menú.

Como alternativa, en la página de acceso rápido, haga clic en el botón Datos externos >, vaya a la pestaña Conexiones y haga clic en Crear conexión.
Haga clic en Crear conexión.
Escriba un nombre de conexión fácil de usar .
Seleccione un Tipo de conexión de HTTP.
Seleccione un Tipo de autorización de las siguientes opciones:
- Portador token
- OAuth de máquina a máquina
- OAuth de usuario a la máquina compartida
- OAuth de usuario a máquina por usuario

En la página de autenticación, escriba las siguientes propiedades de conexión para la conexión HTTP.

Para un token de portador:

Propiedad	Descripción	Ejemplo de valor
Anfitrión	La dirección URL base del área de trabajo o la implementación de Databricks.	`https://databricks.com`
Puerto	El puerto de red usado para la conexión, normalmente `443` para HTTPS.	`443`
Token de portador	Token de autenticación que se usa para autorizar solicitudes de API.	`bearer-token`
Ruta de acceso base	Ruta de acceso raíz para los puntos de conexión de API.	`/api/`

Para el token de máquina a máquina de OAuth:

Propiedad	Descripción
Id. de cliente	Identificador único de la aplicación que creó.
Secreto de cliente	Secreto o contraseña generado para la aplicación que creó.
Ámbito de OAuth	Ámbito que se va a conceder durante la autorización del usuario. El parámetro de ámbito se expresa como una lista de cadenas delimitadas por espacios que distinguen entre mayúsculas y minúsculas. Por ejemplo: `channels:read channels:history chat:write`
Punto de conexión de token	Usado por el cliente para obtener un token de acceso mediante la presentación de su concesión de autorización o token de actualización. Normalmente en el formato: `https://authorization-server.com/oauth/token`

Para el token compartido de usuario a máquina de OAuth:

Se le pedirá que inicie sesión con sus credenciales de OAuth. Las credenciales que use serán compartidas por cualquier persona que use esta conexión. Algunos proveedores requieren una lista de permitidos para la dirección URL de redireccionamiento, por favor incluya <databricks_workspace_url>/login/oauth/http.html como la lista de permitidos de la dirección URL de redireccionamiento. Ejemplo: https://databricks.com/login/oauth/http.html

Propiedad	Descripción
Id. de cliente	Identificador único de la aplicación que creó.
Secreto de cliente	Secreto o contraseña generado para la aplicación que creó.
Ámbito de OAuth	Ámbito que se va a conceder durante la autorización del usuario. El parámetro de ámbito se expresa como una lista de cadenas delimitadas por espacios que distinguen entre mayúsculas y minúsculas. Por ejemplo: `channels:read channels:history chat:write`
Punto de conexión de autorización	Se usa para autenticarse con el propietario del recurso a través de la redirección del agente de usuario. Normalmente en el formato: `https://authorization-server.com/oauth/authorize`
Punto de conexión de token	Usado por el cliente para obtener un token de acceso mediante la presentación de su concesión de autorización o token de actualización. Normalmente en el formato: `https://authorization-server.com/oauth/token`

Para el token OAuth de usuario a máquina por usuario:

Se pedirá a cada usuario que inicie sesión con sus credenciales individuales de OAuth la primera vez que use la conexión HTTP. Algunos proveedores requieren una lista de permitidos para la dirección URL de redireccionamiento, por favor incluya <databricks_workspace_url>/login/oauth/http.html como la lista de permitidos de la dirección URL de redireccionamiento. Ejemplo: https://databricks.com/login/oauth/http.html

Propiedad	Descripción
Id. de cliente	Identificador único de la aplicación que creó. Usado por el servidor de autorización para identificar la aplicación cliente durante el flujo de OAuth.
Secreto de cliente	Secreto o contraseña generado para la aplicación que creó. Se usa para autenticar la aplicación cliente al intercambiar códigos de autorización para tokens y debe mantenerse confidencial.
Ámbito de OAuth	Ámbito que se va a conceder durante la autorización del usuario. Se expresa como una lista de cadenas separadas por espacios y sensibles a mayúsculas y minúsculas que definen los permisos que solicita la aplicación. Por ejemplo: `channels:read channels:history chat:write`
Punto de conexión de autorización	Punto de conexión utilizado para autenticar al propietario del recurso mediante el redireccionamiento del agente de usuario y obtener la autorización. Normalmente en el formato: `https://authorization-server.com/oauth/authorize` El cliente dirige al usuario a este punto de conexión para iniciar sesión y dar su consentimiento a los permisos.
Punto de conexión de token	Punto de conexión usado por el cliente para intercambiar una concesión de autorización (por ejemplo, un código de autorización) o un token de actualización para un token de acceso. Normalmente en el formato: `https://authorization-server.com/oauth/token`
Método de intercambio de credenciales de Oauth	Los proveedores requieren diferentes métodos para pasar credenciales de cliente de OAuth durante el intercambio de tokens. Seleccione una de las siguientes opciones: header_and_body: coloca las credenciales en el encabezado de autorización y en el cuerpo de la solicitud (valor predeterminado). body_only: coloca las credenciales solo en el cuerpo de la solicitud sin un encabezado de autorización. header_only: coloca las credenciales solo en el encabezado de autorización (para proveedores como OKTA).

Haga clic en Crear conexión.

SQL

Use el comando CREATE CONNECTION SQL para crear una conexión.

Nota:

No puede usar el comando SQL para crear una conexión que use OAuth Machine-to-User Shared. En su lugar, consulte las instrucciones de la interfaz de usuario del Explorador de catálogos.

Para crear una nueva conexión mediante un token de portador de , ejecute el siguiente comando en un cuaderno o en el editor de consultas SQL de Databricks:

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

Databricks recomienda usar secrets en lugar de cadenas de texto sin cifrar para valores confidenciales, como credenciales. Por ejemplo:

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

Para crear una nueva conexión mediante OAuth Machine-to-Machine, ejecute el siguiente comando en un cuaderno o en el editor de consultas SQL de Databricks:

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>'
)

Conceda USE CONNECTION privilegios a las entidades de seguridad de identidad que necesitan usar la conexión:

En su área de trabajo, vaya a Catálogo>Conexiones> Sus > de conexión.
Conceda a las identidades el acceso adecuado al Unity Catalog.

Envío de una solicitud HTTP al sistema externo

Ahora que tiene una conexión, aprenda a enviar solicitudes HTTP al servicio mediante la función SQL integrada http_request.

Permisos necesarios:USE CONNECTION en el objeto de conexión.

Ejecute el siguiente comando SQL en un cuaderno o en el editor de SQL de Databricks. Reemplace los valores de marcador de posición:

connection-name: el objeto de conexión que especifica el host, el puerto, el base_path y las credenciales de acceso.
http-method: el método de solicitud HTTP que se usa para realizar la llamada. Por ejemplo: GET, POST, PUT, DELETE
path: la ruta a concatenar después de base_path para invocar el recurso de servicio.
json: el cuerpo JSON que se va a enviar con la solicitud.
headers: un mapa para especificar los encabezados de solicitud.

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"
  )
);

Nota:

El acceso a SQL con http_request está bloqueado para el tipo de conexión Usuario a máquina por usuario individual. Use el SDK de Python Databricks en su lugar.

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"},
)

Uso de conexiones HTTP para las herramientas del agente

Los agentes de IA pueden usar la conexión HTTP para acceder a aplicaciones externas como Slack, Google Calendar o cualquier servicio con una API mediante solicitudes HTTP. Los agentes pueden usar herramientas conectadas externamente para automatizar tareas, enviar mensajes y recuperar datos de plataformas de terceros.

Consulte Conexión de herramientas de agente de IA a servicios externos.

Retroalimentació

Ha estat útil aquesta pàgina?

Last updated on 2025-07-16