Conectar-se a um serviço HTTP externo
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égioCREATE 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
eMANAGE_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
- SQL
Use a interface do usuário do Catalog Explorer para criar uma conexão.
-
Em seu site Databricks workspace, clique em
Catalog .
-
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 .
-
Clique em Criar conexão .
-
Insira um nome de conexão fácil de lembrar.
-
Selecione um tipo de conexão HTTP .
-
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
-
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
- Anfitrião : Por exemplo,
Para o OAuth User-to-Machine Shared, o usuário é solicitado a fazer login com HTTP usando suas credenciais OAuth.
- Clique em Criar conexão .
Use o comando CREATE CONNECTION
SQL para criar uma conexão.
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:
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:
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:
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çobase_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.
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"},
)
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.