Conectar-se a serviços HTTP externos

Importante

Este recurso está no Public Preview.

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

Para se conectar ao seu banco de dados de serviço externo usando a Lakehouse Federation, você deve criar o seguinte no metastore do Azure Databricks Unity Catalog:

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

Antes de começar

Requisitos do espaço de trabalho:

Espaço de trabalho habilitado para o Unity Catalog.

Requisitos de computação:

Conectividade de rede do seu recurso de computação para os sistemas de banco de dados de destino. Consulte as recomendações de rede para a Lakehouse Federation.
Os recursos computacionais do Azure Databricks devem utilizar o Databricks Runtime 15.4 LTS ou superior e o modo de acesso Standard ou Dedicado.
Os armazéns SQL devem ser profissionais ou sem servidor e devem usar 2023.40 ou superior.

Permissões necessárias:

Para criar uma conexão, você deve ser um administrador de metastore ou um usuário com o privilégio de CREATE CONNECTION no metastore do Unity Catalog anexado ao espaço de trabalho.
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 de CREATE FOREIGN CATALOG na conexão.

Os requisitos de permissão adicionais são especificados em cada seção baseada em tarefas a seguir.

Configure a autenticação para o serviço externo usando um dos seguintes métodos:
- Token Bearer: Obtenha um token Bearer para autenticação simples baseada em token.
- OAuth 2.0 Machine-to-Machine: crie e configure um aplicativo para habilitar a autenticação máquina-a-máquina.
- OAuth 2.0 User-to-Machine Shared: Autentique-se através da interação com o utilizador para partilhar 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 utilizador para acessar a conexão entre a identidade do utilizador e a máquina.

Métodos de autenticação para serviços externos

Token de acesso: Um token de acesso é um mecanismo de autenticação simples baseado em token, no qual um token é emitido para um cliente e utilizado para aceder a recursos sem necessitar de credenciais adicionais. O token é incluído no cabeçalho da solicitação e concede acesso desde que seja válido.

OAuth Máquina-a-Máquina: A autenticação OAuth Machine-to-Machine (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 autenticar. Isso é ideal para comunicação entre servidores, microsserviços e tarefas de automação em que nenhum contexto de usuário é necessário. A Databricks recomenda utilizar OAuth Machine-to-Machine sempre que estiver disponível, em vez de OAuth User-to-Machine Shared.

OAuth Utilizador-para-Máquina Partilhado: A autenticação partilhada Utilizador-para-Máquina do OAuth permite que uma única identidade de utilizador autentique e partilhe o mesmo conjunto de credenciais entre vários clientes ou utilizadores. Todos os usuários compartilham o mesmo token de acesso. Essa abordagem é adequada para dispositivos ou ambientes compartilhados onde uma identidade de usuário consistente é suficiente, mas reduz a responsabilidade individual e o rastreamento. Nos casos em que o login de identidade é necessário, selecione User-to-Machine Shared. A Databricks recomenda utilizar OAuth Machine-to-Machine sempre que estiver disponível, em vez de OAuth User-to-Machine Shared.

OAuth User-to-Machine Per User: A autenticação OAuth User-to-Machine Per User permite que cada identidade de usuário se autentique e utilize suas próprias credenciais para aceder a recursos. Cada usuário recebe um token de acesso exclusivo, permitindo o controle de acesso individual, auditoria e prestação de contas. Este método é adequado quando é necessário o acesso a dados específicos do utilizador e quando se acede a serviços externos em nome do utilizador individual.

Os serviços externos devem estar em conformidade com as especificações OAuth 2.0

As conexões HTTP que usam OAuth devem se conectar a serviços que estejam em conformidade com a especificação oficial do OAuth 2.0 para como eles manipulam e retornam dados de token de acesso. Isso significa que as respostas do serviço devem usar os nomes de campo exatos e os formatos de dados descritos na especificação, como access_token, expires_ine assim por diante.

Se você 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 credenciais para acessar o serviço.

Os benefícios de usar uma conexão do Catálogo Unity incluem o seguinte:

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

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

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

Utilize a interface do utilizador do Catalog Explorer.
Execute o comando CREATE CONNECTION SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL.
Use a API REST do Databricks ou a CLI do Databricks para criar uma conexão. Consulte POST /api/2.1/unity-catalog/connections e os comandos do Unity Catalog .

Explorador de Catálogos

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

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo, clique no ícone Adicionar e selecione Adicionar uma conexão no menu.

Como alternativa, na página Acesso rápido , clique no botão Dados externos > , vá para a guia Conexões e clique em Criar conexão.
Clique em Criar conexão.
Introduza um nome de ligação de fácil utilização.
Selecione um tipo de conexão de HTTP.
Selecione um tipo de autenticação entre as seguintes opções:
- Token de portador
- OAuth Máquina para Máquina
- OAuth compartilhado de usuário para máquina
- OAuth Utilizador para Máquina por Utilizador

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

Para um token do portador:

Propriedade	Descrição	Valor de Exemplo
Anfitrião	A URL base do seu espaço de trabalho ou implantação do Databricks.	`https://databricks.com`
Porto	A porta de rede usada para a conexão, normalmente `443` para HTTPS.	`443`
Token de Portador	O token de autenticação usado para autorizar solicitações de API.	`bearer-token`
Caminho base	O caminho base para os endpoints da API.	`/api/`

Para o token OAuth Máquina-a-Máquina:

Propriedade	Descrição
ID de Cliente	Identificador exclusivo para o aplicativo que você criou.
Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou.
Âmbito OAuth	Escopo a ser concedido durante a autorização do usuário. O parâmetro scope é expresso como uma lista de strings delimitadas por espaços, sensíveis a maiúsculas e minúsculas. Por exemplo: `channels:read channels:history chat:write`
Endpoint de token	Usado pelo cliente para obter um token de acesso apresentando o seu código de autorização ou token de atualização. Geralmente no formato: `https://authorization-server.com/oauth/token`

Para token compartilhado de usuário para máquina OAuth:

Você será solicitado a entrar 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 a URL de redirecionamento, inclua <databricks_workspace_url>/login/oauth/http.html como a lista de permissões de URL de redirecionamento. Exemplo: https://databricks.com/login/oauth/http.html

Propriedade	Descrição
ID de Cliente	Identificador exclusivo para o aplicativo que você criou.
Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou.
Âmbito OAuth	Escopo a ser concedido durante a autorização do usuário. O parâmetro scope é expresso como uma lista de strings delimitadas por espaços, sensíveis a maiúsculas e minúsculas. Por exemplo: `channels:read channels:history chat:write`
Endpoint de autorização	Usado para autenticar com o proprietário do recurso através do redirecionamento do agente de utilizador. Geralmente no formato: `https://authorization-server.com/oauth/authorize`
Endpoint de token	Usado pelo cliente para obter um token de acesso apresentando o seu código de autorização ou token de atualização. Geralmente no formato: `https://authorization-server.com/oauth/token`

Para o token OAuth User-to-Machine Per User:

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

Propriedade	Descrição
ID de Cliente	Identificador exclusivo para o aplicativo que você criou. Usado pelo servidor de autorização para identificar o aplicativo cliente durante o fluxo OAuth.
Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou. Ele é usado para autenticar o aplicativo cliente ao trocar códigos de autorização por tokens e deve ser mantido confidencial.
Âmbito OAuth	Escopo a ser concedido durante a autorização do usuário. Expresso como uma lista de cadeias de caracteres delimitadas por espaços e sensíveis a maiúsculas e minúsculas, que definem as permissões que a aplicação solicita. Por exemplo: `channels:read channels:history chat:write`
Endpoint de autorização	Endpoint utilizado para autenticar o proprietário do recurso através do redirecionamento do user agent e obter autorização. Geralmente no formato: `https://authorization-server.com/oauth/authorize` O cliente direciona o utilizador para este ponto de acesso para fazer login e consentir as permissões.
Endpoint de token	Ponto de extremidade usado pelo cliente para trocar uma concessão de autorização (como um código de autorização) ou atualizar token por um token de acesso. Geralmente no formato: `https://authorization-server.com/oauth/token`
Método de troca de credenciais Oauth	Os provedores exigem métodos diferentes para passar credenciais de cliente OAuth durante a troca de tokens. Selecione uma das seguintes opções: header_and_body: Coloca credenciais no cabeçalho da autorização e no corpo da solicitação (padrão). body_only: Coloca credenciais somente no corpo da solicitação sem um cabeçalho de autorização. header_only: Coloca credenciais somente no cabeçalho de autorização (para provedores como OKTA).

Clique em Criar conexão.

SQL

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

Observação

Não é possível usar o comando SQL para criar uma conexão que usa 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 um token Bearer, execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL:

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

Databricks recomenda usar segredos em vez de strings em texto claro para valores sensíveis como credenciais. Por exemplo:

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 bloco de anotações ou no editor de consultas 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>'
)

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

No espaço de trabalho, vá para Catálogo>Conexões> Sua >Permissões.
Conceda às identidades acesso apropriado à conexão do Catálogo Unity.

Enviar uma solicitação HTTP para o sistema externo

Agora que tem uma conexão, aprenda a enviar solicitações HTTP para o serviço usando a função interna de SQL http_request.

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

Execute o seguinte comando SQL em um bloco de anotações ou no editor SQL do Databricks. Substitua os valores dos espaços reservados:

connection-name: O objeto de conexão que especifica as credenciais de host, porta, base_path e 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 concatenar após o base_path para invocar o recurso do serviço.
json: O corpo JSON a ser enviado com a requisição.
headers: Um mapa para especificar os cabeçalhos de solicitação.

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

Observação

O acesso 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.

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

Usar conexões HTTP para ferramentas de agente

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

Veja Conexão de ferramentas do agente de IA a serviços externos.

Feedback

Esta página foi útil?

Last updated on 2025-07-04