Pour offrir une expérience utilisateur de qualité, votre code doit gérer les erreurs correctement. Présentez aux utilisateurs des messages d'erreur exploitables décrivant les mesures correctives pour résoudre le problème.
Ce document décrit les erreurs qui peuvent se produire avec les connecteurs, le fonctionnement des messages d'erreur et la manière de gérer correctement ces erreurs.
Infos: Pour en savoir plus sur la gestion des exceptions en JavaScript, consultez l'instruction try...catch.
Types d'erreurs
Les types et les causes d'erreurs qu'un utilisateur peut rencontrer lors de l'utilisation de votre connecteur appartiennent généralement à l'une des trois catégories suivantes:
Les erreurs internes et externes du connecteur doivent être gérées par le développeur du connecteur. Ces erreurs sont dues à du code créé par le développeur.
Erreur interne du connecteur
Des erreurs internes au connecteur se produisent pendant son exécution. C'est le cas, par exemple, si un connecteur ne peut pas analyser une réponse d'API lors de l'exécution de getData().
Ces erreurs doivent être anticipées et traitées à l'aide d'explications conviviales, le cas échéant.
Pour plus d'informations sur la gestion des erreurs internes des connecteurs, consultez les Bonnes pratiques de gestion des erreurs des connecteurs.
Erreur externe du connecteur
Les erreurs externes du connecteur se produisent après l'exécution du connecteur. Par exemple, lorsqu'une requête getData() portant sur trois champs ne renvoie les données que pour deux champs. Bien que le connecteur ait terminé l'exécution, il n'a pas répondu à la requête de Looker Studio. Des tests approfondis peuvent éviter ces erreurs.
En règle générale, les erreurs externes des connecteurs peuvent être corrigées en examinant les détails de l'erreur (le cas échéant) et en déboguant le code afin d'identifier le problème. Pour en savoir plus sur le débogage de votre connecteur, consultez Déboguer votre code.
Erreur Looker Studio
Les erreurs Looker Studio sont des erreurs sans rapport avec le code de votre connecteur. (par exemple, si un utilisateur tente d'utiliser un graphique de série temporelle avec une source de données sans dimension de date/heure).
Si l'erreur n'est pas directement liée au connecteur, le développeur du connecteur n'a rien à faire. Pour obtenir de l'aide supplémentaire, les utilisateurs peuvent consulter le Centre d'aide Looker Studio.
Affichage des messages d'erreur
Affichage des détails des erreurs en fonction de l'état de l'administrateur
Lorsqu'un connecteur génère une erreur, Looker Studio affiche le message d'erreur en fonction de l'état de l'administrateur de l'utilisateur.
- Si l'utilisateur est un administrateur, il verra tous les détails. Cela inclut le message d'erreur, le type d'erreur et la trace de la pile.
- Si l'utilisateur n'est pas un administrateur, il ne verra les détails que si l'erreur inclut un message convivial. Pour en savoir plus sur l'affichage des messages d'erreur à des utilisateurs non administrateurs, consultez Générer des erreurs côté utilisateur.
Génération d'erreurs visibles par les utilisateurs
Par défaut, seuls les administrateurs du connecteur peuvent consulter les détails des erreurs. Cela permet d'éviter la divulgation accidentelle d'informations sensibles, telles qu'une clé API dans une trace de la pile. Pour afficher des messages d'erreur auprès des utilisateurs non administrateurs, utilisez newUserError() à partir du service Apps Script de Looker Studio.
Exemple :
try {
// API request that can be malformed.
getDataFromAPI();
} catch (e) {
DataStudioApp.createCommunityConnector()
.newUserError()
.setDebugText('Error fetching data from API. Exception details: ' + e)
.setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
.throwException();
}
Dans cet exemple, setText() définit le texte qui sera présenté à tous les utilisateurs, tandis que setDebugText() définit le texte qui ne sera présenté qu'aux administrateurs.
Bonnes pratiques de gestion des erreurs de connecteur
Vous devez essayer d'identifier et de gérer autant d'erreurs que possible lors de l'exécution du code du connecteur. Voici quelques exemples d'opérations courantes pouvant entraîner des erreurs ou un état indésirable:
- Échec de la tentative de récupération d'URL (erreurs temporaires, délais avant expiration)
- Aucune donnée disponible pour la période demandée
- Impossible d'analyser ou de mettre en forme les données de l'API
- Les jetons d'autorisation ont été révoqués.
Gérer les erreurs récupérables
Les points d'exécution du connecteur qui peuvent échouer, mais qui peuvent être récupérés, doivent être gérés. Par exemple, si une requête API échoue pour une raison non fatale (par exemple, un délestage du serveur), une nouvelle tentative doit être effectuée avant de générer une erreur.
Détecter et renvoyer des erreurs
Les erreurs non récupérables doivent être détectées et générées à nouveau. L'erreur générée à nouveau devrait aider les utilisateurs à comprendre pourquoi elle s'est produite. Si le problème peut être résolu, vous devez alors fournir des informations sur les mesures correctives à prendre.
Découvrez comment générer des erreurs pour les utilisateurs.
Consigner les erreurs dans Stackdriver
Utilisez Stackdriver pour consigner les erreurs et d'autres messages. Cela permet de comprendre les erreurs, de déboguer les problèmes et de détecter les exceptions non gérées.
Pour en savoir plus sur Stackdriver Error Reporting, et découvrir comment activer la journalisation des exceptions pour un script et comment identifier en toute sécurité les utilisateurs à des fins de débogage, consultez la section Utiliser Stackdriver Logging.
OBSOLÈTE: Utiliser le préfixe DS_USER: pour les messages d'erreur sécurisés
Pour fournir des messages d'erreur conviviaux aux utilisateurs non administrateurs, incluez le préfixe DS_USER: avec des messages d'erreur. Ce préfixe permet d'identifier les messages sécurisés pour les utilisateurs non administrateurs et n'est pas inclus dans le message d'erreur réel.
Dans les exemples suivants, un message d'erreur s'affiche pour les utilisateurs non administrateurs, tandis qu'un message d'erreur n'est affiché que pour les administrateurs: