Se connecter à Dataphin via JDBC - Dataphin - Centre de documentation Alibaba Cloud

Découvrez comment établir une connexion à Dataphin à l'aide d'un pilote JDBC.

Prérequis

Avant d'utiliser le pilote JDBC, activez la fonctionnalité OpenAPI de Dataphin.

Présentation

Deux modes d'authentification : Le pilote JDBC de Dataphin prend en charge deux modes d'authentification : le mode simple et le mode proxy. Pour plus d'informations, consultez les sections Modes d'authentification.
Résultats d'exécution cohérents : L'exécution d'une instruction SQL avec le pilote JDBC de Dataphin équivaut à son exécution dans la console Dataphin. Les résultats sont donc identiques. Les fonctionnalités configurées dans Dataphin, telles que les autorisations, les règles de masquage des données, les paramètres de sécurité et les normes de codage, influencent également les résultats obtenus via le pilote JDBC.

Limites

Utilisez JDBC pour vous connecter à Dataphin depuis tous les moteurs de calcul et certaines sources de données. Parmi les sources de données prises en charge figurent MySQL, Oracle, MaxCompute, Hive, AnalyticDB for MySQL 3.0, StarRocks, AnalyticDB for PostgreSQL et Doris.
Lorsque vous exécutez une instruction SQL avec le pilote JDBC de Dataphin, celui-ci prétraite l'instruction (traduction SQL, masquage des données, etc.). Les données résultantes transitent également par Dataphin. Ces processus engendrent une surcharge, ce qui peut allonger les temps de requête par rapport à une interrogation directe du moteur de calcul.
Le pilote JDBC de Dataphin soumet les instructions SQL à Dataphin via l'OpenAPI pour traitement, avant qu'elles ne soient transmises au moteur de calcul sous-jacent. Avant d'utiliser ce pilote, évaluez le volume d'appels attendu et déterminez si une mise à l'échelle de votre cluster Dataphin et de votre moteur de calcul est nécessaire.

Remarque
Si vous ne pouvez pas effectuer cette évaluation vous-même, soumettez une demande d'évaluation de capacité pour votre cluster Dataphin à l'équipe d'exploitation et de maintenance (O&M) de Dataphin. Cette demande ne couvre pas l'évaluation de capacité du moteur de calcul.
Dataphin ne prend actuellement pas en charge le contrôle du trafic ni le contrôle de la concurrence. Évaluez attentivement les impacts potentiels.

Version du pilote JDBC et lien de téléchargement

Pour obtenir le package JAR du pilote, contactez l'équipe d'exploitation et de maintenance (O&M) de Dataphin.

Paramètres de connexion

Remarque

Lorsque le pilote JDBC de Dataphin utilise l'AccessKey ID et l'AccessKey Secret de la plateforme (en mode proxy), utilisez la syntaxe set pour définir l'utilisateur d'accès.

set dp_delegation_uid = 'target_source_user_uid';
set dp_delegation_name = 'target_user_name';

Format de l'URL JDBC : jdbc:dataphin://host:port/catalog?[tenant_id=TenantID][&ssl=true][&log_level=Log_Level][&user=UserName][&password=PassWord][&delegation_uid=DelegationUid][&account_type=AccountType][&connect_timeout=ConnectTimeout][&engine=engine_type][compute_project=ProjectName]

Important

Les noms des paramètres sont sensibles à la casse.
Les crochets ([]) sont fournis à titre indicatif uniquement et doivent être omis de la chaîne de connexion réelle.

Paramètre	Obligatoire	Description	Exemple
host	Oui	Le nom de domaine de l'OpenAPI Dataphin. Vous pouvez obtenir le nom de domaine dans la section OpenAPI invocation address de la page AccessKey Management du Personal Center, comme illustré dans la figure suivante :	dataphin-openapi.****.aliyun.com
port	Non	Le port dépend de l'activation ou non du protocole HTTPS pour l'OpenAPI Dataphin. Si HTTPS est activé, le port est `443`. Sinon, le port est `80` (valeur par défaut).	80
catalog	Oui	La portée de requête par défaut. Pour utiliser une table physique Dataphin, spécifiez le nom anglais du projet Dataphin (project_name). Si vous utilisez une table logique Dataphin, saisissez le nom anglais du tableau de bord de données Dataphin (commençant par `LD_`). Pour utiliser une table de source de données gérée par Dataphin, saisissez le code de la source de données configuré dans Dataphin (commençant par `ds_`). Remarque Si la portée de requête par défaut est un bloc de données, le paramètre compute_project est obligatoire. Si la portée de requête par défaut est une table d'une source de données gérée par Dataphin, vous n'avez pas besoin de spécifier compute_project.	Exprojectname
tenant_id	Oui	L'ID du locataire à interroger.	111***111
ssl	Non	Indique s'il faut utiliser HTTPS. True : Utilise un nom de domaine HTTPS. False : Utilise un nom de domaine HTTP. La valeur par défaut est False.	False
currentschema	Non	Le schéma de la source de données. Si le catalogue utilise une table physique ou logique Dataphin, vous n'avez pas besoin de spécifier ce paramètre. Si la source de données utilisée dans le catalogue ne prend pas en charge les schémas, comme MySQL, vous n'avez pas besoin de spécifier ce paramètre. Si la source de données utilisée dans le catalogue prend en charge les schémas, comme Oracle, ce paramètre est facultatif. Si vous spécifiez un schéma, les données de ce schéma sont interrogées. Si vous ne spécifiez pas de schéma, le schéma par défaut de la base de données est interrogé.	information_schema
compute_project	Non	Spécifiez le nom anglais du projet. Ce projet exécute la requête SQL. Le projet et son moteur de calcul associé doivent disposer des autorisations de lecture sur les tables interrogées. Si la portée de requête spécifiée est un projet Dataphin, ce paramètre est facultatif. Si vous ne le spécifiez pas, le projet défini dans la portée de requête par défaut est utilisé pour exécuter l'instruction SQL. Si la portée de requête spécifiée est un bloc de données Dataphin, ce paramètre est obligatoire. Si la portée de requête spécifiée est une source de données Dataphin, vous n'avez pas besoin de spécifier ce paramètre.	Exprojectname
user	Oui	L'AccessKey ID d'un utilisateur ou de la plateforme. Lorsque vous utilisez le mode proxy, spécifiez l'AccessKey ID de la plateforme. Pour obtenir l'AccessKey ID de la plateforme, contactez l'équipe d'exploitation et de maintenance (O&M) de Dataphin. Vous pouvez obtenir l'AccessKey ID d'un utilisateur depuis la page AccessKey Management du Personal Center.	kIB**********PT0
log_level	Non	Le niveau de journalisation. Valeurs valides : DEBUG INFO WARNING ERROR	DEBUG
password	Oui	L'AccessKey Secret pour l'utilisateur spécifié. Pour obtenir l'AccessKey de la plateforme, contactez l'équipe d'exploitation et de maintenance (O&M) de Dataphin. Vous pouvez obtenir l'AccessKey ID d'un utilisateur depuis la page AccessKey Management du Personal Center.	Cy**************r2T
delegation_uid	Non	En mode proxy, ce paramètre spécifie l'utilisateur Dataphin à usurper. Pour l'utilisateur Dataphin proxifié, fournissez l'ID de compte correspondant en fonction du account_type sélectionné. La définition de ce paramètre active le mode proxy.	999***999
account_type	Non	Lorsque vous utilisez le mode proxy pour l'authentification, spécifiez le type de compte de l'utilisateur proxifié. ACCOUNT_NAME : Le nom d'utilisateur dans Dataphin. Ce mode est recommandé lorsque le nom d'utilisateur de l'application est identique au nom d'utilisateur Dataphin. USER_ID : L'ID interne unique dans Dataphin. Ce mode n'est généralement pas recommandé. SOURCE_USER_ID : L'ID de compte dans le système source. Cette option est disponible lorsque Dataphin est configuré pour l'authentification unique (SSO), telle que RAM, SAML ou OAuth. Il s'agit du compte de l'utilisateur dans le fournisseur d'identité (IdP). Remarque Ce paramètre est requis uniquement lorsque delegation_uid est défini. Si ce paramètre n'est pas spécifié, le type par défaut est USER_ID. Si des utilisateurs en double existent, l'authentification échoue.	USER_ID
connect_timeout	Non	Le délai d'attente d'acquisition de connexion, en secondes. Supérieur à 0 : Le délai d'attente en secondes. La valeur minimale est 10. Inférieur ou égal à 0 : Attente indéfinie.	10
engine	Non	Le moteur de calcul pour le projet spécifié par project_name dans la session ou la chaîne de connexion. Pour un moteur de calcul Hadoop, le moteur par défaut est Hive, mais vous pouvez utiliser ce paramètre pour le définir sur Impala ou Spark. Le type de moteur doit être préconfiguré dans le moteur de calcul. Si le moteur spécifié n'est pas pris en charge par le projet, ce paramètre est ignoré et un avertissement est renvoyé. Valeurs valides : MaxCompute Hologres Hive Impala Inceptor ArgoDB Spark Remarque Ce paramètre est ignoré lors de l'accès à une source de données.	MaxCompute
acceleration_source	Non	Spécifie la source d'accélération. Vous pouvez sélectionner le code de n'importe quelle source d'accélération au sein du locataire.	starrocks_code
acceleration_resource_group	Non	Le groupe de ressources d'accélération. Vous pouvez sélectionner un groupe de ressources configuré pour la source d'accélération sélectionnée.	starrocks_resource_group

Modes d'authentification

Mode simple

Définissez le nom d'utilisateur sur l'AccessKey ID de l'utilisateur et le mot de passe sur l'AccessKey Secret de l'utilisateur. Cela authentifie la connexion en tant que cet utilisateur. Pour afficher votre AccessKey, consultez la section Gestion des AccessKey de l'OpenAPI Dataphin.

Lorsque vous accédez à Dataphin via le pilote JDBC, Dataphin authentifie l'AccessKey et autorise l'utilisateur pour les ressources ou les instructions SQL demandées. Dataphin exécute ensuite l'instruction SQL en tant que cet utilisateur.

Mode proxy

Important

Avant d'utiliser le mode proxy, contactez l'équipe d'exploitation et de maintenance (O&M) de Dataphin pour activer et configurer cette fonctionnalité.

Le mode proxy est généralement utilisé pour l'intégration au niveau du système avec Dataphin. Cette méthode évite la distribution ou la configuration d'AccessKeys pour chaque utilisateur individuel. Spécifiez l'utilisateur proxifié dans la chaîne de connexion (URL JDBC) afin de garantir que les opérations sont autorisées en fonction des permissions de cet utilisateur. Un AccessKey au niveau de la plateforme dispose de privilèges élevés et peut proxifier n'importe quel utilisateur. Par exemple, si le client utilise un AccessKey de plateforme, définissez delegation_uid=userA lorsque userA se connecte. Dataphin usurpe alors l'identité de userA pour la connexion et effectue les vérifications de permissions basées sur le profil de cet utilisateur.

Pilote Dataphin

com.aliyun.dataphin.jdbc.DataphinDriver

API	Description	Définition
connect	Établit une connexion à la base de données.	`Connection connect (String url, Properties info) throws SQLException;`
acceptsURL	Vérifie si l'URL est prise en charge.	`boolean acceptsURL(String url) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinConnection

API

Description

Définition

createStatement

Crée un objet Statement.

Statement createStatement
(int resultSetType, 
int resultSetConcurrency)
throws SQLException;

prepareStatement

Crée un objet PreparedStatement.

PreparedStatement prepareStatement(String sql, int resultSetType,int resultSetConcurrency)throws SQLExcept;
PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability);

com.aliyun.dataphin.jdbc.DataphinStatement

API	Description	Définition
executeQuery	Exécute une instruction SQL et renvoie un objet ResultSet.	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	Spécifie le nombre de lignes à extraire de la base de données en un seul lot. Si ce paramètre n'est pas défini ou est défini sur 0, la valeur par défaut de 1000 est utilisée.	`void setFetchSize(int rows) throws SQLException`
cancel	Tente d'annuler l'exécution de l'objet `Statement`.	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

API	Description	Définition
executeQuery	Exécute une instruction SQL et renvoie un objet ResultSet.	`ResultSet executeQuery (String sql) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

API	Description	Définition
getColumnCount	Obtient le nombre de colonnes dans le jeu de résultats.	`int getColumnCount() throws SQLException;`
getColumnName	Obtient le nom d'une colonne dans le jeu de résultats.	`String getColumnName(int column) throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

API	Description	Définition
next	Déplace le curseur vers la ligne suivante dans l'objet `ResultSet`.	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

API

Description

Définition

getTables

Obtient les informations sur les tables.

Paramètres :
- catalog : La valeur par défaut est default.
- schemaPattern : Le nom du projet ou le nom du bloc de données.
- tableNamePattern : Le nom de la table. La correspondance floue est prise en charge. Les expressions régulières ne sont pas prises en charge.
- types : Ce paramètre n'est pas pris en charge.
Résultat :
- Le résultat est un objet ResultSet.
- Chaque ligne du ResultSet décrit une table. Vous pouvez parcourir le ResultSet à l'aide de next(). Seul le nom de la table peut être récupéré pour chaque ligne.
Obtenir le nom de la table :
- resultSet.getString("table_name")

getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException

getColumns

Obtient les informations sur les colonnes d'une table.

Paramètres :
- catalog : Le nom du projet ou le nom du bloc de données.
- schemaPattern : Ce paramètre n'est pas pris en charge.
- tableNamePattern : Le nom complet de la table. La correspondance floue et les expressions régulières ne sont pas prises en charge.
- columnNamePattern : Ce paramètre n'est pas pris en charge.
Résultat :
- Le résultat est un objet ResultSet.
- Chaque ligne du ResultSet décrit une colonne de table. Vous pouvez parcourir le ResultSet à l'aide de next(). Seul le nom de la colonne et le type de données peuvent être récupérés pour chaque ligne.
Obtenir le nom de la colonne : resultSet.getString("column_name").
Obtenir le type de données de la colonne : resultSet.getString("data_type").

ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern)

Exemples

Vous pouvez obtenir des informations sur le catalogue en utilisant le pilote JDBC de Dataphin.

1. Lister les tables

Liste les tables physiques et les vues physiques d'un projet.

Syntaxe

SHOW TABLES
    [FROM db_name]
    [LIKE 'pattern']

Paramètres

db_name :

Nom du projet Dataphin : Affiche les tables physiques du projet.
Pour les projets de développement et les blocs de données, ajoutez explicitement le suffixe _Dev.
Si db_name n'est pas spécifié, la valeur par défaut est project_name tel que spécifié dans la chaîne de connexion.

Résultat

Nom	Type	Description
dim_user	Table logique	Table des utilisateurs.
ods_user	Table physique	Table source des utilisateurs.
ods_user_logical_view	Vue logique	Vue logique.
ods_user_physical_view2	Vue physique	Vue physique.

2. Obtenir le schéma de la table

Affiche le schéma d'une table physique ou d'une vue physique.

Syntaxe

{DESCRIBE | DESC} table_name;

Remarque

Cette commande prend en charge uniquement les tables physiques et les vues physiques.

Paramètres

table_name : Le nom d'une table physique ou d'une vue physique.

Résultat

Nom	Type	Description
ID	BigInt	L'ID de l'utilisateur.
Name	String	Le nom de l'utilisateur.
DS	String	L'heure de partitionnement.

Contrôle des connexions côté serveur

Nombre maximal de connexions : La valeur par défaut est 100.
Délai d'expiration de la connexion : La valeur par défaut est de 288 000 s (2 heures). Si une connexion établie reste inactive, elle se déconnecte automatiquement après cette période. Si vous tentez d'effectuer une opération sur la connexion déconnectée, une erreur ou une exception de fermeture est renvoyée. Cela correspond au paramètre Connection_Idle_Timeout dans l'URL JDBC.

Métadonnées pour les tâches JDBC dans MaxCompute

Lorsqu'une tâche JDBC est soumise depuis Dataphin à une instance d'exécution MaxCompute, les métadonnées suivantes sont incluses dans la soumission :

Paramètre	Description
logical_project	Le nom du projet Dataphin où la tâche JDBC est exécutée.
EXT_JDBC_TASKRUN_ID	L'ID de la tâche JDBC.
EXT_DPN_TENANT_ID	L'ID du locataire Dataphin où la tâche JDBC est exécutée.
EXT_PLATFORM_ID	L'ID de la plateforme supérieure qui soumet la tâche à MaxCompute. La valeur par défaut est Dataphin.
biz_id	L'ID de l'utilisateur Dataphin qui exécute la tâche JDBC.
odps.idata.userenv	Informations sur l'environnement utilisateur. Cela inclut la version du SDK Java, la version de Java, l'adresse IP et les informations MAC de l'appareil. Exemple : `JavaSDK Revision:fcedc4d,Version:0.37.6,JavaVersion:1.8.0_152,IP:11...,MAC:00----*-25`.

Vous pouvez utiliser ces informations pour des cas d'utilisation tels que l'analyse des factures MaxCompute et la consultation des durées des jobs. Pour plus d'informations, consultez les sections Collecter des statistiques sur les comptes des N coûts les plus élevés et les jobs les plus longs des projets MaxCompute.