Sources de Données Externes (EDS) - Guide Complet

Aperçu​

Les Sources de Données Externes (EDS) dans Softyflow permettent une intégration transparente avec les systèmes et bases de données existants. Ce guide complet couvre la configuration de tous les types d'EDS pris en charge et leur utilisation dans les actions et les widgets.

Types d'EDS Pris en Charge​

Softyflow prend en charge les types de sources de données externes suivants :

• Bases de Données Relationnelles : MySQL, PostgreSQL, Oracle Database, Microsoft SQL Server
• Entrepôts de Données Cloud : Snowflake
• Intégrations API : REST APIs avec personnalisation complète
• Services d'Annuaire : LDAP (Beta)
• Sources Supplémentaires : Google Sheets (support partiel) ??

Configuration EDS par Type​

1. Configuration MySQL​

MySQL est un système de gestion de base de données relationnelle open-source populaire.

Étapes de Configuration :

1. Dans l'IDE Softyflow, naviguez vers Ressources → Base de Données Externe (EDS)
2. Sélectionnez "MySQL" comme type d'EDS
3. Configurez les paramètres de connexion pour chaque environnement (TEST, UAT, PROD)
4. Définissez les options avancées au format JSON
5. Testez la connexion avant d'enregistrer

Options Courantes :

• charset : Encodage de caractères (utf8mb4 recommandé)
• timezone : Fuseau horaire de la base de données
• ssl : Objet de configuration SSL
• acquireTimeout : Délai d'acquisition de connexion
• timeout : Délai d'exécution des requêtes

Paramètres de Connexion :

2. Configuration PostgreSQL​

PostgreSQL est un système de base de données objet-relationnel open-source puissant.

Paramètres de Connexion :

Configuration Avancée :

Cet objet JSON configure les paramètres avancés pour une connexion PostgreSQL. Il inclut des options SSL pour les connexions sécurisées, comme la désactivation du rejet de certificat non autorisé et la fourniture de l'autorité de certification, de la clé et du contenu du certificat. Il définit également des délais d'attente pour les instructions et les requêtes à 30 secondes et nomme l'application "Softyflow" pour une identification plus facile dans les journaux de la base de données.

3. Configuration Oracle Database​

Oracle Database est un système de gestion de base de données relationnelle de niveau entreprise.

Paramètres de Connexion :

Ce code fournit les paramètres de connexion pour une base de données Oracle. Il spécifie l'user, le password et la connectString nécessaires pour établir une connexion. L'objet options configure le pool de connexions, en définissant le nombre minimum et maximum de connexions, l'incrément et le délai d'attente du pool.

Formats de Chaîne de Connexion :

• Simple : hostname:port/service_name
• TNS : (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service_name)))
• Easy Connect : hostname:port/service_name:server_type/instance_name

4. Configuration Microsoft SQL Server​

Microsoft SQL Server est un système de gestion de base de données relationnelle développé par Microsoft.

Paramètres de Connexion :

Cet extrait montre les paramètres de connexion pour une base de données Microsoft SQL Server. Il inclut l'user, le password, la database et l'adresse du server. L'objet options active le chiffrement, fait confiance au certificat du serveur (utile pour les certificats auto-signés en développement) et définit les délais d'attente de requête et de connexion.

Options d'Authentification :

Ce code démontre deux méthodes d'authentification alternatives pour SQL Server. La première partie montre comment configurer l'authentification Windows (NTLM) en fournissant un domaine et des identifiants. La deuxième partie illustre comment se connecter en utilisant l'authentification par mot de passe Azure Active Directory, qui nécessite un nom d'utilisateur (au format email) et un mot de passe.

// Windows Authentication
{
  "domain": "DOMAIN_NAME",
  "authentication": {
    "type": "ntlm",
    "options": {
      "userName": "username",
      "password": "password",
      "domain": "domain"
    }
  }
}

// Azure Active Directory
{
  "authentication": {
    "type": "azure-active-directory-password",
    "options": {
      "userName": "user@domain.com",
      "password": "password"
    }
  }
}

5. Configuration Snowflake​

Snowflake est une plateforme d'entreposage de données basée sur le cloud.

Paramètres de Connexion :

Cet objet JSON définit les paramètres de connexion pour un entrepôt de données Snowflake. Il inclut l'identifiant de compte account (y compris la région), le username et le password. Des paramètres optionnels comme database, warehouse et schema peuvent être spécifiés. L'objet options permet de définir un role utilisateur, un timeout et de maintenir la session client active.

Authentification Multi-Facteurs :

Cet extrait configure l'authentification par paire de clés pour Snowflake, qui est une forme d'authentification multi-facteurs. Il utilise l'authentificateur snowflake_jwt et nécessite une privateKey et une passphrase optionnelle pour déchiffrer la clé. C'est une alternative plus sécurisée à l'authentification par mot de passe.

{
  "authenticator": "snowflake_jwt",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "passphrase": "key_passphrase"
}

6. Configuration API​

L'EDS API permet l'intégration avec les APIs REST et les services web.

Configuration de Base :

Ce bloc de code montre la configuration de base pour une Source de Données Externe basée sur API. Il définit une baseURL pour toutes les requêtes, un timeout global et une connectionUrl pour tester la santé de l'API. Il définit également des headers globaux et un runScript qui s'exécute avant que tout endpoint ne soit appelé, ce qui est utile pour des tâches comme récupérer un jeton d'authentification. Le tableau endpoints contiendra les définitions d'appels API spécifiques.

Configuration des Endpoints :

Chaque EDS API prend en charge les endpoints standard suivants qui correspondent aux opérations de base de données :

Cet extrait définit un seul endpoint retrieve pour une EDS API. Il spécifie la method HTTP (GET) et un modèle de value (URL) dynamique qui utilise des variables de template comme {{SF_table}} et {{SF_source._id}}. Il montre également comment ajouter des headers spécifiques à l'endpoint (par exemple, pour l'autorisation) et des params. Enfin, le script response permet de transformer les données retournées par l'appel API.

Types d'Endpoints Disponibles :

1. retrieve : Obtenir un enregistrement unique par ID
2. list : Obtenir plusieurs enregistrements avec pagination
3. count : Compter les enregistrements correspondant aux critères
4. insert : Créer un nouvel enregistrement
5. insertMany : Créer plusieurs enregistrements
6. update : Mettre à jour un enregistrement existant
7. delete : Supprimer un enregistrement
8. execute : Opérations personnalisées

Variables de Contexte Disponibles :

• SF_source : Source de données et paramètres de requête
• SF_table : Nom de la table/ressource
• SF_postData : Données pour les opérations POST/PUT
• SF_limit : Nombre maximum d'enregistrements à récupérer
• SF_sortby : Nom du champ de tri
• SF_page : Numéro de page actuel
• SF_direction : Direction de tri (1 ou -1)

7. Configuration LDAP (Beta)​

Intégration LDAP (Lightweight Directory Access Protocol) pour les services d'annuaire.

Paramètres de Connexion :

Ce code montre les paramètres de connexion pour un serveur LDAP. Il spécifie l'URL du serveur, le DN (Distinguished Name) pour la liaison et le password. L'objet options inclut des délais d'attente et des tlsOptions pour gérer les connexions sécurisées, dans ce cas, autorisant les certificats auto-signés.

LDAPS (LDAP Sécurisé) :

Cet extrait démontre comment configurer une connexion LDAP sécurisée (LDAPS). L'URL utilise le protocole ldaps. Les tlsOptions sont configurées pour une sécurité renforcée, nécessitant une ca (Autorité de Certification) de confiance et rejetant tout certificat non autorisé.

{
  URL: "ldaps://ldap.example.com:636/",
  DN: "cn=service,ou=services,dc=example,dc=com",
  password: "service_password",
  options: {
    "tlsOptions": {
      "ca": ["certificate_content"],
      "rejectUnauthorized": true
    }
  }
}

Configuration d'Environnement​

1. Configuration Multi-Environnements​

Softyflow prend en charge trois environnements pour chaque EDS :

• TEST : Environnement de développement et de test
• UAT : Environnement de test d'acceptation utilisateur
• PROD : Environnement de production

Chaque environnement peut avoir des paramètres de connexion différents, permettant des flux de déploiement appropriés.

2. Meilleures Pratiques de Configuration​

Sécurité :

• Utiliser des variables d'environnement pour les données sensibles
• Activer le chiffrement SSL/TLS lorsque c'est possible
• Mettre en œuvre des mécanismes d'authentification appropriés
• Effectuer une rotation régulière des mots de passe et des clés API

Performance :

• Configurer un pool de connexions approprié
• Définir des valeurs de délai d'attente raisonnables
• Optimiser les modèles de requêtes
• Surveiller l'utilisation des connexions

Fiabilité :

• Tester les connexions avant le déploiement
• Mettre en œuvre des mécanismes de nouvelle tentative
• Configurer une gestion d'erreurs appropriée
• Surveiller la santé du système

Gestion des Droits d'Accès​

Contrôle d'Accès Basé sur les Rôles​

Configurez les droits d'accès pour différents rôles d'utilisateurs :

Cette structure JSON définit le contrôle d'accès basé sur les rôles pour une EDS. Elle contient un tableau de roles. Chaque rôle lie un group d'utilisateurs (par exemple, "Administrators") à un ensemble de rights (create, read, update, delete). Dans cet exemple, les administrateurs ont toutes les permissions, tandis que les utilisateurs réguliers peuvent uniquement lire les données.

Types de Permissions​

• create : Permission d'insérer de nouveaux enregistrements
• read : Permission d'interroger et de récupérer des données
• update : Permission de modifier des enregistrements existants
• delete : Permission de supprimer des enregistrements

Meilleures Pratiques​

1. Meilleures Pratiques de Sécurité​

1. Gestion des Identifiants :

   • Utiliser des identifiants spécifiques à l'environnement
   • Effectuer une rotation régulière des mots de passe et des clés API
   • Mettre en œuvre un accès avec privilèges minimaux

2. Protection des Données :

   • Activer le chiffrement en transit (SSL/TLS)
   • Mettre en œuvre une validation appropriée des entrées
   • Assainir les paramètres de requête

3. Contrôle d'Accès :

   • Configurer des permissions basées sur les rôles
   • Auditer les modèles d'accès aux données
   • Surveiller les activités suspectes

2. Optimisation des Performances​

1. Optimisation des Requêtes :

   • Utiliser des index appropriés sur les tables de base de données
   • Limiter les ensembles de résultats avec un filtrage approprié
   • Mettre en œuvre la pagination pour les grands ensembles de données

2. Gestion des Connexions :

   • Configurer un pool de connexions approprié
   • Définir des valeurs de délai d'attente raisonnables
   • Surveiller l'utilisation des connexions

3. Stratégies de Mise en Cache :

   • Mettre en cache les données statiques ou à évolution lente
   • Mettre en œuvre une invalidation de cache appropriée
   • Considérer la mise en cache côté client pour les widgets

5.3. Gestion des Erreurs​

1. Dégradation Gracieuse :

   • Mettre en œuvre des mécanismes de secours
   • Fournir des messages d'erreur significatifs
   • Enregistrer les erreurs pour le débogage

2. Logique de Nouvelle Tentative :

   • Mettre en œuvre un backoff exponentiel
   • Définir des limites maximales de tentatives
   • Gérer les défaillances temporaires

3. Surveillance :

   • Suivre les métriques de performance EDS
   • Surveiller les taux et modèles d'erreurs
   • Configurer des alertes pour les défaillances critiques

Guide de Dépannage​

1. Problèmes de Connexion​

Problème : Impossible de se connecter à la base de données Solutions :

• Vérifier l'adresse du serveur et le port
• Vérifier les paramètres du pare-feu et du réseau
• Valider les identifiants et les permissions
• Tester depuis le même réseau que Softyflow

Problème : Erreurs de connexion SSL/TLS Solutions :

• Vérifier la validité du certificat SSL
• Vérifier les options de configuration SSL
• Mettre à jour les certificats s'ils sont expirés
• Désactiver temporairement SSL pour les tests

2. Problèmes de Requête​

Problème : Erreurs de syntaxe SQL Solutions :

• Valider la syntaxe SQL pour la base de données cible
• Vérifier les noms de champs et la structure de la table
• Utiliser correctement les fonctionnalités SQL spécifiques à la base de données
• Tester les requêtes directement dans les outils de base de données

Problème : Endpoint API introuvable Solutions :

• Vérifier l'URL de base de l'API et les chemins des endpoints
• Vérifier les méthodes HTTP et les paramètres
• Consulter la documentation de l'API
• Tester les endpoints avec des outils externes (Postman, curl)

3. Problèmes de Performance​

Problème : Performance de requête lente

Solutions :

• Ajouter des index de base de données appropriés
• Optimiser la structure des requêtes et les jointures
• Mettre en œuvre un filtrage et une pagination appropriés
• Considérer la mise en cache des résultats de requête

Problème : Utilisation élevée de la mémoire

Solutions :

• Réduire la taille des ensembles de résultats
• Mettre en œuvre le streaming pour les grands ensembles de données
• Optimiser les scripts de transformation de données
• Surveiller et ajuster les pools de connexions

Ce guide complet couvre tous les aspects de la configuration EDS dans Softyflow.