Se connecter à des services HTTP externes

Une connexion HTTP est un objet sécurisable de Unity Catalog qui stocke les informations de point de terminaison et d’identification pour un service HTTP externe. Utilisez une connexion HTTP pour envoyer des requêtes authentifiées à des API REST externes, des serveurs MCP et des outils d’agent IA à partir de Azure Databricks sans incorporer d’informations d’identification dans votre code.

Avant de commencer

Conditions requises pour l’espace de travail :

• Espace de travail activé pour Unity Catalog. Les espaces de travail créés après le 9 novembre 2023 sont activés automatiquement pour unity Catalog, y compris le provisionnement automatique du metastore. Vous n’avez pas besoin de créer manuellement un metastore, sauf si votre espace de travail précède l’activation automatique et n’a pas été activé pour le catalogue Unity. Consultez l’article Activation automatique de Unity Catalog.

Voici les exigences de calcul à respecter :

• Le calcul Azure Databricks doit utiliser Databricks Runtime 15.4 LTS ou supérieur et le mode d'accès Standard ou Dedicated.
• Les entrepôts SQL 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 un administrateur de metastore ou un utilisateur disposant du privilège CREATE CONNECTION sur le metastore Unity Catalog attaché à l’espace de travail. Dans les espaces de travail activés automatiquement pour le catalogue Unity, les administrateurs de l’espace de travail ont le CREATE CONNECTION privilège par défaut.

Des exigences d’autorisation supplémentaires sont spécifiées dans chaque section basée sur les tâches qui suit.

• Configurez l’authentification auprès du service externe à l’aide de l’une des méthodes suivantes :
  • Jeton du porteur : obtenez un jeton du porteur pour l’authentification simple basée sur un jeton.
  • Inscription dynamique du client (DCR) : détectez et inscrivez automatiquement les informations d’identification OAuth à l’aide du protocole RFC 7591 . Chaque utilisateur s’authentifie individuellement.
  • OAuth 2.0 Machine à machine : créez et configurez une application pour activer l’authentification machine à machine.
  • OAuth 2.0 Partagé utilisateur-machine : authentifiez-vous via l'interaction avec l'utilisateur pour partager l'accès entre l'identité du service et une machine.
  • OAuth 2.0 Utilisateur-à-machine par utilisateur : authentifiez-vous avec une interaction par utilisateur pour permettre un accès entre l’identité de l’utilisateur et la machine.

Méthodes d’authentification pour les services externes

Les services externes doivent se conformer aux spécifications OAuth 2.0

Les connexions HTTP qui utilisent OAuth doivent se connecter aux services conformes à la spécification OAuth 2.0 officielle pour gérer et retourner des données de jeton d’accès. Cela signifie que les réponses du service doivent utiliser les noms de champs et les formats de données exacts décrits dans la spécification, par access_tokenexemple , expires_inet ainsi de suite.

Si vous rencontrez des problèmes de connexion à un service externe à l’aide d’OAuth 2.0, vérifiez que les réponses du service suivent ces exigences.

Créer une connexion au service externe

Tout d’abord, créez une connexion de catalogue Unity au service externe qui spécifie un chemin d’accès et des informations d’identification pour accéder au service.

Les avantages de l’utilisation d’une connexion de catalogue Unity sont les suivants :

• Gestion sécurisée des informations d’identification : Les secrets et les jetons sont stockés et gérés en toute sécurité dans le catalogue Unity, ce qui garantit qu’ils ne sont jamais exposés aux utilisateurs.
• contrôle d’accès granulaire : Catalogue Unity permet de contrôler précisément qui peut utiliser ou gérer les connexions avec les privilèges USE CONNECTION et MANAGE CONNECTION.
• application des jetons spécifiques à l’hôte : les jetons sont limités aux host_name spécifiés 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 de metastore ou utilisateur disposant du privilège CREATE CONNECTION.

Créez une connexion à l’aide de l’une des méthodes suivantes :

• Utilisez l’interface utilisateur de l’Explorateur de catalogues.
• Exécutez la commande CREATE CONNECTION SQL dans un notebook Azure Databricks ou dans l'éditeur de requête Databricks SQL.
• Utilisez l’API REST Databricks ou l’interface CLI Databricks pour créer une connexion. Consultez POST /api/2.1/unity-catalog/connections et Commandes Unity Catalog.

Explorateur de catalogues

Utilisez l’interface utilisateur de l’Explorateur de catalogues pour créer une connexion.

1. Dans votre espace de travail Azure Databricks, cliquez sur Catalog.

2. En haut du volet Catalogue, cliquez sur , puis sélectionnez Créer une connexion dans le menu.

3. Cliquez sur Create connection (Créer la connexion).

4. Entrez un nom de connexion convivial.

5. Sélectionnez un type de connexionHTTP.

6. Sélectionnez un type d’authentification dans les options suivantes :

   • Jeton du porteur
   • Enregistrement dynamique du client
   • OAuth Machine-à-machine
   • OAuth Utilisateur-à-machine partagé
   • OAuth Utilisateur-à-machine par utilisateur
     • Choisissez Configuration manuelle pour entrer vos propres informations d’identification OAuth. Si vous vous connectez à un serveur MCP externe et souhaitez que Databricks gère les informations d’identification OAuth pour vous, consultez Flux OAuth managés.

7. Dans la page Authentification, entrez les propriétés de connexion suivantes pour la connexion HTTP.

   Propriétés du Bearer token

   Pour un jeton du porteur :

   Propriété	Descriptif	Exemple de valeur
   Hôte	URL de base de votre espace de travail ou déploiement Databricks.	https://databricks.com
   Port	Port réseau utilisé pour la connexion, généralement 443 pour HTTPS.	443
   Jeton du porteur	Jeton d’authentification utilisé pour autoriser les demandes d’API.	bearer-token
   Chemin de base	Chemin d’accès racine pour les points de terminaison d’API.	/api/

   Propriétés d’inscription dynamique du client

   Pour l’inscription dynamique du client :

   Propriété	Descriptif
   Hôte	URL HTTPS du service externe. Databricks utilise cette URL pour découvrir le serveur d’autorisation OAuth et inscrire automatiquement un client.
   Port	Port réseau utilisé pour la connexion, généralement 443 pour HTTPS.
   Chemin de base	Chemin d’accès racine pour les points de terminaison d’API.
   Étendue OAuth	(Facultatif) Étendue à accorder pendant l’autorisation de l’utilisateur. Exprimé sous la forme d’une liste de chaînes délimitées par l’espace et sensibles à la casse. S’il est omis, le serveur détermine les étendues par défaut.

   Propriétés de machine à machine OAuth

   Pour OAuth Machine à Machine :

   Propriété	Descriptif
   ID du client	Identificateur unique de l’application que vous avez créée.
   Clé secrète client	Secret ou mot de passe généré pour l’application que vous avez créée.
   Étendue OAuth	Étendue à accorder lors de l'autorisation de l'utilisateur. Le paramètre d’étendue est exprimé sous la forme d’une liste de chaînes sensibles à la casse et séparées par des espaces. Par exemple : channels:read channels:history chat:write
   Point de terminaison de jeton	Utilisé par le client pour obtenir un jeton d’accès en présentant son octroi d’autorisation ou son jeton d’actualisation. Généralement au format : https://authorization-server.com/oauth/token

   Propriétés partagées utilisateur-à-machine OAuth

   Pour OAuth User-to-Machine Shared :

   • Vous serez invité à vous connecter à l’aide de vos informations d’identification OAuth. Les informations d’identification que vous utilisez seront partagées par toute personne qui utilise cette connexion. Certains fournisseurs nécessitent une liste d’autorisation pour l’URL de redirection, veuillez inclure <databricks_workspace_url>/login/oauth/http.html comme URL de redirection sur la liste d’autorisation. Exemple : https://databricks.com/login/oauth/http.html

   Propriété	Descriptif
   ID du client	Identificateur unique de l’application que vous avez créée.
   Clé secrète client	Secret ou mot de passe généré pour l’application que vous avez créée.
   Étendue OAuth	Étendue à accorder lors de l'autorisation de l'utilisateur. Le paramètre d’étendue est exprimé sous la forme d’une liste de chaînes sensibles à la casse et séparées par des espaces. Par exemple : channels:read channels:history chat:write
   Point de terminaison d’autorisation	Utilisé pour s’authentifier auprès du propriétaire de la ressource via la redirection de l’agent utilisateur. Généralement au format : https://authorization-server.com/oauth/authorize
   Point de terminaison de jeton	Utilisé par le client pour obtenir un jeton d’accès en présentant son octroi d’autorisation ou son jeton d’actualisation. Généralement au format : https://authorization-server.com/oauth/token

   Propriétés utilisateur à machine OAuth par utilisateur

   Pour OAuth de l'utilisateur à la machine par utilisateur :

   • Chaque utilisateur est invité à se connecter à l’aide de ses informations d’identification OAuth individuelles la première fois qu’il utilise la connexion HTTP. Certains fournisseurs nécessitent une liste d’autorisation pour l’URL de redirection, veuillez inclure <databricks_workspace_url>/login/oauth/http.html comme URL de redirection sur la liste d’autorisation. Exemple : https://databricks.com/login/oauth/http.html

   Propriété	Descriptif
   ID du client	Identificateur unique de l’application que vous avez créée. Utilisé par le serveur d’autorisation pour identifier l’application cliente pendant le flux OAuth.
   Clé secrète client	Secret ou mot de passe généré pour l’application que vous avez créée. Il est utilisé pour authentifier l’application cliente lors de l’échange de codes d’autorisation pour les jetons et doit être conservé confidentiel.
   Étendue OAuth	Étendue à accorder lors de l'autorisation de l'utilisateur. Exprimée sous forme d’une liste de chaînes sensibles à la casse et séparées par des espaces, définissant les autorisations demandées par l’application. Par exemple : channels:read channels:history chat:write
   Point de terminaison d’autorisation	Point de terminaison utilisé pour authentifier le propriétaire de la ressource via la redirection de l’agent utilisateur et obtenir l’autorisation. Généralement au format : https://authorization-server.com/oauth/authorize Le client dirige l’utilisateur vers ce point de terminaison pour se connecter et donner son consentement aux autorisations.
   Point de terminaison de jeton	Point de terminaison utilisé par le client pour échanger une octroi d’autorisation (par exemple, un code d’autorisation) ou un jeton d’actualisation pour un jeton d’accès. Généralement au format : https://authorization-server.com/oauth/token
   Méthode d’échange d’informations d’identification Oauth	Les fournisseurs nécessitent différentes méthodes pour transmettre les informations d’identification du client OAuth pendant l’échange de jetons. Sélectionnez l’une des options suivantes : header_and_body : place les informations d’identification dans l’en-tête d’autorisation et le corps de la demande (valeur par défaut). body_only : place les informations d’identification uniquement dans le corps de la demande sans en-tête d’autorisation. header_only : place les informations d’identification uniquement dans l’en-tête d’autorisation (pour les fournisseurs comme OKTA).

8. Cliquez sur Create connection (Créer la connexion).

SQL

Utilisez la commande CREATE CONNECTION SQL pour créer une connexion.

Pour créer une nouvelle connexion à l'aide d'un jeton Bearer , exécutez la commande suivante dans un notebook ou dans l'éditeur de requête 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 secrets au lieu de chaînes en texte clair pour des valeurs sensibles telles que les informations d’identification. 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 connexion à l’aide d’OAuth Machine-to-Machine, exécutez la commande suivante dans un notebook ou l’éditeur de requête 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 du catalogue Unity

Attribuez des USE CONNECTION privilèges aux entités d’identité qui doivent utiliser la connexion :

1. Dans votre espace de travail, accédez à Catalog>Connections> Your connection >Permissions.
2. Accordez aux identités l’accès approprié à la connexion du catalogue Unity.

Transférer des 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 du catalogue Unity est un point de terminaison HTTP hébergé par Databricks qui transfère 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 informations d’identification du service externe à partir de la connexion du catalogue Unity.

Ceci est le plus utile lorsque :

• Vous devez appeler une API REST externe ou un serveur MCP à partir d’une application s’exécutant 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, l’actualisation 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 du point de terminaison proxy

L’URL du point de terminaison proxy suit ce format :

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

Comment le proxy construit la requête sortante

Le proxy combine l’hôte de la connexion et base_path le sous-chemin de requête pour générer 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 d’accès /v1de base, une demande à :

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

Est transféré à :

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

Redirection d’en-tête

Le proxy transfère vos en-têtes de requête au service externe avec les règles suivantes :

• en-têtes bloqués : les en-têtes internes d'Azure Databricks (tels que Authorization, Cookie, X-Databricks-* et les en-têtes de session similaires) sont supprimés avant le transfert pour éviter de révéler les informations d'identification d'Azure Databricks aux services externes.
• Tous les autres en-têtes que vous fournissez sont transférés sans modification au service externe. Utilisez-le pour transmettre des en-têtes spécifiques au service, tels que Content-Type des clés API personnalisées requises par le service externe.

Corps de la demande

Le corps de la requête est transféré as-is au service externe sans modification.

Méthodes HTTP prises en charge

GET, POST, , PUT, PATCH, DELETE

Authentification

Vous vous authentifiez auprès du point de terminaison proxy à l’aide de l’authentification standard Azure Databricks (jeton d’accès personnel ou OAuth). Azure Databricks récupère ensuite les informations d’identification du service externe stockées dans la connexion du catalogue Unity et les injecte dans la requête sortante. Tous les types d’authentification de connexion (jeton du porteur, OAuth M2M, OAuth U2M Shared, OAuth U2M par utilisateur) sont pris en charge. Consultez les méthodes d’authentification pour les services externes.

Exemple

L’exemple suivant envoie une requête POST via le proxy à un point de terminaison d’API Slack. Le jeton Slack est stocké dans la connexion du slack_connection catalogue Unity et n’est jamais inclus dans la demande 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 d’accès de base /api, cette requête est transférée à https://slack.com/api/chat.postMessage avec les informations d’identification Slack injectées automatiquement par Azure Databricks.

Envoyer une requête HTTP à l’aide de http_request

Envoyez des requêtes HTTP au service à l’aide de la http_request fonction SQL intégrée.

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 informations d’identification d’accès.
• http-method: méthode de requête HTTP utilisée pour effectuer l’appel. Par exemple : GET, POST, PUT, DELETE
• path : chemin d’accès à concaténer après base_path pour appeler la ressource du service.
• json: corps JSON à envoyer avec la requête.
• headers: Une carte permettant de 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"
  )
);

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"},
)

Utiliser des connexions HTTP pour les outils d’agent

Les agents IA peuvent utiliser la connexion HTTP pour accéder à des applications externes telles que Slack, Google Calendar ou n’importe quel service avec une API à l’aide de 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.

Consultez Connecter des agents à des services externes.

Sécuriser votre connectivité réseau aux services externes

Azure Databricks achemine le trafic pour les connexions HTTP via le plan de calcul serverless de votre espace de travail vers des services externes. Vous pouvez sécuriser ce trafic à l’aide de Private Link ou d’une liste verte IP.

Private Link (recommandé)

Private Link fournit une isolation complète du locataire. Seul votre espace de travail Azure Databricks peut atteindre votre service via la connexion. Le trafic transite via une connexion privée plutôt que sur l’Internet public. Utilisez Private Link pour les services externes hébergés à l’intérieur de votre réseau cloud (VPC ou VNet).

Pour configurer Private Link, consultez Configurer la connectivité privée aux ressources de votre réseau virtuel. Pour connaître les modèles d’installation de proxy, consultez la série de blogs Modèles de connectivité privée et dédiée pour Azure Databricks Serverless.

Liste d’adresses IP autorisées

Si Private Link n'est pas une option, configurez les règles de pare-feu de votre service externe pour autoriser les adresses IP sortantes sans serveur d'Azure Databricks. Avec la liste blanche d’adresses IP, les adresses IP sortantes sont partagées entre les clients Azure Databricks, de sorte que cela ne fournit pas d’isolation des locataires.

Pour obtenir la liste des adresses IP sortantes serverless, consultez la préversion du pare-feu de calcul serverless.