Guide d’utilisation de DBAPI

Présentation du produit

• DBAPI est un outil low-code destiné aux développeurs de data warehouses. Il suffit d’écrire des requêtes SQL et de configurer les paramètres sur une interface pour générer automatiquement des API HTTP. Il permet aux développeurs de créer rapidement des interfaces backend, particulièrement adaptées au développement d’interfaces backend pour les tableaux de bord de BI et la visualisation des données.

• DBAPI constitue le centre de gestion des interfaces de données de l’ensemble de l’entreprise, servant de plateforme pour fournir des services de données à l’extérieur. Il offre des fonctionnalités de création et de publication dynamiques d’API, ainsi qu’une gestion centralisée des interfaces, tout en permettant de surveiller les appels des clients vers ces interfaces et de contrôler leurs droits d’accès.

Adresse d’essai

Caractéristiques principales

• ✅ Prêt à l’emploi : aucune programmation requise, sans dépendance à d’autres logiciels (en mode standalone, seul un environnement Java est nécessaire).
• ✅ Déploiement léger : très faible consommation de ressources ; un serveur 2 cœurs et 4 Go suffit pour assurer un fonctionnement stable.
• ✅ Multiplateforme : compatible avec les modes standalone et cluster, ainsi qu’avec Windows, Linux et macOS.
• ✅ Configuration dynamique : permet la création et la modification dynamiques des API et des sources de données, avec déploiement à chaud transparent pour l’utilisateur.
• ✅ Contrôle des permissions : gestion fine des droits d’accès au niveau des API, avec prise en charge des listes blanches et noires d’adresses IP.
• ✅ Compatibilité étendue : supporte toutes les bases de données relationnelles utilisant le protocole JDBC (MySQL, SQL Server, PostgreSQL, Oracle, Hive, Dameng, Kingbase, Doris, OceanBase, GaussDB, etc.).
• ✅ SQL dynamique : prend en charge le SQL dynamique de style MyBatis, offrant une intégration complète de l’édition, de l’exécution et du débogage des requêtes SQL.
• ✅ Support complet : gère les instructions Select, Insert, Update, Delete ainsi que les appels aux procédures stockées.
• ✅ Gestion des transactions : permet l’exécution simultanée de plusieurs requêtes SQL et offre un contrôle flexible des transactions.
• ✅ Extensions via plugins : propose une riche gamme de plugins pour la mise en cache, la transformation des données, la génération d’alertes en cas d’échec, le traitement des paramètres, etc.
• ✅ Migration simplifiée : permet l’import/export des configurations d’API, facilitant la transition entre les environnements de test et de production.
• ✅ Traitement des paramètres : prend en charge les paramètres transmis via l’API ainsi que les paramètres complexes imbriqués sous forme de JSON, avec fonction de validation des entrées.
• ✅ Suivi et statistiques : fournit des fonctionnalités de consultation des logs d’appel d’API et de suivi des statistiques d’accès.
• ✅ Contrôle du trafic : intègre un mécanisme de limitation du débit pour les API.
• ✅ Orchestration des flux : permet une orchestration avancée des API complexes.
• ✅ Intégration ouverte : fournit une interface OpenAPI pour faciliter l’intégration avec d’autres systèmes.

Concepts de base

Exécuteur

L’exécuteur est une abstraction qui représente l’exécution de la logique métier d’une API. Il existe actuellement plusieurs types d’exécuteurs :

Type d’exécuteur	Description
Exécuteur SQL	Exécute des requêtes SQL dans la base de données et renvoie les résultats.
Exécuteur Elasticsearch	Exécute des requêtes DSL d’Elasticsearch et renvoie les résultats.
Exécuteur HTTP	Agit comme client HTTP, transfère les requêtes HTTP, récupère les réponses et les renvoie.

NOTE

La version personnelle ne prend actuellement en charge que l’exécuteur SQL.

Groupe d’API

Permet de classer et de gérer les API par catégories, regroupant celles liées à une même activité pour faciliter leur maintenance et leur recherche.

Client

Désigne l’application qui interagit avec les API de la plateforme, telle que Python, Java, etc. Chaque client dispose d’un identifiant unique clientId et d’une clé secrète secret, créés et attribués par l’administrateur système afin de définir ses droits d’accès aux API.

Démarrage rapide

Connexion au système

Utilisez les identifiants par défaut admin/admin pour vous connecter.

Configuration des sources de données

1. Accédez à la page de gestion des sources de données et cliquez sur « Créer une source de données ».

   

2. Remplissez les informations de connexion à la base de données et enregistrez.

   

3. Une fois enregistrée, retournez à la page des sources de données pour modifier ou supprimer la nouvelle source.

   

[!AVERTISSEMENT]

• Toutes les bases de données prenant en charge le protocole JDBC sont compatibles.
• Pour utiliser d’autres types de bases de données ou Oracle, vous devez spécifier manuellement la classe du pilote JDBC et placer le fichier JAR correspondant dans le répertoire extlib ou lib, puis redémarrer le service (dans le mode cluster, cette opération doit être effectuée sur tous les nœuds).
• Le répertoire lib contient déjà les pilotes MySQL, SQL Server, PostgreSQL et ClickHouse ; en cas de version incompatible, remplacez-les manuellement.
• Il est recommandé de placer vos propres fichiers JAR de pilotes dans le répertoire extlib pour une gestion unifiée.

Processus de création d’une API

1. Création d’un groupe d’API

• Accédez à la page de gestion des API et cliquez sur « Créer un groupe d’API » dans le menu de gauche.

  

• Saisissez le nom du groupe dans la fenêtre contextuelle et enregistrez.

  

• Après enregistrement, un nouveau groupe apparaît dans le menu de gauche ; cliquez sur le bouton « Plus » pour modifier ou supprimer le groupe.

  

2. Création d’une API

• Dans le groupe souhaité, cliquez sur le bouton « Créer une API » pour accéder à la page de configuration.

  

• Cliquez sur « Informations de base » pour renseigner les informations fondamentales de l’API.

  

  Accès : Les interfaces publiques sont accessibles directement, tandis que les interfaces privées nécessitent un token obtenu par le client (pour ce tutoriel, nous choisissons une interface publique afin de faciliter les tests ultérieurs).

  Chemin : Vous pouvez définir un chemin multi‑niveaux, par exemple /a/b/c, /a/b/c/d.

  Type de contenu : Si l’API utilise le format application/x-www-form-urlencoded, configurez les paramètres correspondants ; si elle utilise application/json, saisissez un exemple de paramètre JSON.

• Cliquez sur « Exécuteur » pour renseigner les informations relatives à l’exécuteur.

  

  Rédaction SQL : Utilisez la syntaxe dynamique SQL de MyBatis (sans les balises externes <select>, <insert>, <delete> ou <update>). Les paramètres sont indiqués par #{} ou ${} ; pour plus de détails, consultez le document sur la syntaxe dynamique SQL.

  Contrôle des transactions : Par défaut, les transactions sont désactivées. Pour les instructions insert, update ou delete, il est recommandé d’activer les transactions afin que, en cas d’échec, les modifications soient annulées. Si plusieurs instructions SQL doivent être exécutées dans le cadre d’une même API, activez les transactions pour exécuter toutes les requêtes dans un même bloc transactionnel.

  Remarque importante : Pour les bases de données comme HIVE qui ne prennent pas en charge les transactions, n’activez pas cette option, sous peine d’erreurs.

  Transformation des données : Si une transformation des données est nécessaire, indiquez le nom de la classe Java du plugin de transformation ; si aucun plugin n’est requis, laissez ce champ vide. Si le plugin nécessite des paramètres, précisez‑les. Pour plus de détails, reportez‑vous au document sur les plugins.

  Prise en charge de plusieurs requêtes SQL : Cliquez sur le bouton « Ajouter » pour ajouter une nouvelle fenêtre de rédaction SQL. Une API peut exécuter plusieurs requêtes SQL, dont les résultats finaux sont regroupés avant d’être renvoyés. Par exemple, lors d’une requête paginée, une seule API peut récupérer à la fois les détails et le nombre total d’enregistrements. Chaque fenêtre de rédaction SQL ne peut contenir qu’une seule instruction SQL.

  

[!ASTUCE] Lorsqu’un exécuteur inclut plusieurs requêtes SQL, chaque requête est associée à un plugin de transformation des données spécifique. Ces plugins s’appliquent toujours aux résultats d’une seule requête.

• Cliquez sur le bouton « Maximiser la fenêtre » pour accéder à l’interface de débogage SQL.

  

• Cliquez sur « Exécuter la requête SQL » pour lancer l’instruction ; si la requête comporte des paramètres, configurez‑les.

  

• Cliquez sur « Plugin global » pour saisir les informations relatives au plugin global.

  

  Mise en cache : Si vous souhaitez mettre en cache les résultats, indiquez le nom de la classe Java du plugin de cache ; sinon, laissez ce champ vide. Si le plugin nécessite des paramètres, précisez‑les.

  Alertes : Si vous voulez recevoir des alertes en cas d’échec de l’API, indiquez le nom de la classe Java du plugin d’alerte ; sinon, laissez ce champ vide. Si le plugin nécessite des paramètres, précisez‑les.

  Transformation globale des données : Si une transformation des données est requise, indiquez le nom de la classe Java du plugin de transformation ; sinon, laissez ce champ vide. Si le plugin nécessite des paramètres, précisez‑les.

  Traitement des paramètres : Si un traitement des paramètres est nécessaire, indiquez le nom de la classe Java du plugin de traitement ; sinon, laissez ce champ vide. Si le plugin nécessite des paramètres, précisez‑les.

  Pour plus de détails, reportez‑vous au document sur les plugins.

• Cliquez sur « Enregistrer » pour finaliser la création de l’API, puis revenez à la liste des API via le menu correspondant.

3. Publication de l’API

• Cliquez sur le bouton « Plus » à côté de l’API pour afficher le bouton « Publier », puis cliquez dessus pour rendre l’API publique.

  

• Cliquez sur le bouton « Plus » à côté de l’API pour afficher le bouton « Tester la requête », puis cliquez dessus pour accéder à la page de test.

  

• Cliquez sur « Envoyer la requête » pour lancer la demande ; si des paramètres sont nécessaires, remplissez‑les.

  

Gestion des clients

• Cliquez sur le menu « Clients », puis sur le bouton « Créer un client ».

  

• Renseignez les informations du client et enregistrez.

  

La création d’un client génère un identifiant clientId et une clé secrète secret. L’administrateur système doit communiquer ces informations au client (l’appelant de l’API).

Le client utilise son propre clientId et secret pour accéder à l’interface http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx afin d’obtenir dynamiquement un token. Ce token lui permet d’accéder aux API privées, à condition que l’administrateur ait déjà autorisé ce client à utiliser cette API.

Lors de la création d’un client, il est impératif de définir une date d’expiration pour le token. À partir de cette date, chaque token demandé sera valide pendant la période indiquée ; passé ce délai, un nouveau token devra être demandé.

[!ASTUCE] Si vous souhaitez que le token soit valable indéfiniment, fixez une date d’expiration très lointaine, par exemple 100 ans.

• Cliquez sur le bouton « Autoriser » pour attribuer des droits d’accès à l’API au client.

  

• Sélectionnez le groupe concerné et enregistrez.

  

Instructions d’utilisation du token

• Interface pour obtenir un token :

  http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx

• Lors de l’appel d’une API privée, le token doit être inclus dans le champ Authorization de l’en-tête pour pouvoir accéder à l’API. (Pour les API publiques, cette étape n’est pas nécessaire.)

• Exemple d’appel en Python :

import requests
headers = {"Authorization": "5ad0dcb4eb03d3b0b7e4b82ae0ba433f"}
re = requests.post("http://127.0.0.1:8520/api/userById", {"idList": [1, 2]}, headers=headers)
print(re.text)

• Modifiez l’API précédente pour la rendre privée, puis cliquez sur le bouton « Tester la requête ».

  

• À ce stade, lorsque vous cliquez sur « Envoyer la requête », l’API devient inaccessible.

  

• Entrez à nouveau le clientId et le secret, puis cliquez sur le bouton pour obtenir un nouveau token.

  

• Placez ce token dans le champ Authorization de l’en-tête, puis cliquez sur « Envoyer la requête » ; l’API est désormais accessible.

  

Configuration du pare-feu IP

L’activation du pare-feu permet de bloquer certaines adresses IP.

Surveillance

DBAPI peut être utilisé en s’appuyant uniquement sur une base de données métadonnées (postgresql/mysql/sqlite). Toutefois, si vous souhaitez également exploiter les fonctionnalités de surveillance disponibles dans l’interface (suivi des appels d’API, du volume de requêtes, du taux de réussite, etc.), il est nécessaire d’utiliser une autre base de données de journalisation (à mettre en place par l’utilisateur) pour stocker les journaux d’accès aux API. Il est recommandé d’utiliser ClickHouse, MySQL, PostgreSQL ou Doris ; bien sûr, d’autres bases de données relationnelles peuvent également être employées.

À l’heure actuelle, des scripts d’initialisation pour les bases de données de journalisation ClickHouse, MySQL et PostgreSQL sont fournis dans le répertoire sql.

NOTE

Si vous n’avez pas besoin des fonctionnalités de surveillance, vous pouvez choisir de ne pas déployer de base de données de journalisation et configurer simplement access.log.writer=null dans le fichier conf/application.properties. (La configuration par défaut est déjà access.log.writer=null.)

Méthodes de collecte des journaux

1. Collecte par fichiers : Par défaut, DBAPI écrit les journaux d’accès aux API dans un fichier disque, logs/dbapi-access.log. Les utilisateurs peuvent ensuite utiliser des outils tels que DataX ou Flume pour transférer ces journaux vers une base de données de journalisation.

2. Écriture directe dans la base de données : Si vous configurez access.log.writer=db dans le fichier conf/application.properties, DBAPI écrira les journaux d’accès aux API de manière asynchrone directement dans la base de données de journalisation. Cette méthode convient aux scénarios où le volume de logs est relativement faible.

3. Mise en tampon via Kafka : Si vous configurez access.log.writer=kafka dans le fichier conf/application.properties, DBAPI enverra les journaux d’accès aux API à Kafka. Les utilisateurs devront ensuite extraire ces journaux depuis Kafka pour les charger dans la base de données de journalisation. Cette approche est adaptée aux cas où le volume de logs est important, car Kafka peut assurer la mise en tampon des données.

NOTE

Dans ce cas, il est impératif de renseigner l’adresse Kafka dans le fichier conf/application.properties.

De plus, DBAPI intègre un outil permettant de consommer les journaux de Kafka et de les écrire dans la base de données de journalisation. Veuillez utiliser le script bin/dbapi-log-kafka2db.sh.

Résumé de la surveillance

• En cliquant sur le menu « Surveillance », vous pouvez consulter les statistiques relatives aux appels d’API.

  

Consultation des enregistrements d’appel d’API

• En sélectionnant l’onglet « Détails », vous pouvez effectuer une recherche dans les journaux d’appel d’API.

  

Autres fonctionnalités

Exportation de la documentation d’API

• Dans le menu API, cliquez sur le bouton « Outils », puis sur « Exporter la documentation d’API ».

  

Système de plugins

DBAPI propose cinq catégories de mécanismes de plugin. Vous pouvez télécharger des plugins depuis le marché des plugins. Si vous souhaitez développer vos propres plugins, veuillez consulter la documentation des plugins.

Plugin de cache

• Ce plugin permet de mettre en cache les résultats des exécuteurs. Par exemple, pour l’exécuteur SQL, il peut mémoriser les résultats des requêtes SELECT afin d’éviter des interrogations fréquentes de la base de données et ainsi réduire la charge sur celle-ci.
• La logique de mise en cache est définie par l’utilisateur, qui peut choisir de stocker les données dans Ehcache, Redis, MongoDB, etc.
• Lorsqu’aucune donnée n’est trouvée dans le cache, l’exécuteur est alors invoqué, et le résultat obtenu est mis en cache.

Scénario multi‑SQL avec l’exécuteur SQL

Pour l’exécuteur SQL, lorsque plusieurs instructions SQL sont regroupées au sein d’un même exécuteur, le plugin de cache encapsule les résultats de toutes ces instructions — si une instruction individuelle dispose d’un plugin de transformation, celui‑ci sera appliqué en premier — avant de mettre en cache l’ensemble.

Plugin d’alerte

• Lorsqu’une erreur interne survient au sein d’une API, le plugin d’alerte peut envoyer des notifications d’alerte par e‑mail, SMS, DingTalk, Feishu, WeChat d’entreprise, etc.
• La logique d’alerte est définie par l’utilisateur.

Plugin de conversion de données

• Parfois, les requêtes SQL ne permettent pas d’obtenir directement les données au format souhaité. Dans ce cas, il est pratique d’utiliser un plugin de conversion pour traiter et transformer les données au moyen d’un code personnalisé.
• Par exemple, il est possible de masquer ou de redresser des numéros de téléphone ou de cartes bancaires issus des résultats d’une requête SQL.

Scénario multi‑SQL avec l’exécuteur SQL

Pour l’exécuteur SQL, lorsqu’un seul exécuteur contient plusieurs instructions SQL, chaque instruction est associée à son propre plugin de conversion. Le plugin de conversion s’applique toujours aux résultats d’une seule instruction SQL.

Plugin global de conversion de données

• Par défaut, les données renvoyées par une API ont le format suivant : {success: true, msg: xxx, data: xxx}.
• Dans certains cas, il est nécessaire de modifier le format des données de réponse. Par exemple, le framework low‑code frontal AMIS exige que les interfaces retournent des données incluant un champ status. Dans ce cas, le plugin global de conversion de données peut être utilisé pour adapter le format de l’ensemble des données renvoyées par l’API.

Différence entre le plugin de conversion de données et le plugin global de conversion de données

Le plugin de conversion de données transforme le résultat d’un exécuteur spécifique (par exemple, les résultats d’une requête SQL), tandis que le plugin global de conversion de données modifie le format de l’ensemble des données renvoyées par l’API.

Plugin de traitement des paramètres

• Ce plugin permet d’effectuer des traitements personnalisés sur les paramètres des requêtes.
• Par exemple, convertir toutes les valeurs des paramètres en majuscules.
• Ou encore, déchiffrer des paramètres chiffrés reçus par l’API selon une logique définie par l’utilisateur.

Notes sur la prise en charge des versions

Le plugin de traitement des paramètres est pris en charge à partir de la version personnelle 4.0.16 et de la version entreprise 4.1.10.

Points d’attention

Prise en charge des sources de données

• Si vous utilisez Oracle ou d’autres types de sources de données, veuillez placer manuellement les pilotes JDBC correspondants dans le répertoire extlib ou lib après le déploiement de DBAPI. (Dans le cas d’un déploiement en cluster, chaque nœud doit recevoir manuellement le fichier JAR.)
• Il est recommandé de placer les pilotes dans le répertoire extlib pour faciliter leur gestion centralisée.

Normes d’écriture des requêtes SQL

• À l’instar de la syntaxe dynamique des requêtes MyBatis, DBAPI prend également en charge les paramètres #{} et ${}. Vous pouvez consulter la documentation sur la syntaxe dynamique des requêtes SQL. Il n’est pas nécessaire d’ajouter les balises externes telles que <select> ou <update> ; il suffit d’écrire directement le contenu de la requête.
• Attention : comme pour MyBatis, les signes inférieurs (<) doivent être remplacés par <.