Configurer une connexion à Databricks à l’aide du pilote JDBC Databricks

Cet article explique comment configurer une connexion à Databricks à l’aide du pilote JDBC Databricks, version 3 et ultérieure.

Configurer la connexion

Pour vous connecter à votre espace de travail Azure Databricks à l’aide du pilote JDBC, vous devez spécifier différents paramètres de connexion tels que le nom d’hôte du serveur de votre espace de travail Azure Databricks, les paramètres des ressources de calcul et les informations d’identification d’authentification pour vous connecter à l’espace de travail.

Vous pouvez définir la valeur de ces propriétés ai niveau de l’URL de connexion JDBC, les définir et les transmettre à la méthode DriverManager.getConnection, ou une combinaison des deux. Consultez la documentation du fournisseur pour savoir comment vous connecter au mieux à l’aide de votre application, client, SDK, API ou outil SQL spécifique.

L’URL de connexion JDBC doit avoir le format suivant. Les propriétés ne respectent pas la casse.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Vous pouvez également spécifier les paramètres à l’aide de la classe java.util.Properties ou d’une combinaison :

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

Les éléments d’URL de connexion sont décrits dans le tableau suivant.

Pour plus d’informations sur les propriétés supplémentaires, notamment les propriétés d’authentification, les propriétés de configuration SQL et les propriétés de journalisation, consultez Propriétés de connexion prises en charge.

Pour obtenir l’URL de connexion JDBC d’un cluster Azure Databricks :

1. Connectez-vous à votre espace de travail Azure Databricks.
2. Dans la barre latérale, cliquez sur Calcul, puis sur le nom du cluster cible.
3. Sous l’onglet Configuration, développez Options avancées.
4. Cliquez sur l’onglet JDBC/ODBC.
5. Copiez l’URL JDBC à utiliser comme URL de connexion JDBC, ou construisez l’URL à partir des valeurs indiquées dans les champs Nom d’hôte du serveur, Port et Chemin d’accès HTTP.

Pour obtenir l’URL de connexion JDBC d’un entrepôt Databricks SQL :

1. Connectez-vous à votre espace de travail Azure Databricks.
2. Dans la barre latérale, cliquez sur SQL Warehouses, puis sur le nom de l’entrepôt cible.
3. Cliquez sur l’onglet Détails de la connexion.
4. Copiez l’URL JDBC à utiliser comme URL de connexion JDBC, ou construisez l’URL à partir des valeurs indiquées dans les champs Nom d’hôte du serveur, Port et Chemin d’accès HTTP.

Configurer des balises de requête

Vous pouvez attacher des balises clé-valeur à vos requêtes SQL à des fins de suivi et d’analytique. Les balises de requête apparaissent dans la system.query.history table pour l’identification et l’analyse des requêtes.

Pour ajouter des balises de requête à votre connexion, incluez la query_tags propriété dans votre URL JDBC :

jdbc:databricks://<server-hostname>:<port>/<schema>;query_tags=key1:value1,key2:value2

Les balises de requête utilisent un format de paire clé :valeur séparé par des virgules :

• query_tags=key:value (balise unique)
• query_tags=key1:value1,key2:value2,key3:value3 (plusieurs balises)

Configurer les connexions proxy

Vous pouvez configurer le connecteur pour vous connecter via un serveur proxy au lieu de vous connecter directement à Databricks. Lors de la connexion via un serveur proxy, le connecteur prend en charge l’authentification de base et SPNEGO.

Pour configurer une connexion proxy :

1. Définissez la UseProxy propriété sur 1.
2. Pour configurer les paramètres de proxy au niveau du système, définissez UseSystemProxy la propriété sur 1, sinon définissez-la pour le pilote de la manière suivante :
   1. Définissez la ProxyHost propriété sur l’adresse IP ou le nom d’hôte de votre serveur proxy.
   2. Définissez la ProxyPort propriété sur le port utilisé par le serveur proxy pour écouter les connexions clientes.
   3. Définissez la ProxyIgnoreList propriété sur un nom d’hôte séparé par des virgules.
   4. Authentifiez-vous auprès du serveur proxy :
      • Pour utiliser l’authentification de base
        1. Définissez la ProxyAuth propriété sur 1.
        2. Définissez la ProxyUID propriété sur votre nom d’utilisateur pour accéder au serveur.
        3. Définissez la ProxyPWD propriété sur votre mot de passe pour accéder au serveur.
      • Pour utiliser l’authentification SPNEGO :
        1. Authentifiez votre principal Kerberos au niveau système.
        2. Définissez la ProxyAuth propriété sur 2.

Pour utiliser un autre proxy spécifiquement pour CloudFetch, suivez les étapes ci-dessus avec les propriétés suivantes : UseCFProxy, , CFProxyHost, CFProxyPortCFProxyAuth, , , CFProxyUIDCFProxyPwd

Configuration de SSL

Si vous vous connectez à Databricks avec ssl (Secure Sockets Layer) activé, vous pouvez configurer le connecteur pour vous connecter à un socket ssl. Lors de la connexion à un serveur via SSL, le connecteur utilise l’authentification unidirectionnel pour vérifier l’identité du serveur.

L’authentification unidirectionnel nécessite un certificat SSL signé et approuvé pour vérifier l’identité du serveur. Vous pouvez configurer le connecteur pour accéder à un TrustStore spécifique qui contient le certificat approprié. Si vous ne spécifiez pas de TrustStore, le connecteur utilise le Java TrustStore par défaut nommé jssecacerts. Si jssecacerts n’est pas disponible, le connecteur utilise plutôt des cacerts.

Pour configurer SSL :

1. Définissez la propriété SSL sur 1.
2. Si vous n’utilisez pas l’un des magasins d’approbations Java par défaut, créez un magasin d’approbations et configurez le connecteur pour l’utiliser :
   1. Créez un magasin de certificats de confiance contenant votre certificat de serveur signé et de confiance.
   2. Définissez la propriété SSLTrustStore sur le chemin complet du TrustStore.
   3. Définissez la propriété SSLTrustStorePwd sur le mot de passe pour accéder au TrustStore.
   4. Si TrustStore n’est pas un Magasin de confiance JKS, définissez la propriété SSLTrustStoreType sur le type correct. Les types pris en charge sont les suivants :
      • SSLTrustStoreType=BCFKS (Magasin de clés FIPS BouncyCastle)
      • SSLTrustStoreType=PKCS12 (Normes de chiffrement à clé publique #12)

Dans certains cas, où vous souhaitez modifier la stratégie de révocation de certificats, le connecteur fournit les paramètres suivants :

• La propriété CheckCertRevocation lorsqu’elle est définie sur 0 accepte les certificats révoqués (la valeur par défaut de la propriété est 1)
  • La propriété AcceptUndeterminedRevocation lorsqu’elle est définie sur 1 accepte les certificats où nous ne pouvons pas identifier l’état de révocation des certificats (CRLDP est inaccessible/expire etc.), la valeur par défaut de cette propriété est 0

Authentifier le pilote

Vous pouvez authentifier la connexion du pilote JDBC à l’aide de l’un des mécanismes d’authentification suivants :

• Authentification OAuth utilisateur à machine (U2M) (recommandé)
• M2M à l’aide d’identités managées Azure
• Jeton d’accès personnel Azure Databricks

Authentification OAuth utilisateur à machine (U2M)

Le pilote JDBC prend en charge l’authentification OAuth utilisateur à machine (U2M) pour la connexion et le consentement humains en temps réel afin d’authentifier le compte d’utilisateur Databricks cible. C’est ce que l’on appelle également l’authentification OAuth basée sur un navigateur.

Azure Databricks a créé l’ID client OAuth databricks-sql-jdbc pour les clients. Il s’agit également de l’ID client OAuth par défaut utilisé dans le pilote JDBC. Pour configurer l’authentification OAuth U2M, ajoutez simplement les propriétés suivantes à votre URL de connexion JDBC ou à l’objet java.util.Properties existant :

Authentification machine à machine (M2M) OAuth

Le pilote JDBC prend en charge l’authentification de machine à machine (M2M), également appelée authentification des informations d’identification du client OAuth 2.0, à l’aide de l’un des principaux ou identités suivants. Consultez Autoriser l’accès au principal de service à Azure Databricks avec OAuth.

• Un principal de service Databricks
• Un principal de service managé Azure
• Une identité managée d'Azure (attribuée par le système ou par l'utilisateur)

M2M à l’aide du principal de service géré Databricks

Pour configurer l’authentification à l’aide d’un principal de service managé Databricks :

1. Créez un principal de service managé Databricks et affectez-le aux comptes et espaces de travail Databricks.
2. Créez un secret Databricks OAuth pour le principal de service. Consultez le guide de configuration OAuth M2M.
3. Accordez des autorisations d’accès aux clusters et aux entrepôts SQL.
4. Ajoutez les propriétés suivantes à votre URL de connexion JDBC ou à l’objet java.util.Properties existant :

M2M à l’aide du principal de service géré Azure

Pour configurer l’authentification à l’aide d’un principal de service managé Azure :

1. Créez un secret Databricks OAuth pour le principal de service. Consultez le guide de configuration OAuth M2M.
2. Accordez des autorisations d’accès aux clusters et aux entrepôts SQL.
3. Ajoutez les propriétés suivantes à votre URL de connexion JDBC ou à l’objet java.util.Properties existant :

M2M à l’aide d’identités managées Azure

Pour configurer l’authentification à l’aide d’identités managées Azure :

1. Configurez des identités managées pour vos ressources Azure.
2. Accordez des autorisations d’accès aux clusters et aux entrepôts SQL.
3. Ajoutez les propriétés suivantes à votre URL de connexion JDBC ou à l’objet java.util.Properties existant :

Jeton d’accès personnel Azure Databricks

Pour authentifier votre connexion de pilote JDBC à l’aide d’un jeton d’accès personnel Azure Databricks, ajoutez les propriétés suivantes à votre URL de connexion JDBC ou à l’objet java.util.Properties :