Last modified by Aurelie Bertrand on 2026/08/24 14:25
Show last authors
1 (% class="box infomessage" %)
2 (((
3 🙋 Ce tutoriel est à destination des **utilisateurs administrateurs de DigDash BI**.
4
5 ⏱ Il est prévu pour être suivi de manière autonome en **2 heures**.
6 )))
7
8 ----
9
10 {{toc/}}
11
12 ----
13
14 = Introduction =
15
16 Dans ce tutoriel, nous allons configurer une architecture complète (back-end et front-end) pour utiliser des flux (graphiques) DigDash en embarqué via la librairie Javascript.
17
18 Pour cela, nous allons mettre en œuvre un back-end léger en Python FastAPI. Ce composant permet de générer des jetons d'impersonnalisation (newAuthTokenAs) à l'aide d'une clé d'API, tout en masquant cette clé critique aux yeux des utilisateurs finaux (front-end). Il sera ensuite nécessaire de modifier notre reverse proxy. Puis, pour finir, nous allons créer une page HTML avec du Javascript pour faire appel à cette API.
19
20 = Architecture de la Solution =
21
22 Pour des raisons de sécurité, la clé d'API DigDash ne doit jamais transiter sur le navigateur du client. Le flux d'authentification s'organise donc ainsi :
23
24 * Le **Front-end **(Javascript) appelle une route sécurisée sur le serveur web (///generate-user-token//).
25 * **Nginx** relaie cette requête en local vers le serveur **FastAPI**.
26 * **FastAPI **interroge directement **DigDash **en injectant la clé d'API et les en-têtes requis, puis extrait le jeton.
27 * Le jeton est renvoyé à notre **Front-end** qui va pouvoir le consommer pour s’authentifier et afficher les flux (graphiques).
28
29 = Pré-requis =
30
31 Pour ce tutoriel et afin de pouvoir utiliser la méthode newAuthTokenAs il est nécessaire d’activer l’emprunt d’identité. Pour cela, nous vous invitons à suivre le paragraphe [[Avancé : Emprunt d’identité>>doc:Digdash.webIntegration.anonymisation_url.WebHome||anchor="emprunt"]] sur la page [[Anonymisation des Urls>>doc:Digdash.webIntegration.anonymisation_url.WebHome]].
32
33 Dans cet exemple d’implémentation, nous utilisons une clé d’API pour l’authentification de l’administrateur au prêt de DigDash. Il est donc nécessaire de créer une clé que l’on utilisera dans notre API back-end. Pour cela, nous vous invitons à suivre la procédure [[Créer une clé d'API>>doc:Digdash.API.DD_API.WebHome||anchor="API"]].
34
35 = Étape 1 : Configurer le Back-end =
36
37 (% class="box infomessage" %)
38 (((
39 **ℹ **Cette section décrit l'installation du serveur d'API sur une machine Ubuntu hébergeant déjà DigDash Enterprise.
40 )))
41
42 == Installation des pré-requis système ==
43
44 Connectez-vous à votre serveur en SSH et exécutez les commandes suivantes pour installer Python 3 et le gestionnaire d'environnement virtuel. Python sera la technologie socle pour notre back-end.
45
46 {{code language="shell"}}
47 # Mise à jour des dépôts système
48 sudo apt update
49
50 # Installation de Python 3, pip et le module venv
51 sudo apt install -y python3 python3-venv python3-pip
52 {{/code}}
53
54 == Initialisation de l'environnement applicatif ==
55
56 Créez et placez-vous dans le répertoire de votre choix (par exemple,// /var/www/embedded///) pour initialiser l'application :
57
58 {{code language="shell"}}
59 # Créer les dossiers de l'application à la racine
60 mkdir -p /var/www/embedded/
61
62 # Accéder au dossier
63 cd /var/www/embedded/
64
65 # Création de l'environnement virtuel Python
66 python3 -m venv venv
67
68 # Activation de l'environnement virtuel
69 source venv/bin/activate
70
71 # Installation des dépendances requises
72 pip install fastapi uvicorn httpx
73 {{/code}}
74
75 == Écriture du code source (main.py) ==
76
77 1. Créez un fichier nommé main.py dans le répertoire précédemment initialisé(((
78 {{code language="shell"}}
79 sudo vi main.py
80 {{/code}}
81 )))
82 1. Puis ajoutez-y le code suivant :(((
83 (% class="box warningmessage" %)
84 (((
85 ⚠ Modifiez la variable **//API_KEY //**et //**l'en-tête "DIGDASH_DOMAIN"**// avec vos propres paramètres.
86 )))
87
88 {{code language="python"}}
89 from fastapi import FastAPI, HTTPException
90 import httpx
91
92 app = FastAPI(title="DigDash Token API")
93
94 # Configuration locale : FastAPI communique directement avec Tomcat sur le port 8080
95 DIGDASH_LOCAL_URL = "http://127.0.0.1:8080"
96
97 # CONFIGURATION A COMPLETER
98 API_KEY = "<VOTRE_CLE_API_DIGDASH>"
99 DIGDASH_DOMAIN = "<VOTRE_DOMAINE_PUBLIC_EX_client.digdash.com>"
100
101 @app.get("/generate-user-token")
102 async def generate_user_token(target_user: str):
103 """
104 Génère un jeton d'authentification pour un utilisateur cible (newAuthTokenAs).
105 """
106 # Construction explicite de l'URL pour DigDash
107 url = f"{DIGDASH_LOCAL_URL}/ddenterpriseapi/DDEnterpriseServlet?method=newAuthTokenAs&userId={target_user}"
108
109 # En-têtes requis pour identifier l'environnement DigDash et communiquer l'API Key
110 headers = {
111 "X-API-KEY": API_KEY,
112 "Accept": "application/json",
113 "Host": DIGDASH_DOMAIN
114 }
115
116 async with httpx.AsyncClient() as client:
117 try:
118 response = await client.get(url, headers=headers)
119
120 # Si Tomcat renvoie une erreur (401, 404, 500, etc.)
121 if response.status_code != 200:
122 raise HTTPException(
123 status_code=response.status_code,
124 detail=f"Erreur DigDash Backend: {response.text}"
125 )
126
127 # La servlet renvoie le token que l'on transfert au front-end
128 raw_token = response.text
129 return {"token": raw_token}
130
131 except httpx.RequestError as exc:
132 raise HTTPException(
133 status_code=500,
134 detail=f"Erreur de communication interne avec Tomcat: {str(exc)}"
135 )
136
137 if __name__ == "__main__":
138 import uvicorn
139 # Lancement du serveur en local sur le port 8000
140 uvicorn.run(app, host="127.0.0.1", port=8000)
141 {{/code}}
142
143 (% class="box infomessage" %)
144 (((
145 💡 Pour une industrialisation, il est recommandé d’utiliser des fichiers “.env” pour ne pas avoir la clé codée directement dans le fichier python.
146 La mise en place de logs est également fortement recommandée pour tracer les usages de l’API et débugger.
147 )))
148 )))
149
150 == Démarrage du service ==
151
152 Pour tester le fonctionnement, vous pouvez lancer le processus via **uvicorn**. Cela va monopoliser votre terminal, il sera nécessaire d’en ouvrir un nouveau pour les prochaines étapes.
153
154 {{code language="shell"}}
155 # Lancement de l'application (assurez-vous que le venv est actif)
156 uvicorn main:app --host 127.0.0.1 --port 8000 --reload
157 {{/code}}
158
159 (% style="line-height:1.2; text-indent:0.15354330708661657pt; text-align:justify" %)
160 Si cette commande se déroule bien, vous devriez voir apparaître le message suivant :
161
162 (% style="line-height:1.2; text-align:justify; margin-top:16px" %)
163 (% style="color:#188038; font-family:~"Roboto Mono~",monospace; font-size:9pt; font-style:italic; font-variant:normal; font-weight:400; text-decoration:none; white-space:pre-wrap" %)//INFO: Application startup complete.//
164
165 (% class="box infomessage" %)
166 (((
167 💡 Pour une mise en production pérenne, il est recommandé de packager cette commande et de créer un service lancé au démarrage de votre serveur.
168 )))
169
170 == Test de fonctionnement ==
171
172 Afin de valider le fonctionnement de notre back-end, il est possible de réaliser un curl en local sur notre serveur DigDash.
173
174 (% class="box warningmessage" %)
175 (((
176 ⚠ Modifiez la variable**// target_user//** avec votre propre utilisateur de test.
177 )))
178
179 (((
180 {{code}}
181 curl -X GET "http://127.0.0.1:8000/generate-user-token?target_user=username" -H "accept: application/json"
182 {{/code}}
183
184 Si vous obtenez un message //**“Connection refused**”//, cela signifie que votre back-end ne répond pas et qu'une une étape précédente n’a pas fonctionné correctement.
185 Si vous obtenez n’importe quelle autre réponse ressemblant à **//{“token”:”xxx”}//**, alors DigDash a bien apporté une réponse et vous pouvez passer aux étapes suivantes.
186 )))
187
188 = Étape 2 : Configuration du Front-end =
189
190 Pour notre architecture côté client, nous allons créer un fichier index.html dans notre répertoire ///var/www/embedded///. L’appel à l'API se fait de manière transparente via l’utilisation de// fetch//.
191
192 1. Créez un fichier **index.html.**(((
193 {{code language="shell"}}
194 sudo vi index.html
195 {{/code}}
196 )))
197 1. (((
198 Puis ajoutez-y le code HTML/CSS/JavaScript suivant :
199
200 (((
201 (% class="box warningmessage" %)
202 (((
203 ⚠ Modifiez la variable **//myUser//** et les identifiants de flux (ici //**c74b5ca3**// et **//ee54be60//**) avec vos propres paramètres.
204 )))
205 )))
206
207 (((
208 {{code language="html"}}
209 <!DOCTYPE html>
210 <html lang="fr">
211 <head>
212 <meta charset="UTF-8">
213 <title>Dashboard Embarqué</title>
214 <script src="/digdash_dashboard/digdash.dashboard.js"></script>
215 <style>
216 .dashboard-container { display: flex; flex-wrap: wrap; gap: 20px; padding: 20px; }
217 .chart-box { border: 1px solid #ccc; width: 45%; height: 400px; background: #f9f9f9; }
218 </style>
219 </head>
220 <body>
221 <div class="dashboard-container">
222 <div id="chart-1" class="chart-box"></div>
223 <div id="chart-2" class="chart-box"></div>
224 </div>
225
226 <script>
227 // Fonction d'initialisation de DigDash
228 async function init() {
229 const myUser = 'Utilisateur1';
230 const response = await fetch('/generate-user-token?target_user='+myUser, {
231 method: 'GET'
232 });
233
234 if (!response.ok) throw new Error("Erreur lors de la récupération du token");
235
236 const data = await response.json();
237 const authToken = data.token;
238 console.log("Token récupéré avec succès :", authToken);
239
240 console.log("Parent: Initialisation de DigDash...");
241 DigDash.init({
242 "url": "/digdash_dashboard", // Utilisation du chemin relatif via Nginx
243 "user": myUser,
244 "authToken": authToken
245 });
246 }
247
248 function renderChildChart(containerId, flowId) {
249 console.log(`Enfant [${containerId}]: Attente de l'initialisation...`);
250 // Fonction permettant d'attendre l'initialisation de DigDash
251 function waitForInit(callback) {
252 if (DigDash.parameters && DigDash.parameters.size > 0) {
253 callback();
254 } else {
255 setTimeout(() => waitForInit(callback), 100);
256 }
257 }
258
259 waitForInit(() => {
260 console.log(`Enfant [${containerId}]: Dessin du flux ${flowId}`);
261 DigDash.drawPortlet(containerId, {
262 "type": "flow",
263 "flowId": flowId
264 })
265 });
266 }
267
268 init();
269
270 renderChildChart("chart-1", "c74b5ca3");
271 renderChildChart("chart-2", "ee54be60");
272 </script>
273 </body>
274 </html>
275 {{/code}}
276 )))
277 )))
278
279 (% class="box infomessage" %)
280 (((
281 💡 À partir du moment où la connexion à DigDash a été établie, il est possible d’utiliser les fonctions présentes dans DDCtrl.
282 )))
283
284 = Étape 3 : Configuration Nginx =
285
286 (% class="box infomessage" %)
287 (((
288 **ℹ** Dans cette section, nous décrivons la procédure d’ouverture de notre API pour un serveur Nginx déjà installé en suivant la documentation d’installation DigDash.
289 )))
290
291 Pour rendre cette API et ce site accessible depuis l'extérieur sans ouvrir de port supplémentaire sur votre pare-feu, vous devez ajouter deux règles de routage dans votre fichier de configuration Nginx existant.
292
293 1. Ouvrez votre fichier de configuration Nginx (généralement ///etc/nginx/sites-available/001-digdash.com.conf//) : (((
294 {{code language="shell"}}
295 sudo vi /etc/nginx/sites-available/001-digdash.com.conf
296 {{/code}}
297 )))
298 1. Localisez le bloc **server** qui écoute sur le port **443 ssl**.
299 1. Insérez les deux directives **location** suivante à l'intérieur de ce bloc et à la suite des autres location :(((
300 {{code language="shell"}}
301 # Routage vers le proxy d'authentification FastAPI
302 location /generate-user-token {
303 proxy_pass http://127.0.0.1:8000;
304 include proxy_params;
305
306 # Désactivation impérative de l'interception des erreurs Nginx
307 # pour laisser FastAPI transmettre ses messages d'erreur propres au client
308 proxy_intercept_errors off;
309 }
310
311 # Routage vers notre index.html
312 location /embedded/ {
313 alias /var/www/embedded/;
314 index index.html;
315 try_files $uri $uri/ =404;
316 }
317 {{/code}}
318 )))
319 1. Testez la syntaxe de la configuration et rechargez Nginx : (((
320 {{code language="shell"}}
321 # Vérification de la configuration Nginx
322 sudo nginx -t
323
324 # Si le test est positif, rechargement à chaud de la configuration
325 sudo systemctl reload nginx
326 {{/code}}
327 )))
328
329 = Étape 4 : Test de fonctionnement =
330
331 Pour finir ce tutoriel, vous pouvez tester l'accès à votre page web via l’url suivante :
332
333 [[https:~~/~~/VOTRE_DOMAINE.digdash.com/embedded/index.html>>https://VOTRE_DOMAINE.digdash.com/embedded/index.html]]
334
335 La page affichée doit contenir deux flux (graphiques) côte à côte, par exemple :
336
337 [[image:Flow_embed_result_fr.png||alt="Flux embarqués"]]
338
339
340 (% class="box infomessage" %)
341 (((
342 **ℹ** Dans la console du navigateur, quelques logs apparaissent pour aider au développement et au débug. Pour un usage en production, la suppression de ces éléments est recommandée.
343 )))
344
345 = Félicitations ! =
346
347 Vous avez réussi à mettre en place vos premiers graphiques DigDash en mode embarqué.
348 Il ne vous reste plus qu’à appliquer ce principe aux graphiques que vous souhaitez intégrer à vos pages web !
349
350