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.
  • 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, 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.

OAuth User-to-Machine Per User: OAuth A autenticação User-to-Machine Per User permite que cada identidade de usuário se autentique e use suas próprias credenciais para acessar o recurso. Cada usuário recebe um token de acesso exclusivo, o que permite o controle de acesso individual, a auditoria e a responsabilidade. Esse método é adequado quando é necessário o acesso a dados específicos do usuário e ao acessar serviços externos em nome do usuário individual.

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 no ícone 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
   • OAuth Usuário para máquina por usuário

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.[1][5][6]
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

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

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.