Se connecter à des services HTTP externes
Aperçu
Cette fonctionnalité est en aperçu public.
Une connexion HTTP est un objet sécurisable Unity Catalog qui stocke des informations de Endpoint et d’identification pour un service HTTP externe. Utilisez une connexion HTTP pour envoyer des requêtes authentifiées aux APIs REST externes, aux serveurs MCP et aux outils d’agent depuis Databricks sans intégrer les identifiants dans votre code.
Disponibilité régionale
Les connexions HTTP Unity Catalog sont uniquement disponibles dans les régions où Model Serving est pris en charge. Voir la disponibilité des fonctionnalités de Model Serving.
Avant de commencer
Exigences du Workspace :
- Workspace activé pour Unity Catalog. Les workspaces créés après le 6 mars 2024 sont automatiquement activés pour Unity Catalog, y compris le provisionnement automatique du métastore. Vous n'avez pas besoin de créer manuellement un métastore, à moins que votre workspace ne soit antérieur à l'activation automatique et n'ait pas été activé pour Unity Catalog. Voir Se familiariser avec Unity Catalog.
Compute requis :
- Le compute Databricks doit utiliser Databricks Runtime 15.4 LTS ou supérieur et le mode d'accès Standard ou Dédié .
- Les SQL warehouses doivent être Pro ou Serverless et doivent utiliser la version 2023.40 ou ultérieure.
Autorisations requises :
- Pour créer une connexion, vous devez être administrateur de métastore ou un utilisateur disposant du privilège
CREATE CONNECTIONsur le métastore Unity Catalog attaché à l'espace de travail. Dans les espaces de travail qui ont été activés automatiquement pour Unity Catalog, les administrateurs d'espace de travail disposent du privilègeCREATE CONNECTIONpar default.
Des exigences d'autorisation supplémentaires sont spécifiées dans chaque section basée sur les tâches qui suit.
- Configurez l'authentification au service externe en utilisant l'une des méthodes suivantes :
- Jeton porteur : obtenez un jeton porteur pour une authentification simple basée sur un jeton.
- Enregistrement dynamique de client (DCR) : découvrir et enregistrer automatiquement les identifiants OAuth à l'aide du protocole RFC 7591. Chaque utilisateur s'authentifie individuellement.
- OAuth 2.0 Machine-to-Machine : créez et configurez une application pour activer l'authentification machine-to-machine.
- OAuth 2.0 utilisateur-à-machine partagé : authentifiez-vous avec l’interaction utilisateur pour partager l’accès entre l’identité de service et la machine.
- **OAuth 2.0 Utilisateur à machine par utilisateur** : Authentifiez-vous avec une interaction par utilisateur pour l'accès entre l'identité de l'utilisateur et la machine.
Méthodes d'authentification pour les services externes
Jeton Bearer
Un jeton porteur est un mécanisme d'authentification simple basé sur un jeton où un jeton est émis à un client et utilisé pour accéder aux Ressources sans nécessiter de justificatifs supplémentaires. Le jeton est inclus dans l'en-tête de la demande et octroie l'accès tant qu'il est valide.
OAuth machine-à-machine
L’authentification OAuth Machine-to-Machine (M2M) est utilisée lorsque deux systèmes ou applications communiquent sans intervention directe de l’utilisateur. Les jetons sont délivrés à un client machine enregistré, qui utilise ses propres identifiants pour s'authentifier. C'est idéal pour la communication de serveur à serveur, les microservices et les tâches d'automatisation lorsqu'aucun contexte utilisateur n'est nécessaire. Databricks recommande d’utiliser OAuth Machine-to-Machine lorsqu’il est disponible plutôt que OAuth User-to-Machine Shared.
OAuth utilisateur à machine partagé
L'authentification OAuth utilisateur à machine partagé permet à une identité d'utilisateur unique de s'authentifier et de partager le même ensemble d'identifiants sur plusieurs clients ou utilisateurs. Tous les utilisateurs partagent le même jeton d'accès. Cette approche convient aux appareils ou environnements partagés où une identité d'utilisateur cohérente est suffisante, mais elle réduit la responsabilité individuelle et le suivi. Dans les cas où une connexion d'identité est requise, sélectionnez utilisateur à machine partagé. Databricks recommande d'utiliser OAuth machine à machine lorsqu'il est disponible plutôt que OAuth utilisateur à machine partagé.
Enregistrement dynamique de client (DCR)
Dynamic Client Registration (DCR) utilise le protocole RFC 7591 pour découvrir automatiquement les Endpoint OAuth et enregistrer un client auprès du service externe. Vous fournissez uniquement l'URL de l'hôte, et Databricks s'occupe du reste — découverte du serveur d'autorisation, enregistrement des identifiants OAuth et gestion des flux de consentement par utilisateur. Chaque utilisateur est invité à autoriser lors de la première utilisation, permettant un contrôle d'accès individuel et une responsabilité. Le service externe doit prendre en charge OAuth 2.0 DCR et exposer les endpoints de métadonnées OAuth pour la découverte automatique. Cette méthode est idéale pour se connecter aux serveurs MCP et autres services qui prennent en charge la norme DCR.
OAuth utilisateur-machine par utilisateur
L'authentification OAuth utilisateur-machine par utilisateur permet à chaque identité d'utilisateur de s'authentifier et d'utiliser ses propres identifiants pour accéder aux ressources. Chaque utilisateur se voit attribuer un jeton d'accès unique, permettant un contrôle d'accès individuel, un audit et une responsabilisation. Cette méthode convient lorsqu'un accès aux données spécifique à l'utilisateur est requis et lors de l'accès aux services externes au nom de l'utilisateur individuel.
Les services externes doivent être conformes aux spécifications OAuth 2.0.
Les connexions HTTP qui utilisent OAuth doivent se connecter à des services qui respectent la spécification OAuth 2.0 officielle quant à la manière dont ils gèrent et renvoient les données du jeton d'accès. Cela signifie que les réponses du service doivent utiliser les noms de champ et les formats de données exacts décrits dans la spécification, tels que access_token, expires_in, et ainsi de suite.
Si vous rencontrez des problèmes de connexion à un service externe utilisant OAuth 2.0, vérifiez que les réponses du service respectent ces exigences.
Fournisseurs OAuth gérés
Pour les fournisseurs suivants, Databricks gère les identifiants OAuth dans le backend, de sorte que vous n'enregistrez pas votre propre application OAuth. Lorsque vous créez la connexion, sélectionnez OAuth utilisateur à machine par utilisateur et choisissez le fournisseur.
Fournisseur | Notes de configuration | Portées prises en charge | Description |
|---|---|---|---|
Glean MCP | Nécessite un hôte. Le chemin de base est configurable (par **default** : |
| Accédez à la recherche d'entreprise Glean, au chat, aux documents et aux outils d'agent. |
GitHub MCP | Utilise les autorisations de l’application GitHub plutôt que les champs d’application d’OAuth. Le champ Champ d'application d'OAuth n’est pas utilisé. | Contenu : lecture et écriture ; problèmes : lecture et écriture ; pull requests : lecture et écriture ; métadonnées : lecture ; membres : lecture ; projets : lecture | Accès en lecture et écriture au contenu, aux tickets et aux pull requests du repository GitHub ; accès en lecture aux membres de l’organisation et aux données du projet. |
MCP d'Atlassian | Aucun |
| Accès en lecture et en écriture aux tickets Jira et aux pages Confluence ; recherche de contenu Jira et Confluence. |
Slack MCP | Aucun |
| Recherchez des messages, fichiers, Canaux de distribution, canvases et utilisateurs Slack ; lisez l'historique des Canal de distribution, groupes, MPIM et messages directs ; publiez des messages et rédigez des canvases. |
Si vous utilisez OAuth géré, ajoutez les URI de redirection suivants à la liste d'autorisation si nécessaire :
Cloud | URI de redirection |
|---|---|
AWS |
|
Azure |
|
GCP |
|
Créer une connexion au service externe
Tout d'abord, créez une connexion Unity Catalog au service externe qui spécifie un chemin d'accès et des identifiants pour accéder au service.
Les avantages de l’utilisation d’une connexion Unity Catalog incluent les éléments suivants :
- Gestion sécurisée des identifiants : Les secrets et les jetons sont stockés et gérés de manière sécurisée dans Unity Catalog, garantissant qu'ils ne sont jamais exposés aux utilisateurs.
- Contrôle d'accès granulaire : Unity Catalog permet un contrôle précis sur les personnes qui peuvent utiliser ou gérer les connexions avec les privilèges
USE CONNECTIONetMANAGE. - Application de jeton spécifique à l’hôte : Les jetons sont limités au
host_namespécifié lors de la création de la connexion, ce qui garantit qu’ils ne peuvent pas être utilisés avec des hôtes non autorisés.
Autorisations requises : administrateur du Metastore ou utilisateur disposant du privilège CREATE CONNECTION.
Créez une connexion en utilisant l'une des méthodes suivantes :
- Utilisez l’interface utilisateur de Catalog Explorer.
- Exécutez la commande SQL
CREATE CONNECTIONdans un Notebook Databricks ou l'éditeur de query Databricks SQL. - Utilisez l'API REST Databricks ou l'interface CLI Databricks pour créer une connexion. Voir POST /api/2.1/unity-catalog/connections et les commandes Unity Catalog.
- Catalog Explorer
- SQL
Utilisez l'interface utilisateur de Catalog Explorer pour créer une connexion.
-
Dans votre workspace Databricks, cliquez sur
Catalogue . -
En haut du volet **Catalogue**, cliquez sur
l'icône **Ajouter** et sélectionnez **Créer une connexion** dans le menu. -
Cliquez sur Créer une connexion .
-
Saisissez un nom convivial pour la connexion .
-
Sélectionnez un type de connexion HTTP .
-
Sélectionnez un **Type d'authentification** parmi les options suivantes :
- Jeton Bearer
- Enregistrement dynamique du client
- OAuth machine à machine
- OAuth utilisateur à machine partagé
- OAuth utilisateur à machine par utilisateur
- Choisissez Configuration manuelle pour saisir vos propres identifiants OAuth. Si vous vous connectez à un serveur MCP externe et que vous souhaitez que Databricks gère les identifiants OAuth pour vous, consultez Fournisseurs OAuth gérés.
-
Sur la page Authentification , saisissez les propriétés de connexion suivantes pour la connexion HTTP.
Propriétés du jeton Bearer
Pour un jeton porteur :
Property | Description | Example value |
|---|---|---|
Host | The base URL of your Databricks workspace or deployment. |
|
Port | The network port used for the connection, typically |
|
Bearer Token | The authentication token used to authorize API requests. |
|
Base Path | The root path for API endpoints. |
|
Propriétés d'enregistrement dynamique du client
Pour l'enregistrement dynamique de client :
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 |
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. |
Propriétés OAuth machine à machine.
Pour OAuth Machine-to-Machine :
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: |
Token endpoint | Used by the client to obtain an access token by presenting its authorization grant or refresh token.
Usually in the format: |
Propriétés partagées OAuth utilisateur à machine
Pour OAuth User-to-Machine Shared :
- Vous serez invité à vous connecter à l’aide de vos identifiants OAuth. Les identifiants que vous utilisez seront partagés par toute personne utilisant cette connexion. Certains fournisseurs exigent une liste d’autorisation pour l’URL de redirection, veuillez inclure
<databricks_workspace_url>/login/oauth/http.htmlcomme liste d’autorisation d’URL de redirection. Exemple :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: |
Authorization endpoint | Used to authenticate with the resource owner via user-agent redirection.
Usually in the format: |
Token endpoint | Used by the client to obtain an access token by presenting its authorization grant or refresh token.
Usually in the format: |
Propriétés OAuth utilisateur-à-machine par utilisateur
Pour OAuth utilisateur à machine par utilisateur :
- Chaque utilisateur sera invité à se connecter en utilisant ses identifiants OAuth individuels la première fois qu'il utilisera la connexion HTTP. Certains fournisseurs exigent une liste d'autorisation pour l'URL de redirection, veuillez inclure
<databricks_workspace_url>/login/oauth/http.htmlcomme liste d'autorisation d'URL de redirection. Exemple :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: |
Authorization endpoint | Endpoint used to authenticate the resource owner via user-agent redirection and obtain authorization.
Usually in the format: |
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: |
Oauth credential exchange method | Providers require different methods for passing OAuth client credentials during token exchange. Select one of the following options:
|
- Cliquez sur Créer une connexion .
Utilisez la commande SQL CREATE CONNECTION pour créer une connexion.
Vous ne pouvez pas utiliser la commande SQL pour créer une connexion qui utilise **OAuth Machine-to-User Shared**. Consultez plutôt les instructions de l’interface utilisateur de Catalog Explorer.
Pour créer une nouvelle connexion à l'aide d'un **jeton Bearer**, exécutez la commande suivante dans un notebook ou l'éditeur de requêtes Databricks SQL :
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
host '<hostname>',
port '<port>',
base_path '<base-path>',
bearer_token '<bearer-token>'
);
Databricks recommande d’utiliser des secrets au lieu de chaînes en texte brut pour les valeurs sensibles telles que les identifiants. Par exemple :
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
host '<hostname>',
port '<port>',
base_path '<base-path>',
bearer_token secret ('<secret-scope>','<secret-key-password>')
)
Pour créer une nouvelle connexion à l'aide d'**OAuth Machine-to-Machine**, exécutez la commande suivante dans un Notebook ou l'éditeur de query 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>'
)
Partager la connexion Unity Catalog
Accorder USE CONNECTION privilèges aux principaux d'identité qui doivent utiliser la connexion :
- Dans votre Workspace, accédez à Catalogue > Connexions > Votre connexion > Autorisations .
- Accordez aux identités l'accès approprié à la connexion Unity Catalog.
Transférer les requêtes via le proxy de connexion HTTP
Pour envoyer une requête à un service externe, Databricks recommande d’utiliser le proxy de connexion HTTP.
Le proxy de connexion HTTP Unity Catalog est un Endpoint HTTP hébergé par Databricks qui transmet les requêtes aux services externes en votre nom. Au lieu de gérer les jetons d'authentification dans votre application, vous vous authentifiez auprès de Databricks et laissez Databricks injecter automatiquement les identifiants de service externe à partir de la connexion Unity Catalog.
Ceci est le plus utile lorsque :
- Vous devez appeler une API REST externe ou un serveur MCP à partir d'une application exécutée en dehors de Databricks sans stocker les informations d'identification directement dans votre application.
- Vous souhaitez que Databricks gère le stockage des informations d'identification, le refresh des jetons OAuth et les flux d'authentification par utilisateur pour les services externes.
- Vous connectez un client MCP (tel que Claude Desktop ou Cursor) à un serveur MCP externe via un proxy géré par Databricks. Consultez Utiliser des serveurs MCP externes.
Autorisations requises : USE CONNECTION sur l'objet de connexion.
URL d'endpoint proxy
L'URL de l'Endpoint proxy suit ce format :
https://<workspace-hostname>/api/2.0/unity-catalog/connections/<connection-name>/proxy[/<sub-path>]
parameter | Description |
|---|---|
| Le nom de la connexion HTTP Unity Catalog. |
| Facultatif. Segment de chemin ajouté après le |
Comment le proxy construit la requête sortante
Le proxy combine l'hôte de la connexion et base_path avec le sous-chemin de la requête pour construire l'URL envoyée au service externe :
{connection host}{base_path}{sub-path}
Par exemple, si votre connexion est configurée avec l'hôte https://api.example.com et le chemin de base /v1, une requête vers :
POST /api/2.0/unity-catalog/connections/my_connection/proxy/messages
Est transféré à :
POST https://api.example.com/v1/messages
Transfert d'en-tête
Le proxy transmet vos en-têtes de requête au service externe selon les règles suivantes :
- En-têtes bloqués : les en-têtes Databricks internes (tels que
Authorization,Cookie,X-Databricks-*et les en-têtes de session similaires) sont supprimés avant d'être transmis afin d'éviter de divulguer les identifiants Databricks à des services externes. - **Tous les autres en-têtes** que vous fournissez sont transmis tels quels au service externe. Utilisez ceci pour transmettre des en-têtes spécifiques au service tels que
Content-Typeou des clés API personnalisées requises par le service externe.
Corps de la requête
Le corps de la requête est transmis tel quel au service externe sans modification.
Méthodes HTTP prises en charge
GET, POST, PUT, PATCH, DELETE
Authentification
Vous vous authentifiez auprès de l'endpoint proxy en utilisant l'authentification Databricks standard (jeton d'accès personnel ou OAuth). Databricks récupère ensuite les informations d'identification du service externe stockées dans la connexion Unity Catalog et les injecte dans la requête sortante. Tous les types d'authentification de connexion (jeton du porteur, OAuth M2M, OAuth U2M partagé, OAuth U2M par utilisateur) sont pris en charge. Consultez Méthodes d'authentification pour les services externes.
Exemple
L'exemple suivant envoie une requête POST via le proxy à un Endpoint d'API Slack. Le jeton porteur Slack est stocké dans la connexion slack_connection Unity Catalog et n'est jamais inclus dans la requête client.
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!"}'
Si slack_connection est configuré avec l'hôte https://slack.com et le chemin de base /api, cette requête est transmise à https://slack.com/api/chat.postMessage avec les identifiants Slack automatiquement injectés par Databricks.
Envoyer une requête HTTP à l’aide de http_request
http_request est obsolète. Utilisez l'Endpoint proxy de connexions Unity Catalog avec le SDK du fournisseur pour le nouveau code.
Envoyer des requêtes HTTP au service à l’aide de la fonction SQL intégrée http_request.
Autorisations requises : USE CONNECTION sur l'objet de connexion.
Exécutez la commande SQL suivante dans un Notebook ou l'éditeur Databricks SQL. Remplacez les valeurs d'espace réservé :
connection-name: L'objet de connexion qui spécifie l'hôte, le port, le base_path et les identifiants d'accès.http-method: la méthode de requête HTTP utilisée pour effectuer l'appel. Par exemple :GET,POST,PUT,DELETEpath: Le chemin à concaténer après lebase_pathpour invoquer la ressource du service.json: Le corps JSON à envoyer avec la requête.headers: une mappage pour spécifier les en-têtes de requête.
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"
)
);
L'accès SQL avec http_request est bloqué pour les types de connexion utilisateur-machine par utilisateur et d'enregistrement dynamique de client. Utilisez plutôt le SDK Databricks pour 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"},
)
Utilisez des connexions HTTP pour les outils d'agent
Les agents peuvent utiliser la connexion HTTP pour accéder à des applications externes comme Slack, Google Calendar ou tout autre service avec une API utilisant des requêtes HTTP. Les agents peuvent utiliser des outils connectés en externe pour automatiser les tâches, envoyer des messages et récupérer des données à partir de plateformes tierces.
Voir Connecter des agents à des outils tiers avec les services MCP.
Limitations
-
La fonction
http_requestest soumise à une limite de débit. Il est conçu pour les cas d'utilisation interactifs et basés sur des agents, et non pour les requêtes de traitement par batch à volume élevé. Si vous exécutezhttp_requestsur de nombreuses lignes dans une seule query, les demandes peuvent être ralenties et entraîner des erreurs. Pour contourner ce problème, utilisez le SDK Databricks pour Python pour envoyer des requêtes par batchs plus petits avec des délais entre celles-ci. Pour le nouveau code, Databricks recommande d'utiliser l'Endpoint proxy de connexions Unity Catalog avec le SDK du fournisseur au lieu dehttp_request. -
La connectivité privée aux ressources de votre Virtual Private Cloud (VPC) à l'aide de Private Service Connect n'est pas prise en charge pour les connexions HTTP. Contactez votre équipe de support si vous avez besoin de cette fonctionnalité.