Conectar-se a serviços HTTP externos

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

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

• 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 do Unity para que você possa usar a sintaxe de consulta do Catálogo do 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 de área de trabalho:

• Espaço de trabalho habilitado para o Unity Catalog.

Requisitos de computação:

• Conectividade de rede do recurso de computação para os sistemas de banco de dados de destino. Confira Recomendações de rede para a Federação de Lakehouse.
• A computação do Azure Databricks deve usar o Databricks Runtime 15.4 LTS ou superior e o modo de acesso Standard ou Dedicado .
• Os sql warehouses 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 CREATE FOREIGN CATALOG na conexão.

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 de portador: obtenha um token de portador 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 de Usuário para Máquina Compartilhado: 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 de Usuário para Máquina por Usuário: autenticação com interação individual de usuário para permitir a comunicação entre a identidade do usuário e a máquina.

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

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

OAuth Machine-to-Machine: A autenticação M2M (OAuth Machine to Machine) é usada quando dois sistemas ou aplicativos se comunicam sem envolvimento direto do usuário. Os tokens são emitidos para um cliente de computador registrado, que usa suas próprias credenciais para autenticação. Isso é ideal para comunicação de servidor para servidor, microsserviços e tarefas de automação em que nenhum contexto de usuário é necessário. A Databricks recomenda usar OAuth Machine-to-Machine quando esta opção estiver disponível sobre OAuth User-to-Machine Shared.

OAuth User-to-Machine Shared: A autenticação OAuth User-to-Machine Shared permite que uma única identidade de usuário autentique e compartilhe o mesmo conjunto de credenciais em vários clientes ou usuários. Todos os usuários compartilham o mesmo token de acesso. Essa abordagem é adequada para dispositivos ou ambientes compartilhados em que uma identidade de usuário consistente é suficiente, mas reduz a responsabilidade e o acompanhamento individuais. Nos casos em que o logon de identidade é necessário, selecione Usuário para Computador Compartilhado. A Databricks recomenda usar OAuth Machine-to-Machine quando esta opção estiver disponível sobre OAuth User-to-Machine Shared.

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 autentique e use suas próprias credenciais para acessar recursos. Cada usuário recebe um token de acesso exclusivo, permitindo controle de acesso individual, auditoria e responsabilidade. Esse método é adequado quando o acesso a dados específicos do usuário é necessário e ao acessar serviços externos em nome do usuário individual.

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

As conexões HTTP que usam o OAuth devem se conectar a serviços que estejam em conformidade com a especificação oficial do OAuth 2.0 para como lidam 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 Catálogo do Unity com o serviço externo que especifica um caminho e credenciais para acessar o serviço.

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

• gerenciamento de credenciais seguras: Segredos e tokens são armazenados e gerenciados com segurança no Catálogo do Unity, garantindo que nunca sejam expostos aos usuários.
• Controle de acesso granular: O Catálogo Unity permite um controle refinado sobre quem pode usar ou gerenciar conexões com os privilégios USE CONNECTION e MANAGE CONNECTION.
• Imposição de token específico 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 que possua o privilégio CREATE CONNECTION.

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

• Use a interface do usuário do Explorador de Catálogos.
• Execute o comando SQL CREATE CONNECTION em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.
• 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 Comandos do Catálogo do Unity.

Gerenciador de Catálogos

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

1. No workspace do Azure Databricks, clique no Catálogo.

2. 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á até a guia Conexões e clique em Criar conexão.

3. Clique em Criar conexão.

4. Insira um nome de conexão simples.

5. Selecione um Tipo de conexão de HTTP.

6. Selecione um tipo de autenticação a partir das seguintes opções:

   • Token do portador
   • OAuth de Máquina para Máquina
   • OAuth de Usuário para Máquina Compartilhado
   • OAuth de Usuário para Máquina por Usuário

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

   Para um token de portador:

   Propriedade	Descrição	Valor do 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 raiz para pontos de extremidade de API.	/api/

   Para o token OAuth Máquina para Máquina:

   Propriedade	Descrição
   ID do cliente	Identificador exclusivo para o aplicativo que você criou.
   Segredo do cliente	Segredo ou senha gerado 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 cadeias de caracteres delimitadas por espaço, 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 sua credencial de autorização ou token de atualização. Normalmente, no formato: https://authorization-server.com/oauth/token

   Para o token OAuth compartilhado de Usuário para Máquina:

   • Você será solicitado a entrar usando suas credenciais do OAuth. As credenciais usadas 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 do cliente	Identificador exclusivo para o aplicativo que você criou.
   Segredo do cliente	Segredo ou senha gerado 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 cadeias de caracteres delimitadas por espaço, 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 por meio do redirecionamento de agente de usuário. Normalmente, no formato: https://authorization-server.com/oauth/authorize
   Endpoint de token	Usado pelo cliente para obter um token de acesso apresentando sua credencial de autorização ou token de atualização. Normalmente, no formato: https://authorization-server.com/oauth/token

   Para o token OAuth de Usuário para Máquina por Usuário:

   • 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 do 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 gerado 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.
   Escopo do OAuth	Escopo a ser concedido durante a autorização do usuário. Expressa como uma lista de strings separadas por espaço, sensíveis a maiúsculas e minúsculas, que definem as permissões solicitadas pelo aplicativo. Por exemplo: channels:read channels:history chat:write
   Endpoint de autorização	Ponto de extremidade usado para autenticar o proprietário do recurso por meio de redirecionamento usuário-agente e obter autorização. Normalmente, no formato: https://authorization-server.com/oauth/authorize O cliente direciona o usuário para esse ponto de extremidade para fazer logon e consentir com permissões.
   Endpoint de token	Ponto de extremidade utilizado pelo cliente para trocar uma concessão de autorização (como um código de autorização) ou um token de atualização por um token 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 credenciais de cliente OAuth durante a troca de tokens. Selecione uma das seguintes opções: header_and_body: coloca credenciais no cabeçalho de 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).

8. Clique em Criar conexão.

SQL

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

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

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

O Databricks recomenda usar segredos em vez de cadeias de caracteres de texto sem formatação para valores confidenciais, 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 o OAuth Machine-to-Machine, execute o seguinte comando em um notebook ou no editor de consultas SQL do 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>'
)

Compartilhar conexão do Unity Catalog

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

1. Em seu ambiente de trabalho, vá para Catálogo>Conexões> suas >.
2. Conceda às identidades acesso apropriado à conexão com o Unity Catalog.

Enviar uma solicitação HTTP para o sistema externo

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

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

Execute o seguinte comando SQL em um notebook ou no editor de SQL do Databricks. Substitua os valores de espaço reservado:

• 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 ser concatenado após 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 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"
  )
);

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 Calendar 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.

Consulte Conectar ferramentas de agente de IA a serviços externos.