Conectar-se a um serviço HTTP externo

info

Visualização

Esse recurso está em Public Preview.

Esta página descreve como configurar o Lakehouse Federation para executar consultas federadas em dados de serviços externos que não são gerenciados por Databricks. Para saber mais sobre a lakehouse Federation, consulte O que é a lakehouse Federation?

Para conectar-se ao seu banco de dados de serviço externo usando o Lakehouse Federation, você deve criar o seguinte no seu metastore Databricks Unity Catalog (os espaços de trabalho criados após 6 de março de 2024 já possuem um provisionamento automático de metastore Unity Catalog ):

• Uma conexão com o banco de dados do serviço externo.
• Um catálogo externo que espelha seu banco de dados de serviço externo no Unity Catalog para que o senhor possa usar a sintaxe de consulta do Unity Catalog e as ferramentas de governança de dados para gerenciar o acesso do usuário do Databricks ao banco de dados.

Antes de começar

Requisitos do workspace:

• Espaço de trabalho habilitado para Unity Catalog. Os espaços de trabalho criados após 6 de março de 2024 são habilitados automaticamente para o Unity Catalog , incluindo o provisionamento automático do metastore. Você não precisa criar um metastore manualmente, a menos que seu workspace seja anterior à ativação automática e não tenha sido habilitado para Unity Catalog. Consulte Ativação automática do Unity Catalog.

Requisitos de computação:

• Conectividade de rede do seu recurso compute para os sistemas de banco de dados de destino. Veja as recomendações do Networking para a Lakehouse Federation.
• Databricks compute O senhor deve usar Databricks Runtime 15.4 LTS ou acima e o modo de acesso Standard ou Dedicated .
• Os SQL warehouse devem ser Pro ou Serverless e devem utilizar a versão 2023.40 ou superior.

Permissões necessárias:

• Para criar uma conexão, você deve ser um administrador do metastore ou um usuário com o privilégio CREATE CONNECTION no metastore Unity Catalog anexado ao workspace. Em espaços de trabalho que foram habilitados para o Unity Catalog automaticamente, os administradores workspace têm o privilégio CREATE CONNECTION por default.
• Para criar um catálogo estrangeiro, você deve ter a permissão CREATE CATALOG no metastore e ser o proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG na conexão. Em espaços de trabalho que foram habilitados para o Unity Catalog automaticamente, os administradores workspace têm o privilégio CREATE CATALOG por default.

Outros requisitos de permissão são definidos em cada seção baseada em tarefa a seguir.

• Configure a autenticação para o serviço externo usando um dos seguintes métodos:
  • Tokens de portador : Obter tokens de portador para autenticação simples baseada em tokens.
  • OAuth 2.0 Máquina a máquina : Crie e configure um aplicativo para habilitar a autenticação máquina a máquina.
  • OAuth 2.0 Compartilhado de usuário para máquina : Autenticação com interação do usuário para compartilhar o acesso entre a identidade do serviço e a máquina.
  • OAuth 2.0 User-to-Machine Per User : autenticação com interação por usuário para acesso entre a identidade do usuário e a máquina.

Métodos de autenticação para serviço externo

Tokens de portador

Um token de portador é um mecanismo de autenticação simples baseado em tokens, onde um token é emitido para um cliente e usado para acessar um recurso sem a necessidade de credenciais adicionais. O token é incluído no cabeçalho da solicitação e concede acesso enquanto for válido.

OAuth Máquina a Máquina

A autenticação OAuth de máquina para máquina (M2M) é usada quando dois sistemas ou aplicativos se comunicam sem o envolvimento direto do usuário. Os tokens são emitidos para um cliente de máquina registrado, que usa suas próprias credenciais para autenticação. Isso é ideal para comunicação servidor-servidor, microsserviços e tarefas de automação onde não é necessário contexto do usuário. A Databricks recomenda o uso do OAuth Máquina a Máquina quando disponível, em vez do OAuth Usuário a Máquina Compartilhado.

Compartilhamento de usuário para máquina via OAuth

A autenticação compartilhada OAuth de usuário para máquina permite que uma única identidade de usuário se autentique e compartilhe o mesmo conjunto de credenciais entre vários clientes ou usuários. Todos os usuários compartilham o mesmo access token. Essa abordagem é adequada para dispositivos ou ambientes compartilhados onde uma identidade de usuário consistente é suficiente, mas reduz a responsabilidade individual e o acompanhamento. Nos casos em que for necessário fazer login com um autenticador, selecione Compartilhamento de Usuário para Máquina. A Databricks recomenda o uso do OAuth Máquina a Máquina quando disponível, em vez do OAuth Usuário a Máquina Compartilhado.

OAuth de usuário para máquina por usuário

A autenticação OAuth de usuário para máquina por usuário permite que cada identidade de usuário se autentique e use suas próprias credenciais para acessar o recurso. A cada usuário é emitido um access token exclusivo, permitindo o controle de acesso individual, auditoria e responsabilização. Este método é adequado quando é necessário o acesso a dados específicos do usuário e quando se acessa um serviço externo em nome do usuário individual.

O serviço externo deve estar em conformidade com as especificações do OAuth 2.0

As conexões HTTP que usam OAuth devem se conectar a um serviço que esteja em conformidade com a OAuth especificação oficial 2.0 sobre como manipular e retornar dados de tokens de acesso. Isso significa que as respostas do serviço devem usar os nomes exatos dos campos e os formatos de dados descritos na especificação, como access_token, expires_in, e assim por diante.

Se o senhor tiver problemas para se conectar a um serviço externo usando o OAuth 2.0, verifique se as respostas do serviço seguem esses requisitos.

Criar uma conexão com o serviço externo

Primeiro, crie uma conexão do Unity Catalog com o serviço externo que especifique um caminho e as credenciais para acessar o serviço.

Os benefícios de usar uma conexão do Unity Catalog incluem o seguinte:

• Gerenciamento seguro de credenciais: Segredos e tokens são armazenados com segurança e gerenciados em Unity Catalog, garantindo que nunca sejam expostos aos usuários.
• Controle de acesso granular: O Unity Catalog permite um controle refinado sobre quem pode usar ou gerenciar conexões com os privilégios USE CONNECTION e MANAGE CONNECTION.
• Aplicação de tokens específicos do host: os tokens são restritos ao host_name especificado durante a criação da conexão, garantindo que não possam ser usados com hosts não autorizados.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE CONNECTION.

Crie uma conexão usando um dos seguintes métodos:

• Use a interface do usuário do Catalog Explorer.
• Execute o comando CREATE CONNECTION SQL em um Databricks Notebook ou no editor de consultas Databricks SQL.
• Use a API REST da Databricks ou a CLI da Databricks para criar uma conexão. Veja POST /api/2.1/unity-catalog/connections e Unity Catalog comando.

Catalog Explorer

Use a interface do usuário do Catalog Explorer para criar uma conexão.

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique em Adicione o ícone e selecione "Criar uma conexão" no menu.

3. Clique em Criar conexão .

4. Insira um nome de conexão fácil de lembrar.

5. Selecione um tipo de conexão HTTP .

6. Selecione um tipo de autenticação entre as seguintes opções:

   • Tokens de portador
   • OAuth máquina a máquina
   • Usuário OAuth para máquina compartilhada
   • OAuth Usuário para máquina por usuário
     • Selecione Configuração Manual para inserir suas próprias credenciais OAuth. Se você estiver se conectando a um servidor MCP externo e quiser que Databricks gerencie as credenciais OAuth para você, consulte Gerenciar fluxos OAuth.

7. Na página Autenticação , insira as seguintes propriedades de conexão para a conexão HTTP.

Propriedades dos tokens de portador

Para tokens ao portador:

Property	Description	Example value
Host	The base URL of your Databricks workspace or deployment.	https://databricks.com
Port	The network port used for the connection, typically 443 for HTTPS.	443
Bearer Token	The authentication token used to authorize API requests.	bearer-token
Base Path	The root path for API endpoints.	/api/

Propriedades de comunicação máquina a máquina OAuth

Para OAuth de máquina para máquina:

Property	Description
Client ID	Unique identifier for the application you created.
Client secret	Secret or password generated for the application that you created.
OAuth scope	Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example: channels:read channels:history chat:write
Token endpoint	Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format: https://authorization-server.com/oauth/token

Propriedades compartilhadas entre usuário e máquina via OAuth

Para compartilhamento OAuth de usuário para máquina:

• Será solicitado que o senhor faça login usando suas credenciais OAuth. As credenciais que você usa serão compartilhadas por qualquer pessoa que use essa conexão. Alguns provedores exigem uma lista de permissões para o URL de redirecionamento. Inclua <databricks_workspace_url>/login/oauth/http.html como a lista de permissões do URL de redirecionamento. Exemplo: https://databricks.com/login/oauth/http.html

Property	Description
Client ID	Unique identifier for the application you created.
Client secret	Secret or password generated for the application that you created.
OAuth scope	Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example: channels:read channels:history chat:write
Authorization endpoint	Used to authenticate with the resource owner via user-agent redirection. Usually in the format: https://authorization-server.com/oauth/authorize
Token endpoint	Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format: https://authorization-server.com/oauth/token

Propriedades de usuário para máquina do OAuth por usuário

Para autenticação OAuth de usuário para máquina por usuário:

• Cada usuário será solicitado a fazer login usando suas credenciais OAuth individuais na primeira vez que usar a conexão HTTP. Alguns provedores exigem uma lista de permissões para o URL de redirecionamento. Inclua <databricks_workspace_url>/login/oauth/http.html como a lista de permissões do URL de redirecionamento. Exemplo: https://databricks.com/login/oauth/http.html

Property	Description
Client ID	Unique identifier for the application you created. Used by the authorization server to identify the client application during the OAuth flow.
Client secret	Secret or password generated for the application that you created. It is used to authenticate the client application when exchanging authorization codes for tokens and must be kept confidential.
OAuth scope	Scope to grant during user authorization. Expressed as a list of space-delimited, case-sensitive strings defining the permissions the application requests. For example: channels:read channels:history chat:write
Authorization endpoint	Endpoint used to authenticate the resource owner via user-agent redirection and obtain authorization. Usually in the format: https://authorization-server.com/oauth/authorize The client directs the user to this endpoint to log in and consent to permissions.
Token endpoint	Endpoint used by the client to exchange an authorization grant (such as an authorization code) or refresh token for an access token. Usually in the format: https://authorization-server.com/oauth/token
Oauth credential exchange method	Providers require different methods for passing OAuth client credentials during token exchange. Select one of the following options: header_and_body: Places credentials in both the authorization header and request body (default). body_only: Places credentials only in the request body without an authorization header. header_only: Places credentials only in the authorization header (for providers like OKTA).

8. Clique em Criar conexão .

SQL

Use o comando CREATE CONNECTION SQL para criar uma conexão.

nota

O senhor não pode usar o comando SQL para criar uma conexão que use o OAuth Machine-to-User Shared . Em vez disso, consulte as instruções da interface do usuário do Catalog Explorer.

Para criar uma nova conexão usando tokens de portador , execute o seguinte comando em um notebook ou no editor de consultas Databricks SQL:

SQL

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

Databricks recomenda o uso de segredos em vez de texto simples strings para valores confidenciais, como credenciais. Por exemplo:

SQL

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

Para criar uma nova conexão usando OAuth Machine-to-Machine , execute o seguinte comando em um Notebook ou no editor de consultas Databricks SQL:

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

Compartilhar conexão Unity Catalog

Conceda privilégios USE CONNECTION às entidades de identidade que precisam usar a conexão:

1. Em seu workspace, acesse Catálogo > Conexões > Sua conexão > Permissões .
2. Conceda às identidades o acesso apropriado à conexão com o Unity Catalog .

Encaminhar solicitações através do proxy de conexão HTTP

Para enviar uma solicitação a um serviço externo, a Databricks recomenda o uso do proxy de conexão HTTP.

O proxy de conexão HTTP Unity Catalog é um endpoint HTTP hospedado Databricksque encaminha solicitações para serviços externos em seu nome. Em vez de gerenciar tokens de autenticação em seu aplicativo, você se autentica com o Databricks e permite que o Databricks injete automaticamente as credenciais do serviço externo da conexão do Unity Catalog.

Isso é mais útil quando:

• Você precisa chamar uma API REST externa ou um servidor MCP a partir de um aplicativo executado fora do Databricks, sem armazenar credenciais diretamente no seu aplicativo.
• Você deseja que Databricks lide com o armazenamento de credenciais, refresh de tokens OAuth e os fluxos de autenticação por usuário para serviços externos.
• Você está conectando um cliente MCP (como o Claude Desktop ou o Cursor) a um servidor MCP externo por meio de um proxy Databricks-gerenciar. Consulte Usar servidores MCP externos.

Permissões necessárias: USE CONNECTION no objeto de conexão.

URL endpoint do proxy

A URL do endpoint do proxy segue este formato:

https://<workspace-hostname>/api/2.0/unity-catalog/connections/<connection-name>/proxy[/<sub-path>]

Parâmetro	Descrição
<connection-name>	O nome da conexão HTTP Unity Catalog .
<sub-path>	Opcional. Um segmento de caminho adicionado após o base_path da conexão ao construir a URL de saída. Evite chamar diretamente a URL base da conexão.

Como o proxy constrói a solicitação de saída

O proxy combina o host da conexão e base_path com o subcaminho da solicitação para construir a URL enviada ao serviço externo:

{connection host}{base_path}{sub-path}

Por exemplo, se sua conexão estiver configurada com o host https://api.example.com e o caminho base /v1, uma solicitação para:

POST /api/2.0/unity-catalog/connections/my_connection/proxy/messages

É encaminhado para:

POST https://api.example.com/v1/messages

Encaminhamento de cabeçalho

O proxy encaminha os cabeçalhos da sua solicitação para o serviço externo seguindo as seguintes regras:

• Cabeçalhos bloqueados : Os cabeçalhos internos Databricks (como Authorization, Cookie, X-Databricks-* e cabeçalhos de sessão semelhantes) são removidos antes do encaminhamento para evitar o vazamento de credenciais Databricks para serviços externos.
• Todos os outros cabeçalhos fornecidos serão encaminhados sem alterações para o serviço externo. Use isso para passar cabeçalhos específicos do serviço, como Content-Type ou chave API personalizada exigida pelo serviço externo.

Corpo da solicitação

O corpo da solicitação é encaminhado ao serviço externo tal como está, sem modificações.

Métodos HTTP suportados

GET, POST, PUT, PATCH, DELETE

Autenticação

Você se autentica com o endpoint do proxy usando a autenticação padrão Databricks ( access token pessoal ou OAuth). Em seguida, o Databricks recupera as credenciais do serviço externo armazenadas na conexão do Unity Catalog e as insere na solicitação de saída. Todos os tipos de autenticação de conexão (tokens Bearer, OAuth M2M, OAuth U2M Compartilhado, OAuth U2M por Usuário) são suportados. Consulte Métodos de autenticação para serviços externos.

Exemplo

O exemplo a seguir envia uma solicitação POST através do proxy para um endpoint da API do Slack. Os tokens de portador do Slack são armazenados na conexão Unity Catalog slack_connection e nunca são incluídos na solicitação do cliente.

Bash

curl -X POST \
  "https://<workspace-hostname>/api/2.0/unity-catalog/connections/slack_connection/proxy/chat.postMessage" \
  -H "Authorization: Bearer <databricks-token>" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C123456", "text": "Hello from Databricks!"}'

Se slack_connection estiver configurado com o host https://slack.com e o caminho base /api, esta solicitação será encaminhada para https://slack.com/api/chat.postMessage com as credenciais do Slack injetadas automaticamente pelo Databricks.

Enviar uma solicitação HTTP usando http_request

atenção

http_request Está obsoleto. Use o endpointproxy de conexõesUnity Catalog com o SDK do provedor para o novo código.

Envie solicitações HTTP para o serviço usando a função SQL integrada http_request .

Permissões necessárias: USE CONNECTION no objeto de conexão.

Execute o seguinte comando SQL em um notebook ou no editor Databricks SQL. Substitua os valores temporários:

• connection-name: o objeto de conexão que especifica o host, a porta, o base_path e as credenciais de acesso.
• http-method: o método de solicitação HTTP usado para fazer a chamada. Por exemplo: GET, POST, PUT, DELETE
• path: O caminho a ser concatenado após o endereço base_path para invocar o recurso de serviço.
• json: O corpo JSON a ser enviado com a solicitação.
• headers: Um mapa para especificar os cabeçalhos da solicitação.

SQL

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

O acesso ao SQL com http_request está bloqueado para o tipo de conexão User-to-Machine Per User. Em vez disso, use o SDK do Python Databricks.

Python

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

Use conexões HTTP para ferramentas de agente

AI Os agentes podem usar a conexão HTTP para acessar aplicativos externos como Slack, Google Calendar ou qualquer serviço com um API usando solicitações HTTP. Os agentes podem usar ferramentas conectadas externamente para automatizar a tarefa, enviar mensagens e recuperar dados de plataformas de terceiros.

Consulte Conectar agentes a serviços externos.

Limitações

• A conectividade privada com o recurso em sua VPC usando o serviço privado Connect não é compatível com conexões HTTP. Entre em contato com sua equipe de suporte se precisar dessa funcionalidade.