Résoudre les problèmes liés au framework d'extension Looker

Le framework d'extension Looker vous permet de créer des applications et des visualisations JavaScript et TypeScript personnalisées qui s'exécutent dans Looker. Les extensions s'exécutent dans un iframe en bac à sable et interagissent avec votre instance Looker via le SDK d'extension. Si vous rencontrez des problèmes avec une extension personnalisée (par exemple, une page vide ou un message d'erreur dans l'iframe, des erreurs JavaScript ou CORS (Cross-Origin Resource Sharing) dans la console du navigateur, des requêtes d'API Looker ayant échoué (codes d'état 4xx ou 5xx) ou des erreurs de configuration manifest.lkml), ce document vous aide à les résoudre.

Prérequis et exigences de configuration courantes

Avant de commencer à résoudre les problèmes, vérifiez que votre environnement, votre projet LookML et votre compte utilisateur répondent aux exigences d'exécution d'une extension Looker :

  • Framework d'extension activé : un administrateur Looker doit activer le paramètre Framework d'extension sous Admin > Plate-forme > Framework d'extension.
  • Configuration du projet et du modèle LookML : chaque extension nécessite un projet LookML qui inclut les composants suivants :
  • Droits d'accès du fichier manifeste : la déclaration application dans le fichier manifest.lkml doit définir explicitement tous les entitlements dont l'extension a besoin, par exemple core_api_methods pour les appels d'API Looker ou external_api_urls pour les requêtes adressées à des domaines externes. Une extension ne s'exécutera pas sans bloc entitlements.
  • Autorisations utilisateur : les utilisateurs doivent disposer d'autorisations d'extension (telles que access_data, explore ou develop) pour un ensemble de modèles incluant le modèle LookML de l'extension. Pour créer une extension, les développeurs ont besoin des autorisations LookML develop.
  • Outils de diagnostic et détails de l'environnement : préparez les informations et outils suivants avant de commencer le dépannage :
    • L'URL de votre instance Looker, le nom du projet LookML et le nom application déclaré dans manifest.lkml.
    • Accès aux outils pour les développeurs de votre navigateur Web (onglets Console et Réseau) sur l'ordinateur client.
    • Pendant le développement local, l'accès au terminal qui exécute votre serveur de développement local.
    • Pour les erreurs de serveur 5xx sur les appels d'API Looker, l'accès aux journaux d'instance Looker (looker.log sur les instances hébergées par le client, ou l'explorateur de journaux dans Cloud Logging dans la console Google Cloud pour les instances Looker (Google Cloud Core)).

Arborescence de débogage

Utilisez l'arbre de décision suivant pour commencer à résoudre les problèmes liés au framework d'extension Looker :

Les sections suivantes décrivent plus en détail les scénarios de l'arborescence.

Inspecter les journaux de la console et du réseau du navigateur

Étant donné que les extensions Looker s'exécutent côté client dans votre navigateur, commencez par inspecter les outils pour les développeurs de votre navigateur pour détecter les erreurs JavaScript, les non-respects des règles de sécurité et les échecs de requêtes HTTP.

Rechercher les erreurs dans la console du navigateur

Pour identifier les erreurs côté client qui empêchent le chargement ou l'exécution de l'extension :

  1. Dans Looker, ouvrez la page où l'extension se charge.
  2. Effectuez un clic droit sur la page, puis sélectionnez Inspecter (ou appuyez sur Ctrl+Maj+I sous Windows et Linux, ou sur Cmd+Option+I sous macOS).
  3. Dans le panneau des outils pour les développeurs, sélectionnez l'onglet Console.
  4. Actualisez la page pour capturer les erreurs qui se produisent lors du chargement initial.
  5. Inspectez les messages d'erreur en rouge dans la console :

Inspecter l'onglet "Réseau" pour détecter les requêtes ayant échoué

Pour analyser les requêtes HTTP effectuées par l'extension pour les bundles JavaScript, les éléments ou les points de terminaison d'API, procédez comme suit :

  1. Dans le panneau des outils pour les développeurs du navigateur, sélectionnez l'onglet Réseau.
  2. Cochez la case Désactiver le cache pour que le navigateur ne charge pas de ressources obsolètes mises en cache.
  3. Actualisez la page sur laquelle l'extension se charge.
  4. Consultez la liste des requêtes réseau pour identifier les codes d'état 4xx ou 5xx, puis sélectionnez une requête ayant échoué pour inspecter ses onglets En-têtes, Charge utile et Réponse :
    • 404 sur le bundle d'extension (par exemple, bundle.js) : vérifiez que le serveur de développement est en cours d'exécution et que le paramètre url ou file dans manifest.lkml est correct.
    • 401 ou 403 sur une requête API Looker : examinez l'authentification, les autorisations et les droits d'accès.
    • 400 ou 422 sur une requête API : inspectez les onglets Charge utile et Réponse pour identifier un JSON incorrect ou des paramètres de requête non valides.
    • 5xx erreurs de serveur : indiquent des erreurs côté serveur sur l'instance Looker. Vérifiez looker.log sur les instances hébergées par le client ou l'explorateur de journaux dans la console pour les instances Looker (Google Cloud Core) afin de trouver les entrées avec des codes temporels correspondants.

Si aucune erreur n'apparaît dans les onglets Console ou Réseau, ou si vous devez vérifier comment Looker charge l'extension, passez à la section suivante.

Vérifier le fichier manifeste et la configuration du projet

La déclaration application dans le fichier manifest.lkml de votre projet contrôle la façon dont Looker charge l'extension et les ressources qu'elle peut utiliser. Les erreurs de configuration dans manifest.lkml sont une cause courante d'échecs de chargement et d'API :

  • Vérifiez le paramètre url ou file : dans l'IDE Looker, ouvrez le fichier manifest.lkml de votre projet et inspectez la déclaration application :
    • Une déclaration application doit inclure un paramètre url ou un paramètre file, mais pas les deux.
    • Pendant le développement local : vérifiez que le paramètre url correspond exactement au protocole (http ou https), au nom d'hôte, au port et au chemin d'accès diffusés par votre serveur de développement local (par exemple, https://localhost:8080/bundle.js).
    • En production : vérifiez que vous avez remplacé la déclaration application du chemin de développement local url par le chemin de production file dans votre projet LookML (par exemple, file: "apps/bundle.js") ou l'URL du bundle de production.
  • Vérifiez les droits d'accès manifest.lkml : examinez le bloc entitlements dans votre déclaration application. Une extension ne peut pas utiliser une ressource Looker ou un domaine externe, sauf si ce droit est explicitement déclaré, comme suit :
    • core_api_methods: : doit lister toutes les méthodes de l'API Looker appelées par votre extension (par exemple, core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls : doit lister tous les domaines externes non Looker que l'extension demande directement ou via le proxy.
    • Droits supplémentaires : vérifiez si votre extension nécessite local_storage, navigation, new_window, new_window_external_urls, use_form_submit, use_embeds, use_downloads, use_iframes, use_clipboard, oauth2_urls, global_user_attributes ou scoped_user_attributes.
  • Validez, validez et déployez : après avoir modifié manifest.lkml, cliquez sur Valider le LookML, validez vos modifications, puis cliquez sur Déployer en production pour que la configuration mise à jour prenne effet.

Résoudre les problèmes liés au serveur et à l'environnement de développement local

Lorsque vous développez une extension localement à l'aide du paramètre url dans manifest.lkml, votre serveur de développement local doit être en cours d'exécution et accessible depuis votre navigateur :

  • Vérifiez que le serveur de développement est en cours d'exécution : vérifiez la fenêtre de terminal dans laquelle vous avez démarré le serveur de développement (par exemple, à l'aide de yarn develop ou npm start) :
    • Vérifiez que la compilation s'est effectuée sans erreur et qu'un message d'écoute s'affiche (par exemple, webpack compiled successfully ou listening on localhost:8080).
    • Si le serveur n'est pas en cours d'exécution, démarrez-le avec yarn develop ou npm start.
    • Si le serveur s'est arrêté avec une erreur de syntaxe ou une erreur de dépendance manquante, corrigez l'erreur de code ou exécutez yarn install (ou npm install) pour installer les packages manquants.
    • Si le serveur échoue en raison d'un conflit de port (EADDRINUSE), arrêtez l'autre processus qui utilise ce port, ou configurez votre serveur de développement et le paramètre manifest.lkml url pour utiliser un autre port.
  • Ouvrez l'URL de l'extension directement dans votre navigateur : copiez la valeur url de manifest.lkml (par exemple, https://localhost:8080/bundle.js) et ouvrez-la dans un nouvel onglet du navigateur :
    • Certificat SSL autosigné non fiable : les serveurs de développement locaux utilisent fréquemment des certificats SSL autosignés. Si votre navigateur affiche un avertissement de sécurité concernant le certificat, sélectionnez Avancé et accédez à localhost pour approuver le certificat pour votre session de navigateur. Tant que le certificat n'est pas approuvé, le navigateur empêche le chargement du bundle dans l'iframe Looker.
    • Connexion refusée ou bloquée : si le navigateur ne parvient pas à accéder à l'URL, vérifiez qu'aucun pare-feu local ou logiciel de sécurité des points de terminaison ne bloque les connexions à localhost sur le port configuré.

Résoudre les problèmes de mise en réseau, de CORS et de règles de sécurité

Les navigateurs Web appliquent la règle d'origine identique, qui empêche Looker de charger des ressources d'extension ou d'appeler des serveurs externes d'une autre origine, sauf si les en-têtes et les règles de sécurité CORS (Cross-Origin Resource Sharing) sont configurés :

  • Identifiez les erreurs CORS dans la console du navigateur : recherchez les messages d'erreur dans l'onglet Console contenant Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy ou des en-têtes Access-Control-Allow-Origin manquants.
  • Configurez les en-têtes CORS du serveur de développement local : si vous utilisez webpack-dev-server (ou un bundler similaire), assurez-vous que la configuration devServer dans webpack.config.js inclut l'en-tête Access-Control-Allow-Origin : javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • Configurez l'hébergement de production et les en-têtes CORS d'API externes : si votre extension charge des éléments ou demande des données à partir d'un service externe (tel que Cloud Storage, Amazon S3 ou un serveur backend personnalisé), configurez le service d'hébergement pour qu'il renvoie l'en-tête Access-Control-Allow-Origin qui autorise le domaine de votre instance Looker. Vérifiez également qu'aucun proxy réseau ni pare-feu ne supprime les en-têtes CORS de la réponse, et assurez-vous que le domaine externe est listé dans external_api_urls dans manifest.lkml.
  • Vérifiez la Content Security Policy (CSP) et le chargement amélioré des extensions : si vous rencontrez des violations de la CSP lors du chargement d'une extension, vérifiez le paramètre Chargement amélioré des extensions sous Admin > Plate-forme > Extension Framework.

Résoudre les problèmes d'authentification et d'accès à l'API

Les extensions interagissent avec l'API Looker au nom de l'utilisateur connecté via le SDK d'extension. Si les appels d'API échouent avec les codes d'état 401 Unauthorized ou 403 Forbidden dans l'onglet Réseau, vérifiez les points suivants :

  • Distinguez les erreurs 401 et 403 :
    • 401 Unauthorized : la requête n'a pas été authentifiée. Cette erreur se produit généralement si le SDK d'extension n'a pas été initialisé correctement ou si l'extension a tenté d'appeler l'API avant que le SDK n'ait terminé son handshake d'authentification.
    • 403 Forbidden : la requête a été authentifiée, mais l'utilisateur connecté ne dispose pas des autorisations Looker requises ou le fichier manifest.lkml de l'extension n'inclut pas la méthode appelée dans core_api_methods.
  • Vérifiez les rôles et les autorisations des utilisateurs : dans Admin > Utilisateurs et Admin > Rôles, vérifiez les rôles, les ensembles d'autorisations et les ensembles de modèles attribués à l'utilisateur connecté :
    • Vérifiez que l'utilisateur dispose des autorisations nécessaires pour utiliser l'extension, y compris access_data (et explore ou develop, selon les besoins) pour un ensemble de modèles contenant le modèle LookML de l'extension et tous les modèles interrogés par l'extension.
    • Vérifiez que le rôle de l'utilisateur inclut les autorisations spécifiques requises par chaque point de terminaison de l'API Looker appelé par l'extension.
  • Assurez-vous que le contexte du SDK est prêt avant d'appeler l'API : vérifiez que le code de votre extension attend l'initialisation du contexte du SDK d'extension avant d'appeler les méthodes de l'API.

Résoudre les problèmes liés au SDK d'extension et aux dépendances

Des problèmes d'installation de packages npm ou Yarn, ou des composants de fournisseur du SDK manquants peuvent empêcher une extension de compiler ou de se connecter à Looker :

  • Vérifiez l'installation du module Node.js : dans votre terminal, accédez au répertoire racine de votre projet d'extension et vérifiez le répertoire node_modules :
    1. Si node_modules est manquant ou si les dépendances semblent corrompues, supprimez le répertoire node_modules et le fichier de verrouillage (yarn.lock ou package-lock.json).
    2. Facultatif : Si l'installation du package échoue à plusieurs reprises, videz le cache de votre gestionnaire de packages (par exemple, exécutez npm cache clean --force).
    3. Vérifiez que la version de Node.js installée est compatible avec les exigences du projet, puis exécutez yarn install ou npm install pour effectuer une nouvelle installation.
  • Vérifiez l'initialisation de ExtensionProvider : ouvrez le fichier d'entrée principal de votre extension (par exemple, App.js ou index.js) et vérifiez que <ExtensionProvider> (importé depuis @looker/extension-sdk-react) encapsule les composants d'application qui ont besoin du contexte du SDK Looker : javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); Si <ExtensionProvider> est manquant ou si vous l'avez placé après les composants qui appellent le SDK, les composants enfants ne peuvent pas accéder au contexte du SDK.

Résoudre les erreurs d'exécution JavaScript et de logique

Si la configuration de l'extension, le serveur de développement, les autorisations et la configuration du SDK sont valides, le problème peut être une erreur d'exécution dans le code JavaScript ou TypeScript personnalisé de l'extension :

  • Analyser les traces de la pile de la console : dans l'onglet Console du navigateur, recherchez le message d'erreur rouge et cliquez sur la flèche de développement pour afficher la trace de la pile complète. Les premières lignes de la trace de la pile identifient le fichier et le numéro de ligne de votre code source où l'erreur s'est produite. Cliquez sur le lien du fichier (par exemple, MyComponent.js:42) pour accéder directement à cette ligne dans l'onglet Sources.
  • Recherchez les valeurs non définies ou nulles : pour les erreurs telles que TypeError: Cannot read properties of undefined, vérifiez que les réponses de l'API asynchrone ou les propriétés ont fini de se charger avant que votre code ne lise les propriétés imbriquées. Ajoutez des vérifications défensives (telles que if (myObject && myObject.property) ou le chaînage facultatif myObject?.property).
  • Vérifiez les formats de réponse de l'API : vérifiez que votre code gère la structure de données réelle renvoyée par les appels d'API Looker (par exemple, en vérifiant si une charge utile de réponse est un objet ou un tableau avant d'appeler des méthodes de tableau).
  • Déboguer avec des points d'arrêt et la journalisation : dans l'onglet Sources du navigateur, définissez des points d'arrêt avant la ligne défaillante pour suspendre l'exécution et inspecter les valeurs des variables en temps réel, ou ajoutez des instructions console.log() pour suivre le flux d'exécution.

Vérifier la compatibilité de la version de Looker

Les mises à jour ou modifications majeures des fonctionnalités de Looker peuvent nécessiter une version compatible du SDK d'extension Looker :

  1. Vérifiez la version de @looker/extension-sdk (et de @looker/extension-sdk-react, le cas échéant) dans le fichier package.json de votre projet d'extension.
  2. Dans l'interface Web de Looker, vérifiez la version actuelle de votre instance sous Aide > À propos ou Admin > Général > Paramètres.
  3. Comparez votre version de Looker avec les notes de compatibilité de la documentation @looker/extension-sdk.
  4. Si votre instance Looker a été récemment mise à niveau et que l'extension utilise un SDK obsolète, ou si l'extension utilise une fonctionnalité SDK plus récente qui n'est pas compatible avec une version antérieure de Looker, mettez à jour le package SDK vers une version compatible : bash npm install @looker/extension-sdk@latest Après avoir mis à jour le package, réinstallez les dépendances et redémarrez votre serveur de développement.

Recueillir des informations de diagnostic

Si vous ne parvenez pas à résoudre le problème après avoir suivi la procédure de dépannage, rassemblez les informations suivantes avant de contacter l'assistance :

  1. Informations sur l'instance et le projet Looker :
    • URL de l'instance Looker (par exemple, instance_name.looker.com).
    • Version de Looker.
    • Nom du projet LookML contenant l'extension et nom de application dans manifest.lkml.
  2. Configuration de l'extension et détails du SDK :
    • Une copie ou une capture d'écran de la déclaration application dans le fichier manifest.lkml.
    • La version de @looker/extension-sdk spécifiée dans package.json.
    • Indique si l'extension est exécutée à partir d'un serveur de développement local (url) ou déployée en production (file).
  3. Journaux d'erreurs et captures d'écran :
    • Captures d'écran ou texte intégral des erreurs des onglets Console et Réseau du navigateur (y compris les en-têtes de requête et les charges utiles de réponse pour les requêtes 4xx ou 5xx ayant échoué).
    • Si les appels d'API renvoient systématiquement des erreurs de serveur 5xx, les extraits de journaux correspondants de looker.log (pour les instances hébergées par le client) ou de l'explorateur de journaux dans Logging (pour les instances Looker (Google Cloud Core)).
  4. Résumé du dépannage et procédure de reproduction :
    • Un résumé des étapes de dépannage que vous avez déjà effectuées et de leurs résultats.
    • La procédure exacte pour reproduire le problème, ou un exemple minimal reproductible si vous suspectez un problème dans le framework d'extension Looker ou le SDK d'extension.

Contacter l'assistance

Si vous avez suivi toutes les étapes précédentes et que le problème n'est toujours pas résolu :