Conectar-se a serviços HTTP externos

Uma ligação HTTP é um objeto seguro pelo Unity Catalog que armazena informações de endpoint e credenciais para um serviço HTTP externo. Use uma ligação HTTP para enviar pedidos autenticados para APIs REST externas, servidores MCP e ferramentas de agentes de IA a partir do Azure Databricks sem incorporar credenciais no seu código.

Antes de começar

Requisitos do espaço de trabalho:

• Espaço de trabalho habilitado para o Unity Catalog. Os espaços de trabalho criados após 9 de novembro de 2023 são ativados automaticamente para o Unity Catalog, incluindo o provisionamento automático de metastores. Não precisas de criar uma metastore manualmente a menos que o teu espaço de trabalho seja anterior à ativação automática e não tenha sido ativado para o Unity Catalog. Consulte Ativação automática do Unity Catalog.

Requisitos de computação:

• Azure Databricks cálculo deve usar Databricks Runtime 15.4 LTS ou superior e o modo de acesso Standard ou Dedicado.
• Os armazéns SQL 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. Nos espaços de trabalho que estavam ativados automaticamente para o Unity Catalog, os administradores de espaços de trabalho têm esse CREATE CONNECTION privilégio por defeito.

Os 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 Bearer: Obtenha um token Bearer para autenticação simples baseada em token.
  • Registo Dinâmico de Clientes (DCR): Descobre e regista automaticamente credenciais OAuth usando o protocolo RFC 7591 . Cada utilizador autentica-se individualmente.
  • OAuth 2.0 Machine-to-Machine: crie e configure um aplicativo para habilitar a autenticação máquina-a-máquina.
  • OAuth 2.0 User-to-Machine Shared: Autentique-se através da interação com o utilizador para partilhar 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 utilizador para acessar a conexão entre a identidade do utilizador e a máquina.

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

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

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

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

• Gerenciamento seguro de credenciais: segredos e tokens são armazenados e gerenciados com segurança no Unity Catalog, garantindo que nunca sejam expostos aos usuários.
• Controle de acesso granular: Unity Catalog permite um controle refinado sobre quem pode usar ou gerenciar conexões com os privilégios de USE CONNECTION e MANAGE CONNECTION.
• Aplicação de token específico do host: Tokens são restritos aos hosts host_name indicados durante a criação da ligação, garantindo que não possam ser utilizados com hosts não autorizados.

Permissões necessárias: administrador do Metastore ou usuário com o CREATE CONNECTION privilégio.

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

• Utilize a interface do utilizador do Catalog Explorer.
• Execute o comando SQL CREATE CONNECTION num Azure Databricks notebook 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 os comandos do Unity Catalog .

Explorador de Catálogos

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

1. No seu espaço de trabalho Azure Databricks, clique em Catalog.

2. Na parte superior do painel Catálogo, clique no ícone Adicionar e selecione Criar uma conexão no menu.

3. Clique em Criar conexão.

4. Introduza um nome de ligação de fácil utilização.

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

6. Selecione um tipo de autenticação entre as seguintes opções:

   • Token de portador
   • Registo Dinâmico de Clientes
   • OAuth Máquina para Máquina
   • OAuth compartilhado de usuário para máquina
   • OAuth Utilizador para Máquina por Utilizador
     • Escolha Configuração Manual para inserir as suas próprias credenciais OAuth. Se estiver a ligar-se a um servidor MCP externo e quiser que o Databricks gere as credenciais OAuth por si, veja Managed OAuth Flows.

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

   Propriedades do token portador

   Para um token do portador:

   Propriedade	Descrição	Valor de 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 base para os endpoints da API.	/api/

   Propriedades de Registo Dinâmico de Clientes

   Para Registo Dinâmico de Clientes:

   Propriedade	Descrição
   Anfitrião	O URL HTTPS do serviço externo. O Databricks utiliza esta URL para descobrir o servidor de autorização OAuth e registar automaticamente um cliente.
   Porto	A porta de rede usada para a conexão, normalmente 443 para HTTPS.
   Caminho base	O caminho base para os endpoints da API.
   Âmbito OAuth	(Opcional) Permissões para conceder durante a autorização do utilizador. Expressar como uma lista de strings separadas por espaços, com distinção entre maiúsculas e minúsculas. Se for omitido, o servidor determina os escopos padrão.

   Propriedades OAuth Máquina-a-Máquina

   Para OAuth Máquina-a-Máquina:

   Propriedade	Descrição
   ID de Cliente	Identificador exclusivo para o aplicativo que você criou.
   Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou.
   Âmbito OAuth	Escopo a ser concedido durante a autorização do usuário. O parâmetro scope é expresso como uma lista de strings delimitadas por espaços, 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 o seu código de autorização ou token de atualização. Geralmente no formato: https://authorization-server.com/oauth/token

   Propriedades partilhadas de Utilizador-para-Sistema do OAuth

   Para OAuth utilizador-para-máquina partilhado:

   • Você será solicitado a entrar 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 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 de Cliente	Identificador exclusivo para o aplicativo que você criou.
   Segredo do cliente	Segredo ou senha gerada para o aplicativo que você criou.
   Âmbito OAuth	Escopo a ser concedido durante a autorização do usuário. O parâmetro scope é expresso como uma lista de strings delimitadas por espaços, 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 através do redirecionamento do agente de utilizador. Geralmente no formato: https://authorization-server.com/oauth/authorize
   Endpoint de token	Usado pelo cliente para obter um token de acesso apresentando o seu código de autorização ou token de atualização. Geralmente no formato: https://authorization-server.com/oauth/token

   Propriedades de OAuth de Utilizador-para-Máquina por Utilizador

   Para OAuth utilizador-para-máquina por utilizador:

   • 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 de 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 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 confidencial.
   Âmbito OAuth	Escopo a ser concedido durante a autorização do usuário. Expresso como uma lista de cadeias de caracteres delimitadas por espaços e sensíveis a maiúsculas e minúsculas, que definem as permissões que a aplicação solicita. Por exemplo: channels:read channels:history chat:write
   Endpoint de autorização	Endpoint utilizado para autenticar o proprietário do recurso através do redirecionamento do user agent e obter autorização. Geralmente no formato: https://authorization-server.com/oauth/authorize O cliente direciona o utilizador para este ponto de acesso para fazer login e consentir as permissões.
   Endpoint de token	Ponto de extremidade usado pelo cliente para trocar uma concessão de autorização (como um código de autorização) ou atualizar token por um token de acesso. Geralmente 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 da 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 CREATE CONNECTION SQL para criar uma conexão.

Para criar uma nova conexão usando um token Bearer, execute o seguinte comando em um bloco de anotações 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 usar segredos em vez de strings em texto claro para valores sensíveis 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 bloco de anotações 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>'
)

Compartilhar conexão do Catálogo Unity

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

1. No espaço de trabalho, vá para Catálogo>Conexões> Sua >Permissões.
2. Conceda às identidades acesso apropriado à conexão do Catálogo Unity.

Encaminhar pedidos através do proxy de ligação HTTP

Para enviar um pedido a um serviço externo, o Databricks recomenda o uso do proxy de ligação HTTP.

O proxy de ligação HTTP do Unity Catalog é um endpoint HTTP alojado no Databricks que encaminha pedidos para serviços externos em seu nome. Em vez de gerir tokens de autenticação na sua aplicação, autentica com Databricks e permite que o Databricks injete automaticamente as credenciais de serviço externo da ligação ao Unity Catalog.

Isto é mais útil quando:

• Precisas de chamar uma API REST externa ou um servidor MCP a partir de uma aplicação a correr fora do Databricks sem armazenar as credenciais diretamente na tua aplicação.
• Queres que o Databricks gere o armazenamento de credenciais, a atualização de tokens OAuth e os fluxos de autenticação por utilizador para serviços externos.
• Está a ligar um cliente MCP (como Claude Desktop ou Cursor) a um servidor MCP externo através de um proxy gerido pelo Databricks. Consulte Usar servidores MCP externos.

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

URL do ponto final de Proxy

O URL do endpoint do proxy segue este formato:

https://<workspace-hostname>/api/2.0/unity-catalog/connections/<connection-name>/proxy[/<sub-path>]

Como o proxy constrói o pedido de saída

O proxy combina o host da ligação e base_path com o subcaminho de pedido para construir a URL enviada ao serviço externo:

{connection host}{base_path}{sub-path}

Por exemplo, se a sua ligação estiver configurada com o host https://api.example.com e o caminho base /v1, um pedido para:

POST /api/2.0/unity-catalog/connections/my_connection/proxy/messages

É encaminhado para:

POST https://api.example.com/v1/messages

Encaminhamento de cabeçalhos

O proxy encaminha os seus cabeçalhos de pedido para o serviço externo com as seguintes regras:

• Cabeçalhos bloqueados: Cabeçalhos internos do Azure Databricks (como Authorization, Cookie, X-Databricks-* e cabeçalhos de sessão semelhantes) são removidos antes de serem encaminhados para evitar a fuga de credenciais do Azure Databricks para serviços externos.
• Todos os outros cabeçalhos que forneces são encaminhados sem alterações para o serviço externo. Use isto para passar cabeçalhos específicos do serviço, como Content-Type chaves de API personalizadas exigidas pelo serviço externo.

Corpo da solicitação

O corpo do pedido é encaminhado tal como está para o serviço externo sem modificações.

Métodos HTTP suportados

GET, POST, PUT, PATCH, DELETE

Authentication

Autentica-se com o endpoint do proxy usando autenticação padrão do Azure Databricks (token de acesso pessoal ou OAuth). O Azure Databricks recupera então as credenciais de serviço externo armazenadas na ligação ao Unity Catalog e injeta-as no pedido de saída. Todos os tipos de autenticação de ligação (token portador, OAuth M2M, OAuth U2M Partilhado, OAuth U2M por Utilizador) são suportados. Consulte Métodos de autenticação para serviços externos.

Exemplo

O exemplo seguinte envia um pedido POST através do proxy para um endpoint da API do Slack. O token portador do Slack é armazenado na slack_connection ligação do Catálogo Unity e nunca é incluído no pedido do cliente.

curl -X POST \
  "https://<workspace-hostname>/api/2.0/unity-catalog/connections/slack_connection/proxy/chat.postMessage" \
  -H "Authorization: Bearer <databricks-token>" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C123456", "text": "Hello from Databricks!"}'

Se o slack_connection estiver configurado com o host https://slack.com e o caminho base /api, este pedido é encaminhado para https://slack.com/api/chat.postMessage com as credenciais Slack automaticamente injetadas pelo Azure Databricks.

Enviar um pedido HTTP usando http_request

Envie pedidos HTTP ao serviço usando a http_request função SQL incorporada.

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

Execute o seguinte comando SQL em um bloco de anotações ou no editor SQL do Databricks. Substitua os valores dos espaços reservados:

• 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 concatenar após o base_path para invocar o recurso do serviço.
• json: O corpo JSON a ser enviado com a requisiçã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 Agenda 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.

Ver Ligar os agentes a serviços externos.

Proteja a sua conectividade de rede a serviços externos

O Azure Databricks encaminha o tráfego para ligações HTTP através do plano de computação serverless do seu espaço de trabalho para serviços externos. Pode proteger este tráfego usando Private Link ou IP allowlisting.

Private Link (recomendado)

O Private Link oferece isolamento completo para os inquilinos. Só o seu espaço de trabalho Azure Databricks pode aceder ao seu serviço através da ligação. O tráfego viaja por uma ligação privada em vez de pela internet pública. Use o Private Link para serviços externos alojados na sua rede cloud (VPC ou VNet).

Para configurar Private Link, veja Configurar conectividade privada aos recursos do seu VNet. Para consultar a série de blogs sobre padrões de configuração de proxy, veja Private and Dedicated Connectivity Patterns for Azure Databricks Serverless.

Lista de autorização de propriedade intelectual

Se o Private Link não for uma opção, configure as regras de firewall do seu serviço externo para adicionar à lista de permitidos os IPs de saída sem servidor do Azure Databricks. Com a lista de permitidos de IP, os IPs de saída são partilhados entre os clientes do Azure Databricks, pelo que esta abordagem não proporciona isolamento entre locatários.

Para a lista de IPs de saída serverless, consulte IPs de saída para a pré-visualização do firewall de computação serverless.