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

Cette page vous montre 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 les paramètres de connexion, notamment le nom d'hôte du serveur de votre espace de travail, les paramètres de ressources de calcul et les informations d'identification d'authentification.

Définissez ces propriétés sur l’URL de connexion JDBC, transmettez-les à la méthode DriverManager.getConnection ou utilisez 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

Attachez des balises clé-valeur aux requêtes SQL à des fins de suivi et d’analytique. Les balises 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

Configurez le connecteur pour vous connecter via un serveur proxy au lieu de vous connecter directement à Databricks. Le connecteur prend en charge l’authentification de base et SPNEGO lors de la connexion via un serveur proxy. Consultez les propriétés de connexion prises en charge.

Pour utiliser les paramètres de proxy au niveau du système, définissez UseProxy=1 et UseSystemProxy=1.

Pour configurer manuellement les paramètres de proxy :

1. Définissez UseProxy=1.
2. Définir ProxyHost, ProxyPortet ProxyIgnoreList.
3. Pour vous authentifier auprès du serveur proxy, choisissez une méthode :
   • De base : Définir ProxyAuth=1, ProxyUIDet ProxyPWD.
   • SPNEGO (environnements Kerberos) : authentifiez votre principal Kerberos au niveau du système, puis définissez ProxyAuth=2.

Configurer un proxy pour Cloud Fetch

Cloud Fetch nécessite une configuration de proxy distincte de la connexion du pilote principal. Utilisez les propriétés de connexion UseCFProxy, CFProxyHost, CFProxyPort, CFProxyAuth, CFProxyUID, et CFProxyPwd pour acheminer le trafic Cloud Fetch via un proxy. Consultez les propriétés de connexion prises en charge.

Si votre réseau est privé, autorisez *.blob.core.windows.net et *.store.core.windows.net, et ajoutez les téléchargements et révocations de certificats requis à votre liste blanche.

Résolution des problèmes

Si vous ne pouvez pas résoudre les problèmes de proxy, définissez EnableQueryResultDownload=0 pour désactiver Cloud Fetch et revenir au téléchargement direct.

Pour diagnostiquer les problèmes de performances, définissez LogLevel=4 pour activer la journalisation au niveau info. Le pilote enregistre la vitesse de téléchargement par segment, donc les jeux de résultats volumineux génèrent plusieurs lignes de journal :

CloudFetch download speed: 21.24 MB/s
CloudFetch download speed: 20.60 MB/s

Le pilote enregistre un avertissement lorsque la vitesse de téléchargement tombe en dessous d’environ 1 Mo/s. Le composant de journalisation est com.databricks.client.spark.jdbc.ResultFileDownloadHandler. Si les téléchargements sont lents ou bloqués, augmentez CloudFetchThreadPoolSize pour télécharger davantage de blocs de fichiers en parallèle.

Configuration de SSL

Si vous vous connectez à un espace de travail Databricks avec SSL activé, configurez le connecteur pour vous connecter à un socket compatible 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é. Configurez le connecteur pour accéder à un TrustStore spécifique. Si vous ne spécifiez pas de TrustStore, le connecteur utilise la valeur par défaut Java TrustStore (jssecacerts) ou les certificats si jssecacerts n'est pas disponible.

Pour configurer SSL :

1. Définissez SSL=1.
2. Si vous n'utilisez pas d'Java TrustStore par défaut, configurez-en un personnalisé :
   • Créez un TrustStore contenant votre certificat de serveur signé et approuvé.
   • Défini SSLTrustStore sur le chemin d’accès complet du TrustStore.
   • Définissez le mot de passe du TrustStore avec SSLTrustStorePwd.
   • Si le TrustStore n’est pas un TrustStore JKS, définissez SSLTrustStoreType sur soit BCFKS (BouncyCastle FIPS Keystore) soit PKCS12.

Pour modifier la stratégie de révocation de certificats, définissez les propriétés suivantes :

• CheckCertRevocation: défini pour 0 accepter les certificats révoqués. La valeur par défaut est 1.
• AcceptUndeterminedRevocation: défini pour 1 accepter des certificats avec un état de révocation indéterminé (par exemple, lorsque CRLDP est inaccessible ou expire). La valeur par défaut est 0.

Authentifier le pilote

Pour plus d’informations sur la configuration de l’authentification pour le pilote JDBC, consultez les paramètres d’authentification du pilote JDBC Databricks.