Traitement des erreurs et messages liés aux connecteurs de communauté

Pour offrir une expérience utilisateur de qualité, votre code doit gérer correctement les erreurs. Présentez aux utilisateurs des messages d'erreur exploitables qui décrivent les étapes à suivre 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 les erreurs de connecteur.

Info : Pour en savoir plus sur la gestion des exceptions en JavaScript, consultez la déclaration try...catch.

Types d'erreurs

Les types et les causes d'erreurs qu'un utilisateur peut rencontrer lorsqu'il utilise votre connecteur appartiennent généralement à l'une des trois catégories suivantes :

1. Erreurs internes du connecteur
2. Erreurs externes du connecteur
3. Erreurs Looker Studio

Les erreurs internes et externes du connecteur doivent être gérées par le développeur du connecteur. Ces erreurs se produisent en raison du code créé par le développeur.

Erreur interne du connecteur

Les erreurs internes du connecteur se produisent lors de l'exécution du connecteur. 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 avec des explications conviviales, le cas échéant.

Pour en savoir plus sur la gestion des erreurs internes du connecteur, consultez Bonnes pratiques pour la gestion des erreurs de connecteur.

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() pour trois champs ne renvoie des données que pour deux d'entre eux. Bien que le connecteur ait terminé l'exécution, il n'a pas répondu à la demande de Looker Studio. Des tests approfondis peuvent éviter ces erreurs.

Les erreurs externes du connecteur peuvent généralement être corrigées en examinant les détails de l'erreur (le cas échéant) et en déboguant le code pour 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 ne sont pas liées au 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 aucune action à effectuer. Pour obtenir de l'aide supplémentaire, les utilisateurs peuvent consulter le Centre d'aide Looker Studio.

Afficher les messages d'erreur

Afficher les 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 du statut d'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 savoir comment afficher des messages d'erreur aux utilisateurs non administrateurs, consultez Générer des erreurs visibles par l'utilisateur.

Important : Implémentez isAdminUser() pour identifier les administrateurs et afficher le niveau de détail approprié aux utilisateurs du connecteur.

Afficher des erreurs destinées aux utilisateurs

Par défaut, seuls les administrateurs de connecteurs peuvent voir les détails des erreurs. Cela permet d'éviter la divulgation involontaire d'informations sensibles, comme une clé API dans une trace de pile. Pour afficher des messages d'erreur aux utilisateurs non administrateurs, utilisez newUserError() à partir du service Apps Script 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 affiché pour tous les utilisateurs, tandis que setDebugText() définit le texte qui ne sera affiché que pour les administrateurs.

Bonnes pratiques pour gérer les erreurs de connecteur

Vous devez essayer de détecter et de gérer le plus d'erreurs possible lors de l'exécution du code de votre connecteur. Par exemple, certaines opérations courantes peuvent entraîner des erreurs ou un état indésirable :

• Échec d'une tentative de récupération d'URL (erreurs temporaires, délais d'attente)
• Aucune donnée n'est disponible pour la période demandée
• Les données de l'API ne peuvent pas être analysées ni mises en forme
• 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 sont récupérables, doivent être gérés. Par exemple, si une requête d'API échoue pour une raison non fatale (par exemple, une décharge de charge du serveur), elle doit être relancée avant de générer une erreur.

Relever et générer des erreurs

Les erreurs non récupérables doivent être détectées et relancées. L'erreur relancée devrait aider les utilisateurs à comprendre pourquoi l'erreur s'est produite. Si le problème peut être résolu, des informations sur les mesures correctives doivent être fournies.

Consultez la section Afficher des erreurs à l'utilisateur.

Consigner les erreurs dans Stackdriver

Utilisez Stackdriver pour consigner les erreurs et autres messages. Cela permet de comprendre les erreurs, de déboguer les problèmes et de découvrir les exceptions non gérées.

Pour en savoir plus sur Stackdriver Error Reporting, sur l'activation de la journalisation des exceptions pour un script et sur l'identification sécurisée des utilisateurs à des fins de débogage, consultez Utiliser Stackdriver Logging.

OBSOLÈTE : utilisez le préfixe DS_USER: pour les messages d'erreur sécurisés.

Attention : Cette fonctionnalité est obsolète et sera supprimée en juin 2019. Migrer vers newUserError() Pour en savoir plus, consultez Afficher des erreurs destinées aux utilisateurs.

Pour fournir des messages d'erreur conviviaux aux utilisateurs non administrateurs, incluez le préfixe DS_USER: avec les messages d'erreur. Ce préfixe permet d'identifier les messages sécurisés pour les utilisateurs non administrateurs. Il n'est pas inclus dans le message d'erreur proprement dit.

Les exemples suivants incluent un cas où un message d'erreur s'affiche pour les utilisateurs non administrateurs et un autre où un message d'erreur s'affiche uniquement pour les utilisateurs administrateurs :

data-studio/errors.gs

Afficher sur GitHub

// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

// Only admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('This message will only be shown to admin users');
}

Remarque : Le préfixe DS_USER: n'identifie que les messages sécurisés pour les utilisateurs non administrateurs. Il n'est pas inclus dans le message d'erreur réel affiché aux utilisateurs.