Pular para o conteúdo principal

Conectar-se a um serviço HTTP externo

info

Visualização

Esse recurso está em Public Preview.

Este artigo descreve como configurar o Lakehouse Federation para executar consultas federadas em dados de serviços externos que não são gerenciados pelo site 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, o senhor deve criar o seguinte no metastore Databricks 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 preparado para o Catálogo do Unity.

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, é preciso ser administrador de metastore ou usuário com o privilégio CREATE CONNECTION no metastore do Unity Catalog anexado ao espaço de trabalho.
  • Para criar um catálogo externo é preciso ter a permissão CREATE CATALOG no metastore e ser proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG na conexão.

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.

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, em que um token é emitido para um cliente e usado para acessar o recurso sem exigir credenciais adicionais. Os tokens são incluídos no cabeçalho da solicitação e concedem acesso desde que sejam válidos.

OAuth Machine-to-Machine (recomendado): 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 se autenticar. Isso é ideal para comunicação de servidor para servidor, microsserviços e tarefas de automação em que não é necessário nenhum contexto de usuário. A Databricks recomenda o uso do OAuth Machine-to-Machine quando ele estiver disponível.

OAuth compartilhado de usuário para máquina: A autenticação OAuth User-to-Machine Shared permite que uma única identidade de usuário autentique e compartilhe o mesmo conjunto de credenciais entre vários clientes ou usuários. Todos os usuários compartilham os mesmos tokens de acesso. Essa abordagem é adequada para dispositivos ou ambientes compartilhados em que uma identidade de usuário consistente é suficiente, mas reduz a responsabilidade individual e o acompanhamento. Nos casos em que o login de identidade é necessário, selecione Compartilhado de usuário para máquina.

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.

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

  1. Em seu site Databricks workspace, clique em Ícone de catálogo Catalog .

  2. Na parte superior do painel Catálogo , clique no ícone Ícone de adicionar ou ícone de mais Adicionar e selecione Adicionar uma conexão no menu.

    Como alternativa, na página de acesso rápido , clique no botão Dados externos >, acesse a tab Conexões e clique em Criar conexão .

  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

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

    Para tokens ao portador:

    • Anfitrião : Por exemplo, https://databricks.com
    • Porto : Por exemplo, 443
    • Tokens de portador : Por exemplo, bearer-token
    • Caminho base : Por exemplo, /api/

    Para OAuth tokens Machine-to-Machine:

    • 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 do 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:

    • 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 do 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 : Para autenticar com o proprietário do recurso por meio do redirecionamento do agente do usuário, geralmente 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

nota

Para o OAuth User-to-Machine Shared, o usuário é solicitado a fazer login com HTTP usando suas credenciais OAuth.

  1. Clique em Criar conexão .

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

Última atualização em