Sources de données externes

À quoi ça sert

Une source de données externe est une base de données ou une API de votre organisation — distincte de Deltia — que Deltia lit en lecture seule : « Bases de données et API de votre organisation que le module KPI et l'assistant IA peuvent lire. En lecture seule. » Une fois la source déclarée, un administrateur du module KPI en adopte les collections pour que les auteurs de graphiques puissent les utiliser, à côté des données de Deltia. Voir Sources de données externes dans les KPI.

Six types de source sont proposés : « Base MongoDB », « Base Oracle », « Google Ads », « Meta Ads », « TikTok Ads » et « API REST (JSON) ». Une base MongoDB ou Oracle est interrogée en direct. Les quatre autres types sont des API : Deltia en importe les lignes, puis les met à jour régulièrement.

La déclaration se fait dans « Intégrations », « Approbation des connecteurs », onglet « Sources de données ». Elle est réservée aux administrateurs du module Connecteurs.

Concepts clés

• Source de données — la connexion à une base ou à une API : son adresse, son compte et ses réglages. Elle ne contient aucun graphique.
• Statut — l'état de la dernière vérification : « Non testée », « Opérationnelle », « Lecture impossible » (la connexion fonctionne mais aucune donnée n'a pu être lue) ou « Injoignable ».
• Source API — une source Google Ads, Meta Ads, TikTok Ads ou API REST. Ses lignes sont copiées dans Deltia à chaque synchronisation ; un graphique lit cette copie.
• Synchronisation — l'import des lignes d'une source API. Le premier passage remonte l'historique par tranches (« Import initial »), les suivants ne relisent que les derniers jours.
• Flux — un jeu de lignes importé depuis l'API : un rapport pour Google Ads, Meta Ads ou TikTok Ads, un flux de la définition pour une API REST.
• Scope des données — le scope dans lequel sont rangées les lignes d'une source API. Seuls les membres de ce scope les voient dans les graphiques. Un scope peut être fixe, ou calculé ligne par ligne par un code.
• Rôles autorisés à lire la source — les rôles qui peuvent lire la source, quel que soit leur accès au module Connecteurs.
• Tunnel VPN — un accès réseau privé à la base d'une organisation, déclaré par un super-administrateur de la plateforme. Une source Oracle peut passer par lui.

Comment faire

Déclarer une base MongoDB

1. Cliquez sur votre avatar, puis, sous « Administration », sur « Intégrations ».
2. Cliquez sur la carte « Approbation des connecteurs », puis sur l'onglet « Sources de données ».
3. Cliquez sur « Ajouter une source ». Le « Type de source » proposé d'emblée est « Base MongoDB ».
4. Renseignez « Nom », « Hôte », « Port », « Base de données », « Utilisateur » et « Mot de passe » — tous obligatoires.
5. Renseignez « Base d'authentification » et « Replica set » si votre base les demande.
6. Laissez « TLS » activé, sauf raison particulière.
7. Cochez « Lire sur un secondaire » pour que les graphiques ne concurrencent pas votre production.
8. Sous « Rôles autorisés à lire la source », choisissez « Seulement certains rôles » puis les rôles concernés.
9. Réglez la « Durée du cache (secondes) » si la valeur par défaut ne convient pas.
10. Cliquez sur « Ajouter ».

Le message « Source de données créée » confirme la création. Sans rôle choisi, personne ne lit la source, hormis les administrateurs du module Connecteurs : « Les administrateurs du module Connecteurs lisent toutes les sources, quel que soit ce choix. » À l'inverse d'un tableau de bord, l'absence de rôle ne rend rien accessible aux autres.

Déclarer une source publicitaire

Les sources « Google Ads », « Meta Ads » et « TikTok Ads » se déclarent comme les autres, avec en plus une connexion à l'API publicitaire, le choix des comptes lus et un éditeur de rapports. Voir Sources publicitaires.

Déclarer une base Oracle

1. Dans l'onglet « Sources de données », cliquez sur « Ajouter une source ».
2. Choisissez « Base Oracle » comme « Type de source ».
3. Renseignez « Nom », « Hôte » et « Port » (1521 par défaut).
4. Choisissez l'« Identifiant de la base » : « Nom de service » ou « SID ». Le nom de service est à préférer ; le SID ne sert qu'aux instances 11g enregistrées sans service. Saisissez-le dans « Base de données ».
5. Renseignez le « Schéma » propriétaire des tables à lire. Vide, c'est le schéma de l'utilisateur de connexion.
6. Renseignez « Utilisateur » et « Mot de passe ».
7. Choisissez les « Rôles autorisés à lire la source » et la « Durée du cache (secondes) », puis cliquez sur « Ajouter ».

À côté de chaque champ, l'aide « Comment obtenir « {champ} » » donne la requête à lancer dans la base pour retrouver l'adresse, le nom de service, le schéma ou pour créer un compte en lecture seule. La base est lue en direct, comme une base MongoDB. Il n'y a pas de réglage « TLS » : la connexion n'est pas chiffrée par Deltia, ce qui convient à une base atteinte par un tunnel VPN.

Si la base n'est pas joignable depuis Internet, un super-administrateur de la plateforme Deltia déclare d'abord un tunnel VPN pour l'organisation, dans l'onglet « Tunnels VPN ». Le champ « Accès réseau » apparaît alors dans le formulaire : « Direct (joignable depuis Internet) » ou le tunnel, puis la « Base de données du tunnel » parmi ses cibles. Les cibles du tunnel remplacent l'hôte et le port. Sans tunnel disponible, le formulaire indique : « Base privée ? Demandez à un super-administrateur Deltia de configurer un tunnel VPN pour cette organisation. »

Déclarer une API REST (JSON)

1. Dans l'onglet « Sources de données », cliquez sur « Ajouter une source ».
2. Choisissez « API REST (JSON) » comme « Type de source ».
3. Renseignez « Nom » et le « Jeton » : le jeton bearer ou la clé d'API, selon l'authentification déclarée. Il est stocké chiffré, jamais dans la définition.
4. Éditez la « Définition (JSON) » : adresse de base, authentification, en-têtes, variables et flux à synchroniser. Un exemple est prérempli : une API authentifiée par jeton, lue jour par jour et paginée par curseur.
5. Réglez « Synchroniser toutes les (heures) » et le « Scope des données », qui s'applique à chaque flux.
6. Choisissez les « Rôles autorisés à lire la source », puis cliquez sur « Ajouter ».

L'adresse de l'API doit être en HTTPS, publique et répondre en JSON : voir « Messages d'erreur d'une source API » en Référence.

Ranger les lignes dans un scope

Sous « Scope des données », deux modes existent pour une source API :

• « Un scope fixe » range toutes les lignes dans un scope choisi. Seuls ses membres les voient dans les graphiques.
• « Calculé par code » prend une fonction record => … qui renvoie l'identifiant d'un des scopes de l'organisation à partir de chaque ligne.

Une ligne dont le scope reste inconnu n'est visible par personne ; la ligne de statut de la source le signale : « {n} lignes sans scope, visibles par personne ». Si un flux désigne un scope qui n'existe pas, l'enregistrement est refusé : « Un flux de la source range ses lignes dans un scope qui n'existe pas dans l'organisation. »

Tester une connexion

1. Dans le formulaire de la source, ou sur la ligne de la liste, cliquez sur « Tester ».

« Connexion réussie (serveur {version}) » confirme que la source répond et qu'au moins une donnée est lisible. « Connexion réussie, mais aucune donnée lisible : vérifiez les droits de lecture de l'utilisateur. » signale une connexion qui fonctionne sans droit de lecture réel. Sinon, « Échec de la connexion : {raison} » précise la cause — voir « Causes d'échec » en Référence.

Synchroniser une source API

1. Sur la ligne de la source API, cliquez sur « Synchroniser ».

Les sources API se synchronisent aussi toutes seules, à l'intervalle réglé dans « Synchroniser toutes les (heures) » ; le bouton sert à ne pas attendre le passage suivant. Le résultat s'affiche : « Synchronisation effectuée. », « Cette source est déjà à jour. », « Synchronisation déjà en cours : elle se poursuit en arrière-plan. » ou « Synchronisation en échec : {raison} ».

Sous le nom de la source, une ligne résume l'état : « Import initial : {n} % » (avec « jusqu'au {date} » quand la tranche en cours est connue), « À jour · dernière synchro {date} », « Jamais synchronisée », « En erreur : {raison} » ou « État de la synchronisation indisponible ».

Quand l'API refuse certains comptes publicitaires (par exemple Meta qui répond par un refus pour un compte), la synchronisation continue pour les autres. Les lignes déjà importées pour les comptes refusés sont conservées sur la période relue, au lieu d'être supprimées. Tant qu'un compte reste refusé, les lignes que l'API ne renvoie plus pour les autres comptes restent aussi, jusqu'à une synchronisation sans refus. Une limite de débit annoncée par Meta est réessayée comme les autres limites ; si elle dure plus longtemps que les réessais, le flux est en échec et reprend à la synchronisation suivante.

Modifier ou supprimer une source de données

1. Sur l'onglet « Sources de données », cliquez sur l'icône de modification ou de suppression de la ligne voulue.
2. Pour la suppression, confirmez « Supprimer la source de données ? ».

En modification, le mot de passe d'une base MongoDB reste vide : « Laissez vide pour conserver le mot de passe enregistré. » Le saisir ne le remplace que si l'hôte, le port, l'utilisateur et la base d'authentification restent identiques ; changer l'un d'eux exige de ressaisir le mot de passe. De même, « Laissez vide pour conserver le jeton enregistré. » vaut pour une source API.

La suppression est définitive : « {nom} » sera supprimée et les graphiques qui la lisent cesseront de s'afficher. Pour une source API, la suppression emporte aussi toutes les lignes importées, et la recréer réimporte tout l'historique sur le quota de l'API.

Référence

Champs d'une base MongoDB

Réglages d'une source API

Les réglages propres aux sources publicitaires (début de l'import, jours relus, jours par passage, rapports) sont décrits dans Sources publicitaires.

Un flux contient 2 000 000 lignes au plus, et une organisation 5 000 000 lignes au total toutes sources API confondues. Quand un flux atteint sa limite, la synchronisation s'arrête avec « limite de lignes atteinte : avancez la date de début ou retirez le rapport ».

Statuts d'une source

La liste affiche aussi la date du « Dernier succès », ou « Jamais ».

Causes d'échec

Le message « Échec de la connexion : {raison} » et « Synchronisation en échec : {raison} » reprennent l'une des causes suivantes.

Messages d'erreur

Limites

Qui peut quoi

Le droit « Lire la source de données » se règle aussi depuis Rôles et droits, sous « Sources de données externes ».

Questions fréquentes

Un administrateur du module KPI voit-il toutes mes sources ? Non. Il ne voit que celles que ses rôles lui permettent de lire. Seuls les administrateurs du module Connecteurs lisent toutes les sources.

Où sont passées les sources de données dans l'administration KPI ? Elles se déclarent désormais dans l'administration des connecteurs. L'ancien onglet « Sources de données » de l'administration KPI s'appelle « Jeux de données » : il sert à adopter les collections et à les cartographier. Un ancien signet vers l'onglet de déclaration ouvre directement la page des connecteurs.

Deltia peut-il écrire dans ma base ou dans mon API ? Non, la lecture est seule en jeu.

Puis-je changer le type d'une source existante ? Non : créez une nouvelle source.