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 do Databricks Unity Catalog (os espaços de trabalho criados após 8 de novembro de 2023 já possuem um provisionamento automático do 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 8 de novembro de 2023 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.

   Para tokens ao portador:

Propriedade	Descrição	Valor de exemplo
Host	O URL de base de seu Databricks workspace ou implantação.	https://databricks.com
Porta	A porta de rede usada para a conexão, normalmente 443 para HTTPS.	443
Tokens de portador	Os tokens de autenticação usados para autorizar as solicitações do API.	bearer-token
Caminho base	O caminho raiz para o ponto de extremidade API.	/api/

Para OAuth tokens Machine-to-Machine:

Propriedade	Descrição
ID do cliente	Identificador exclusivo para o aplicativo que você criou.
Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou.
Escopo OAuth	Escopo a ser concedido durante a autorização do usuário. O parâmetro de escopo é expresso como uma lista de espaços delimitados, com distinção entre maiúsculas e minúsculas strings. Por exemplo: channels:read channels:history chat:write
tokens endpoint	Usado pelo cliente para obter tokens de acesso apresentando sua concessão de autorização ou tokens refresh. Normalmente no formato: https://authorization-server.com/oauth/token

Para OAuth tokens compartilhados 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

Propriedade	Descrição
ID do cliente	Identificador exclusivo para o aplicativo que você criou.
Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou.
Escopo OAuth	Escopo a ser concedido durante a autorização do usuário. O parâmetro de escopo é expresso como uma lista de espaços delimitados, com distinção entre maiúsculas e minúsculas strings. Por exemplo: channels:read channels:history chat:write
Autorização endpoint	Usado para autenticar com o proprietário do recurso por meio do redirecionamento do agente do usuário. Normalmente no formato: https://authorization-server.com/oauth/authorize
tokens endpoint	Usado pelo cliente para obter tokens de acesso apresentando sua concessão de autorização ou tokens refresh. Normalmente no formato: https://authorization-server.com/oauth/token

Para OAuth tokens 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

Propriedade	Descrição
ID do cliente	Identificador exclusivo para o aplicativo que você criou. Usado pelo servidor de autorização para identificar o aplicativo cliente durante o fluxo do 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 em sigilo.
Escopo OAuth	Escopo a ser concedido durante a autorização do usuário. Expressa como uma lista de strings, delimitada por espaço e sensível a maiúsculas e minúsculas, que define as permissões solicitadas pelo aplicativo. Por exemplo: channels:read channels:history chat:write
Autorização endpoint	usado para autenticar o proprietário do recurso por meio do redirecionamento do agente do usuário e obter autorização. Geralmente no formato: https://authorization-server.com/oauth/authorize O cliente direciona o usuário para este endpoint para log in e consente com as permissões.
tokens endpoint	Ponto de extremidade usado pelo cliente para trocar uma concessão de autorização (como um código de autorização) ou tokens refresh por tokens de acesso. Normalmente no formato: https://authorization-server.com/oauth/token
Método de troca de credenciais Oauth	Os provedores exigem métodos diferentes para passar as credenciais do cliente OAuth durante a troca de tokens. Selecione uma das seguintes opções: header_and_body : Coloca as credenciais no cabeçalho de autorização e no corpo da solicitação (default). body_only : coloca as credenciais somente no corpo da solicitação sem um cabeçalho de autorização. header_only : coloca as credenciais somente no cabeçalho de autorização (para provedores como 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 .

Enviar uma solicitação HTTP para o sistema externo

Agora que o senhor tem uma conexão, aprenda a enviar 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 as ferramentas do agente AI ao serviço externo.