Se connecter à des services HTTP externes

Cette page explique comment configurer Lakehouse Federation pour exécuter des requêtes fédérées sur des données de service externe qui ne sont pas gérées par Azure Databricks. Pour en savoir plus sur lakehouse Federation, consultez Qu’est-ce que la Fédération Lakehouse ?

Pour vous connecter à votre base de données de service externe à l’aide de Lakehouse Federation, vous devez créer les éléments suivants dans votre metastore du catalogue Unity Azure Databricks :

• Connexion à votre base de données de service externe.
• Catalogue étranger qui met en miroir votre base de données de service externe dans Le catalogue Unity afin de pouvoir utiliser la syntaxe de requête du catalogue Unity et les outils de gouvernance des données pour gérer l’accès utilisateur Azure Databricks à la base de données.

Avant de commencer

Conditions requises pour l’espace de travail :

• Espace de travail activé pour Unity Catalog.

Voici les exigences de calcul à respecter :

• Connectivité réseau de votre ressource de calcul aux systèmes de base de données cibles. Consultez l’article Recommandations de mise en réseau pour Lakehouse Federation.
• Le calcul Azure Databricks doit utiliser Databricks Runtime 15.4 LTS ou ultérieur en mode Standard ou Dédié pour l'accès.
• 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.
• Pour créer un catalogue étranger, vous devez disposer de l’autorisation CREATE CATALOG sur le metastore et être le propriétaire de la connexion ou disposer du privilège CREATE FOREIGN CATALOG sur la connexion.

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.
  • 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

jeton du porteur : Jeton du porteur est un mécanisme d’authentification simple basé sur des jetons où un jeton est émis à un client et utilisé pour accéder aux ressources sans nécessiter d’informations d’identification supplémentaires. Le jeton est inclus dans l’en-tête de demande et accorde 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 émis à un client d’ordinateur inscrit, qui utilise ses propres informations d’identification pour s’authentifier. Cela est idéal pour les tâches de communication, de microservices et d’automatisation de serveur à serveur, où aucun contexte utilisateur n’est nécessaire. Databricks recommande d’utiliser OAuth Machine-to-Machine lorsqu’il est disponible sur OAuth User-to-Machine Shared.

OAuth User-to-Machine Shared : L’authentification partagée utilisateur-à-machine OAuth permet à une identité utilisateur unique d’authentifier et de partager le même ensemble d’informations d’identification 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é utilisateur cohérente est suffisante, mais elle réduit la responsabilité et le suivi individuels. Dans les cas où la connexion d’identité est requise, sélectionnez Partage utilisateur-machine. Databricks recommande d’utiliser OAuth Machine-to-Machine lorsqu’il est disponible sur OAuth User-to-Machine Shared.

OAuth Utilisateur-à-machine par utilisateur : l’authentification OAuth Utilisateur-à-machine par utilisateur permet à chaque identité utilisateur de s’authentifier et d’utiliser ses propres informations d’identification pour accéder aux ressources. Chaque utilisateur est émis un jeton d’accès unique, ce qui permet un contrôle d’accès, un audit et une responsabilité individuels. Cette méthode convient lorsque l’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 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 l'éditeur de requêtes SQL de Databricks.
• 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 Catalogue.

2. En haut du volet Catalogue, cliquez sur l’icône Ajouter, puis sélectionnez Ajouter une connexion dans le menu.

   Sinon, dans la page Accès rapide, cliquez sur le bouton Données externes >, accédez à l’onglet Connexions, puis cliquez sur Créer une connexion.

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
   • OAuth Machine-à-machine
   • OAuth Utilisateur-à-machine partagé
   • OAuth Utilisateur-à-machine par utilisateur

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

   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/

   Pour le jeton 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

   Pour le jeton partagé utilisateur à machine OAuth :

   • 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

   Pour un jeton OAuth Utilisateur-à-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.

Envoyer une requête HTTP au système externe

Maintenant que vous disposez d’une connexion, découvrez comment 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 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 les outils d’agent IA aux services externes.