Intégrer Looker avec Conversational Analytics

1. Avant de commencer

Cet atelier de programmation vous guidera dans l'intégration d'un tableau de bord Looker intégré avec le chat Conversational Analytics pour créer une expérience de données unifiée basée sur le langage naturel. Pour en tirer le meilleur parti, vous devez maîtriser l'intégration Looker, l'analyse conversationnelle, JavaScript et React.

Points abordés

Après avoir suivi cet atelier de programmation, vous aurez appris les points suivants :

• Configurer l'application Looker Embed Reference en local
• Créer un composant React de chat avec la bibliothèque Looker Components
• Envoyer le filtre du tableau de bord intégré en tant que contexte à Conversational Analytics
• Activer le chat optimisé par l'analyse conversationnelle pour contrôler les filtres de votre tableau de bord intégré

Prérequis

Voici les conditions à réunir pour effectuer cet atelier de programmation :

• Une instance Looker avec le bloc Looker ASC Demographic Data installé et l'intégration SSO activée
• Accès aux API et aux développeurs à votre instance Looker
• Un environnement local avec Node v18, yarn, Git et gcloud installés
• Un projet cloud avec les rôles IAM suivants configurés pour votre compte utilisateur :
• roles/bigquery.dataViewer Lecteur de données BigQuery
• roles/bigquery.user Utilisateur BigQuery
• roles/looker.instanceUser Utilisateur d'instance Looker

2. Configurer Conversational Analytics

Configurons l'agent de données Conversational Analytics que le chat de votre tableau de bord intégré utilisera pour répondre aux questions en langage naturel.

S'authentifier avec gcloud

1. Authentifiez-vous avec votre compte utilisateur dans votre environnement local :

gcloud auth login

2. Définissez les identifiants par défaut de l'application (ADC) et le projet de facturation sur votre gcloud :

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Activer les API Conversational Analytics

3. Activez les API du projet Cloud. Veuillez remplacer YOUR_PROJECT_ID par l'ID de votre projet Google Cloud :

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Créer l'agent de données

4. Ouvrez Google Colab.
5. Dans Google Colab, chargez ce notebook à partir du dépôt de référence Looker Embed.
6. Exécutez toutes les étapes du notebook. Vous aurez besoin de l'ID de votre projet Cloud et de l'URI de votre instance Looker avec une barre oblique à la fin, comme "https://my.looker.app/". Vous devriez obtenir un résultat positif à la fin du notebook.

Vous disposez désormais d'un agent de données Conversational Analytics qui est prêt à accepter les messages de chat, à interroger les explorations Looker dans votre tableau de bord Looker intégré et à renvoyer des résultats et des visualisations.

3. Configurer la référence d'intégration Looker

Configurons l'application Looker Embed Reference dans votre environnement local afin que vous puissiez essayer l'exemple d'intégration du chat Conversational Analytics à un tableau de bord Looker intégré.

Cloner le dépôt

1. Clonez le dépôt GitHub dans votre environnement local. Consultez l'exemple de commande ci-dessous :

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Accédez au répertoire LookerEmbedReference que vous avez cloné :

cd LookerEmbedReference

Configurer et exécuter le serveur frontend local

3. Installez les dépendances dans le répertoire Frontend.

cd Frontend
yarn install

4. Configurez un fichier .env dans la racine du répertoire Frontend avec les identifiants. YOUR_LOOKER_INSTANCE_URI doit correspondre à l'URI de votre instance Looker, sans barre oblique à la fin. Le contenu du fichier doit être le suivant :

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

Vous pouvez utiliser l'exemple de commande suivant pour créer le fichier :

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Exécutez le serveur de développement frontend :

yarn run dev

Configurer et exécuter le serveur de backend localement

6. Ouvrez un nouvel shell, terminal, console ou onglet. Accédez au répertoire Backend-Node et installez les dépendances. Assurez-vous de laisser l'ancien shell/terminal avec le serveur frontend en cours d'exécution.

cd ../Backend-Node
yarn install

7. Configurez un fichier .env dans la racine du répertoire Backend-Node avec des identifiants :

• YOUR_LOOKER_CLIENT_ID est votre ID client Looker.
• YOUR_LOOKER_CLIENT_SECRET est votre code secret du client Looker.
• YOUR_LOOKER_EMBED_SECRET est votre code secret d'intégration.
• YOUR_PROJECT_ID est votre ID de projet cloud.
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH est l'URI de votre instance Looker avec une barre oblique à la fin.
• YOUR_LOOKER_INSTANCE_URI est l'URI de votre instance Looker sans barre oblique à la fin.

Le contenu du fichier doit être le suivant :

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

Vous pouvez utiliser l'exemple de commande suivant pour créer le fichier. Remplacez tous les identifiants en conséquence :

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Exécutez le serveur de développement backend :

yarn run dev

Le serveur de développement frontal est maintenant en cours d'exécution et fournit le code JavaScript pour l'application Web. Le serveur de développement de backend est également en cours d'exécution pour gérer les requêtes d'URL d'intégration de l'authentification unique et les requêtes de proxy vers les points de terminaison Conversational Analytics.

4. Essayer l'exemple

Essayons votre application Web qui s'exécute désormais localement dans votre environnement.

Démarrer une conversation

1. Ouvrez l'adresse https://localhost:3001 dans le navigateur de votre choix.
2. Accédez à la page Tableau de bord intégré avec chat dans le menu de navigation principal de gauche.
3. Une fois le composant de chat chargé sur la droite, saisissez "Bonjour, qui êtes-vous ?".
4. Notez la réponse.

L'application a automatiquement créé un objet conversation Conversational Analytics pour suivre l'historique du chat et a chargé l'interface de chat. Lorsque vous avez posé une question à l'interface de chat, le frontend a envoyé un message utilisateur à votre serveur backend Node local. Il a ensuite transféré la requête et la réponse au point de terminaison chat de Conversational Analytics.

Filtrer le tableau de bord intégré

Familiarisez-vous maintenant avec le tableau de bord intégré et interagissez avec lui.

5. Faites défiler le tableau de bord intégré. Notez qu'il couvre les données de recensement pour plusieurs dimensions et métriques.
6. Vous pouvez filtrer le tableau de bord par État et Comté en haut à gauche. Définissez le filtre du tableau de bord sur Texas. Sélectionnez ensuite le bouton en forme de flèche circulaire en surbrillance bleue pour exécuter à nouveau le tableau de bord.
7. Notez que toutes les données de visualisation sont filtrées sur l'état du Texas.

Poser une question avec le contexte du tableau de bord

Maintenant que nous avons filtré le tableau de bord, continuons à examiner les données qu'il contient.

8. Saisissez "Dis-moi les cinq comtés où les loyers sont les moins chers" dans le chat.
9. Notez que votre requête à Conversational Analytics contient désormais les mots supplémentaires "Filtrer sur la dimension 'state.state_name' étant Texas".
10. Notez que la requête et les données de la réponse sont filtrées sur l'état Texas.
11. De plus, une fois les résultats des données renvoyés, votre tableau de bord intégré a été réexécuté avec son filtre Comté défini sur les cinq comtés définis dans les données du résultat.

Vous pouvez maintenant continuer à examiner les données du recensement, les cinq comtés étant filtrés pour vous.

Félicitations ! Vous avez configuré et testé un exemple simple de tableau de bord intégré à un chat Conversational Analytics.

5. Créer un composant de chat

Pour comprendre ce qui se passe en arrière-plan, commençons par explorer le composant Chat. Nous partons du principe que vous savez comment intégrer un tableau de bord Looker avec le SDK d'intégration Looker.

Utiliser la bibliothèque de composants Looker

1. Ouvrez le fichier du composant Chat à l'adresse Frontend/src/components/EmbedChat/components/chat.js dans votre IDE ou votre terminal préféré.
2. Le composant Chat est conçu avec des composants React de l'UI Looker standards du package Bibliothèque de composants Looker.

La bibliothèque de composants Looker permet d'intégrer facilement le contenu Looker à votre application en fournissant des composants React prédéfinis qui s'alignent sur les styles et les composants d'un tableau de bord Looker intégré.

Envoyer un message à un utilisateur

L'interface de chat doit envoyer la requête d'un utilisateur à Conversational Analytics.

3. Près du bas du fichier de composant Chat, le composant Chat contient le sous-composant ChatInput, qui fournit le champ de saisie pour la requête d'un utilisateur.
4. Lors de l'envoi, la méthode showAndSendUserPrompt envoie la requête de l'utilisateur à Conversational Analytics (par proxy via votre backend Node).

Diffuser et afficher les messages système

Une fois que l'utilisateur a envoyé un message à Conversational Analytics, nous devons afficher sa réponse.

5. Près du bas du fichier de composant Chat, le composant Chat contient le sous-composant MessageList, qui contient la logique permettant d'afficher les messages de Conversational Analytics en fonction de leur type.
6. La méthode streamAndParseResponse gère la réponse en essayant constamment d'analyser les messages système valides à partir de la réponse JSON en streaming. Chaque fois qu'un message système valide est analysé avec succès, il s'affiche dans MessageList.

Pour une expérience utilisateur plus réactive, nous vous recommandons vivement d'afficher les messages système de Conversational Analytics dès qu'ils arrivent.

La réponse de l'analyse conversationnelle à une requête utilisateur se compose de plusieurs messages système, qui couvrent les sources de données interrogées, la requête, les résultats, les visualisations et plus encore. Si l'utilisateur doit attendre que tous les messages système arrivent, il peut penser qu'il y a des problèmes de performances ou d'application.

Vous avez maintenant découvert comment le composant Chat, créé avec la bibliothèque Looker Components, envoie un message utilisateur et renvoie la réponse en streaming.

6. Envoyer des filtres de tableau de bord à Conversational Analytics

Voyons maintenant comment inclure les filtres de tableau de bord dans la requête d'un utilisateur afin que l'analyse conversationnelle puisse filtrer sa requête avec le contexte du tableau de bord (ses filtres).

Écouter l'événement de modification du filtre du tableau de bord

1. Ouvrez le fichier du composant EmbedChat à l'adresse Frontend/src/components/EmbedChat/EmbedChat.js,, qui représente la page de l'application contenant le tableau de bord intégré au composant Chat exploré précédemment.
2. Le composant EmbedChat écoute l'événement "dashboard:filters:changed" du tableau de bord intégré avec la méthode .on(...) du SDK d'intégration. Le composant stocke ensuite les filtres actuels dans son état de filtre.

Envoyer l'état du filtre à Conversational Analytics

3. Le composant EmbedChat transmet les filtres au composant Chat, qui convertit chaque filtre en chaîne de type "Filter on dimension '...' being ..." dans la méthode showAndSendUserPrompt à ajouter à la fin de la requête de l'utilisateur.

Le nom ou la clé du filtre d'un tableau de bord ne sont pas nécessairement identiques au nom de la dimension réelle. Vous devez mapper la clé du filtre au nom réel de la dimension pour que Conversational Analytics comprenne les dimensions à filtrer.

Dans ce cas, par exemple dans le composant Chat, son objet FIELD_FILTER_MAP mappe le nom de la dimension "state.state_name" à la clé du filtre "State 📍". La méthode showAndSendUserPrompt utilise ensuite la carte pour déterminer le nom de la dimension sur laquelle filtrer.

7. Contrôler les filtres du tableau de bord depuis le chat

Enfin, voyons comment activer le composant Chat pour contrôler les filtres du tableau de bord intégré.

Déterminer les filtres à définir

1. La méthode streamAndParseResponse du composant Chat recherche toujours un message système contenant les résultats des données de l'analyse conversationnelle.
2. Chaque fois que la méthode streamAndParseResponse analyse un message système avec des résultats de données, elle vérifie si des dimensions dans les données correspondent aux dimensions dans les filtres.
3. Si c'est le cas, la méthode streamAndParseResponse convertit les colonnes de données en filtres de tableau de bord. Cette fois, la méthode utilise à nouveau FIELD_FILTER_MAP, mais en sens inverse, en convertissant le nom de la dimension en clé du filtre. Les valeurs du filtre sont celles de la colonne de données.

Envoyer un événement de modification de filtre au tableau de bord intégré

4. Avec les filtres de tableau de bord souhaités, la méthode streamAndParseResponse appelle la méthode setFilters du composant Chat avec les filtres souhaités.
5. Cela appelle la méthode setDashboardFilters du composant EmbedChat, qui envoie deux événements, "dashboard:filters:update" avec les filtres et "dashboard:run" au tableau de bord intégré en succession immédiate à l'aide de la méthode send du SDK Embed.
6. L'événement "dashboard:filters:update" modifie les filtres du tableau de bord intégré, tandis que l'événement "dashboard:run" réexécute les requêtes du tableau de bord avec les nouveaux filtres.

Vous devez envoyer "dashboard:run" après l'événement "dashboard:filters:update". L'événement "dashboard:filters:update" n'exécute pas automatiquement les requêtes du tableau de bord.

8. Conclusion et points à retenir

Vous avez configuré votre propre exemple de tableau de bord Looker intégré à la fonctionnalité de chat Conversational Analytics. Vous avez appris à activer l'exploration des données basée sur le langage naturel avec votre tableau de bord Looker intégré et Conversational Analytics.

• Vous avez créé un composant de chat avec la bibliothèque de composants Looker.
• Vous avez transmis le contexte de votre tableau de bord Looker intégré à Conversational Analytics pour faciliter l'exploration des données.
• Vous avez activé Conversational Analytics pour contrôler les filtres de votre tableau de bord intégré et ainsi obtenir plus de contexte lorsque vous explorez les données.

Étape suivante

• En savoir plus sur les fonctionnalités de Conversational Analytics
• Mettez à jour l'exemple d'application Looker Embed Reference pour qu'il fonctionne avec vos propres tableaux de bord Looker intégrés.
• Essayez les autres cas d'utilisation d'intégration disponibles dans l'exemple d'application Looker Embed Reference que vous exécutez en local.