Conectar-se a um serviço HTTP externo

info

Visualização

Esse recurso está em Public Preview.

Uma conexão HTTP é um objeto protegível Unity Catalog que armazena informações endpoint e credenciais para um serviço HTTP externo. Utilize uma conexão HTTP para enviar solicitações autenticadas para APIs REST externas, servidores MCP e ferramentas de agentes AI do Databricks sem precisar incorporar credenciais no seu código.

Antes de começar

Requisitos do workspace:

• Espaço de trabalho habilitado para Unity Catalog. Os espaços de trabalho criados após 6 de março de 2024 são habilitados automaticamente para o Unity Catalog , incluindo o provisionamento automático do metastore. Você não precisa criar um metastore manualmente, a menos que seu workspace seja anterior à ativação automática e não tenha sido habilitado para Unity Catalog. Consulte Ativação automática do Unity Catalog.

Requisitos de computação:

• 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, você deve ser um administrador do metastore ou um usuário com o privilégio CREATE CONNECTION no metastore Unity Catalog anexado ao workspace. Em espaços de trabalho que foram habilitados para o Unity Catalog automaticamente, os administradores workspace têm o privilégio CREATE CONNECTION por default.

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.
  • Registro Dinâmico de Cliente (DCR) : Descobre e registra automaticamente credenciais OAuth usando o protocolo RFC 7591 . Cada usuário se autentica individualmente.
  • 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, onde um token é emitido para um cliente e usado para acessar um recurso sem a necessidade de credenciais adicionais. O token é incluído no cabeçalho da solicitação e concede acesso enquanto for válido.

OAuth Máquina a Máquina

A autenticação OAuth de máquina para máquina (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 autenticação. Isso é ideal para comunicação servidor-servidor, microsserviços e tarefas de automação onde não é necessário contexto do usuário. A Databricks recomenda o uso do OAuth Máquina a Máquina quando disponível, em vez do OAuth Usuário a Máquina Compartilhado.

Compartilhamento de usuário para máquina via OAuth

A autenticação compartilhada OAuth de usuário para máquina permite que uma única identidade de usuário se autentique e compartilhe o mesmo conjunto de credenciais entre vários clientes ou usuários. Todos os usuários compartilham o mesmo access token. Essa abordagem é adequada para dispositivos ou ambientes compartilhados onde uma identidade de usuário consistente é suficiente, mas reduz a responsabilidade individual e o acompanhamento. Nos casos em que for necessário fazer login com um autenticador, selecione Compartilhamento de Usuário para Máquina. A Databricks recomenda o uso do OAuth Máquina a Máquina quando disponível, em vez do OAuth Usuário a Máquina Compartilhado.

Registro dinâmico de clientes (DCR)

O Registro Dinâmico de Clientes (DCR) utiliza o protocolo RFC 7591 para descobrir automaticamente o endpoint OAuth e registrar um cliente no serviço externo. Você fornece apenas a URL do host e Databricks cuida do resto — descobrindo o servidor de autorização, registrando as credenciais OAuth e gerenciando os fluxos de consentimento por usuário. Cada usuário é solicitado a autorizar o uso no primeiro acesso, permitindo o controle de acesso individual e a responsabilização. O serviço externo deve suportar OAuth 2.0 DCR e expor um endpoint de metadados OAuth para descoberta automática. Este método é ideal para conectar-se a servidores MCP e outros serviços que suportam o padrão DCR.

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 se autentique e use suas próprias credenciais para acessar o recurso. A cada usuário é emitido um access token exclusivo, permitindo o controle de acesso individual, auditoria e responsabilização. Este método é adequado quando é necessário o acesso a dados específicos do usuário e quando se acessa um serviço externo em nome do usuário individual.

O serviço externo deve estar em conformidade com as especificações do OAuth 2.0

As conexões HTTP que usam OAuth devem se conectar a um serviço que esteja em conformidade com a OAuth especificação oficial 2.0 sobre como manipular e retornar dados de tokens de acesso. Isso significa que as respostas do serviço devem usar os nomes exatos dos campos e os formatos de dados descritos na especificação, como access_token, expires_in, e assim por diante.

Se o senhor 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 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 em Adicione o ícone e selecione "Criar uma conexão" no menu.

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
   • Registro dinâmico de clientes
   • OAuth máquina a máquina
   • Usuário OAuth para máquina compartilhada
   • OAuth Usuário para máquina por usuário
     • Selecione Configuração Manual para inserir suas próprias credenciais OAuth. Se você estiver se conectando a um servidor MCP externo e quiser que Databricks gerencie as credenciais OAuth para você, consulte Gerenciar fluxos OAuth.

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

Propriedades dos tokens de portador

Para tokens ao portador:

Property	Description	Example value
Host	The base URL of your Databricks workspace or deployment.	https://databricks.com
Port	The network port used for the connection, typically 443 for HTTPS.	443
Bearer Token	The authentication token used to authorize API requests.	bearer-token
Base Path	The root path for API endpoints.	/api/

Propriedades de registro dinâmico de clientes

Para registro dinâmico de clientes:

Property	Description
Host	The HTTPS URL of the external service. Databricks uses this URL to discover the OAuth authorization server and register a client automatically.
Port	The network port used for the connection, typically 443 for HTTPS.
Base Path	The root path for API endpoints.
OAuth scope	(Optional) Scope to grant during user authorization. Expressed as a list of space-delimited, case-sensitive strings. If omitted, the server determines the default scopes.

Propriedades de comunicação máquina a máquina OAuth

Para OAuth de máquina para máquina:

Property	Description
Client ID	Unique identifier for the application you created.
Client secret	Secret or password generated for the application that you created.
OAuth scope	Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example: channels:read channels:history chat:write
Token endpoint	Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format: https://authorization-server.com/oauth/token

Propriedades compartilhadas entre usuário e máquina via OAuth

Para compartilhamento OAuth 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

Property	Description
Client ID	Unique identifier for the application you created.
Client secret	Secret or password generated for the application that you created.
OAuth scope	Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example: channels:read channels:history chat:write
Authorization endpoint	Used to authenticate with the resource owner via user-agent redirection. Usually in the format: https://authorization-server.com/oauth/authorize
Token endpoint	Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format: https://authorization-server.com/oauth/token

Propriedades de usuário para máquina do OAuth por usuário

Para autenticação OAuth 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

Property	Description
Client ID	Unique identifier for the application you created. Used by the authorization server to identify the client application during the OAuth flow.
Client secret	Secret or password generated for the application that you created. It is used to authenticate the client application when exchanging authorization codes for tokens and must be kept confidential.
OAuth scope	Scope to grant during user authorization. Expressed as a list of space-delimited, case-sensitive strings defining the permissions the application requests. For example: channels:read channels:history chat:write
Authorization endpoint	Endpoint used to authenticate the resource owner via user-agent redirection and obtain authorization. Usually in the format: https://authorization-server.com/oauth/authorize The client directs the user to this endpoint to log in and consent to permissions.
Token endpoint	Endpoint used by the client to exchange an authorization grant (such as an authorization code) or refresh token for an access token. Usually in the format: https://authorization-server.com/oauth/token
Oauth credential exchange method	Providers require different methods for passing OAuth client credentials during token exchange. Select one of the following options: header_and_body: Places credentials in both the authorization header and request body (default). body_only: Places credentials only in the request body without an authorization header. header_only: Places credentials only in the authorization header (for providers like OKTA).

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

Compartilhar conexão Unity Catalog

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

1. Em seu workspace, acesse Catálogo > Conexões > Sua conexão > Permissões .
2. Conceda às identidades o acesso apropriado à conexão com o Unity Catalog .

Encaminhar solicitações através do proxy de conexão HTTP

Para enviar uma solicitação a um serviço externo, a Databricks recomenda o uso do proxy de conexão HTTP.

O proxy de conexão HTTP Unity Catalog é um endpoint HTTP hospedado Databricksque encaminha solicitações para serviços externos em seu nome. Em vez de gerenciar tokens de autenticação em seu aplicativo, você se autentica com o Databricks e permite que o Databricks injete automaticamente as credenciais do serviço externo da conexão do Unity Catalog.

Isso é mais útil quando:

• Você precisa chamar uma API REST externa ou um servidor MCP a partir de um aplicativo executado fora do Databricks, sem armazenar credenciais diretamente no seu aplicativo.
• Você deseja que Databricks lide com o armazenamento de credenciais, refresh de tokens OAuth e os fluxos de autenticação por usuário para serviços externos.
• Você está conectando um cliente MCP (como o Claude Desktop ou o Cursor) a um servidor MCP externo por meio de um proxy Databricks-gerenciar. Consulte Usar servidores MCP externos.

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

URL endpoint do proxy

A URL do endpoint do proxy segue este formato:

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

Parâmetro	Descrição
<connection-name>	O nome da conexão HTTP Unity Catalog .
<sub-path>	Opcional. Um segmento de caminho adicionado após o base_path da conexão ao construir a URL de saída. Evite chamar diretamente a URL base da conexão.

Como o proxy constrói a solicitação de saída

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

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

Por exemplo, se sua conexão estiver configurada com o host https://api.example.com e o caminho base /v1, uma solicitação para:

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

É encaminhado para:

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

Encaminhamento de cabeçalho

O proxy encaminha os cabeçalhos da sua solicitação para o serviço externo seguindo as seguintes regras:

• Cabeçalhos bloqueados : Os cabeçalhos internos Databricks (como Authorization, Cookie, X-Databricks-* e cabeçalhos de sessão semelhantes) são removidos antes do encaminhamento para evitar o vazamento de credenciais Databricks para serviços externos.
• Todos os outros cabeçalhos fornecidos serão encaminhados sem alterações para o serviço externo. Use isso para passar cabeçalhos específicos do serviço, como Content-Type ou chave API personalizada exigida pelo serviço externo.

Corpo da solicitação

O corpo da solicitação é encaminhado ao serviço externo tal como está, sem modificações.

Métodos HTTP suportados

GET, POST, PUT, PATCH, DELETE

Autenticação

Você se autentica com o endpoint do proxy usando a autenticação padrão Databricks ( access token pessoal ou OAuth). Em seguida, o Databricks recupera as credenciais do serviço externo armazenadas na conexão do Unity Catalog e as insere na solicitação de saída. Todos os tipos de autenticação de conexão (tokens Bearer, OAuth M2M, OAuth U2M Compartilhado, OAuth U2M por Usuário) são suportados. Consulte Métodos de autenticação para serviços externos.

Exemplo

O exemplo a seguir envia uma solicitação POST através do proxy para um endpoint da API do Slack. Os tokens de portador do Slack são armazenados na conexão Unity Catalog slack_connection e nunca são incluídos na solicitação do cliente.

Bash

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 slack_connection estiver configurado com o host https://slack.com e o caminho base /api, esta solicitação será encaminhada para https://slack.com/api/chat.postMessage com as credenciais do Slack injetadas automaticamente pelo Databricks.

Enviar uma solicitação HTTP usando http_request

atenção

http_request Está obsoleto. Use o endpointproxy de conexõesUnity Catalog com o SDK do provedor para o novo código.

Envie 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 SQL com http_request é bloqueado para os tipos de conexão Usuário-para-Máquina Por Usuário e Registro Dinâmico de Cliente. Em vez disso, use o SDK do Databricks para Python.

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 agentes a serviços externos.

Limitações

• A conectividade privada com o recurso em sua VPC usando o serviço privado Connect não é compatível com conexões HTTP. Entre em contato com sua equipe de suporte se precisar dessa funcionalidade.