Google Cloud vous fournit les outils nécessaires pour surveiller la fiabilité de vos projets avec Google Cloud Monitoring et déboguer les problèmes avec les journaux d'erreurs Google Cloud Logging. Chaque fois qu'une défaillance se produit lors de la réponse aux intentions des utilisateurs, le pipeline Google Home Analytics enregistre cette défaillance dans vos métriques et publie un journal d'erreurs dans les journaux de votre projet.
Pour résoudre les erreurs, vous devez suivre deux étapes :
- Surveillez l'état de vos projets grâce aux métriques pour la maison connectée.
- Examinez les problèmes en consultant les descriptions détaillées des erreurs dans les journaux d'erreurs.
Vous pouvez également tester votre action en la partageant avec d'autres utilisateurs. Assurez-vous de gérer les erreurs et les exceptions de manière appropriée.
Erreurs de surveillance
Vous pouvez utiliser des Google Cloud Monitoring dashboard pour accéder aux métriques de votre projet. Certains graphiques clés sont particulièrement utiles pour surveiller la qualité et déboguer :
- Le graphique Taux de réussite est le premier à consulter lorsque vous surveillez la fiabilité de vos projets. Les baisses dans ce graphique peuvent indiquer une panne pour une partie ou l'ensemble de votre base d'utilisateurs. Nous vous recommandons de surveiller attentivement ce graphique pour détecter toute irrégularité après chaque modification ou mise à jour de votre projet.
- Le graphique Latence au 95e centile est un indicateur important des performances de votre intégration Cloud-to-cloud pour vos utilisateurs. Des fluctuations soudaines dans ce graphique peuvent indiquer que vos systèmes ne sont pas en mesure de répondre aux demandes. Nous vous conseillons de consulter régulièrement ce graphique pour détecter tout comportement inattendu.
- Les graphiques Répartition des erreurs sont particulièrement utiles pour résoudre les problèmes liés à vos intégrations. Pour chaque erreur mise en évidence dans le graphique du pourcentage de réussite, un code d'erreur s'affiche dans la répartition des erreurs. Vous pouvez consulter les erreurs signalées par Google Home platform et découvrir comment les résoudre dans le tableau ci-dessous.
Codes d'erreur courants de la plate-forme
Voici quelques codes d'erreur courants que vous pouvez voir dans les journaux de votre projet pour identifier les problèmes détectés par Google Home platform. Consultez le tableau ci-dessous pour obtenir des informations de dépannage. Pour obtenir la liste complète des codes d'erreur, consultez Erreurs et exceptions.
| Code d'erreur | Description | Action requise du partenaire |
|---|---|---|
ACTION_NOT_AVAILABLE |
La commande n'est pas valide pour l'état actuel de l'appareil (par exemple, "Régler la température" alors que l'appareil est éteint).
Vérifiez les traits de l'appareil et la logique de l'état actuel dans votre traitement. |
Oui |
AGENT_ISSUE |
Un problème général s'est produit avec l'agent cloud du partenaire.
Recherchez les exceptions non gérées ou les plantages dans les journaux de traitement. |
Oui |
AGENT_UNAVAILABLE_ERROR |
Google n'a pas pu accéder à l'URL d'exécution du partenaire.
Assurez-vous que votre serveur est en ligne, que le pare-feu ne bloque pas Google et que l'URL est correcte. |
Oui |
APP_LAUNCH_FAILED |
Échec du lancement de l'application tierce sur l'appareil cible.
Vérifiez l'appId et assurez-vous que l'application est compatible avec le matériel cible. |
Oui |
AUTH_EXPIRED |
Le jeton d'accès OAuth a expiré et ne peut pas être actualisé.
Vérifiez la rotation du jeton d'actualisation et assurez-vous que l'utilisateur n'a pas révoqué l'accès. |
Oui |
BACKEND_FAILURE_URL_TIMEOUT |
Le délai d'attente de la requête Google a expiré lors de la tentative d'accès à votre service.
Vérifiez que votre service est en ligne, qu'il accepte les connexions et qu'il n'est pas surchargé. Vérifiez également que l'appareil cible est allumé, en ligne et synchronisé. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google a reçu un code d'erreur HTTP 5xx de votre service.
Utilisez requestId dans Google Cloud Logging pour vérifier les journaux de votre service pour la maison connectée.
|
|
CHANNEL_SWITCH_FAILED |
L'appareil n'a pas pu passer à la chaîne multimédia demandée.
Vérifiez les noms/numéros des chaînes et l'état de l'abonnement de l'utilisateur. |
Oui |
CHARGER_ISSUE |
L'appareil signale un problème matériel avec son système de recharge.
Le partenaire doit examiner la télémétrie au niveau matériel et l'état de la batterie. |
Oui |
CHECK_PARTNER_APP |
L'utilisateur doit ouvrir l'application du partenaire pour résoudre l'erreur.
Utilisez ce code pour les erreurs nécessitant une interaction complexe avec l'UI (par exemple, les mises à jour du micrologiciel). |
Oui |
COMMAND_FAILED |
Une erreur générique s'est produite lors de l'exécution d'une commande.
Consultez vos journaux d'exécution pour trouver la cause première de l' requestId.
|
Oui |
COMMAND_INSERT_FAILED |
Google n'a pas pu mettre en file d'attente ni traiter la commande pour l'appareil.
Examinez les performances d'écriture de la base de données ou la logique de mise en file d'attente des commandes internes. |
Oui |
DEVICE_NOT_FOUND |
L'ID de l'appareil indiqué dans la requête n'existe pas côté partenaire.
Assurez-vous que votre cloud déclenche un requestSync lorsqu'un utilisateur
ajoute ou supprime des appareils.
|
Oui |
ERROR_STATUS |
La réponse indiquait un état "ERROR" non spécifique sans code.
Incluez toujours une chaîne errorCode spécifique pour améliorer
les données TTS et du tableau de bord des utilisateurs.
|
Oui |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google a reçu une erreur HTTP 4xx (autre que 401) de votre service d'exécution.
Recherchez les réponses 403, 404 ou 400 dans les journaux de votre serveur Web. |
Oui |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
L'URL d'exécution est bloquée par le fichier robots.txt ou par des filtres de sécurité.
Assurez-vous que votre point de terminaison d'exécution est accessible aux robots d'exploration et services Google. |
Oui |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google a reçu une erreur HTTP 5xx de votre service d'exécution.
Enquêter sur les plantages de serveur, les délais d'attente ou les erreurs de passerelle 502/503. |
Oui |
EXECUTION_BAILOUT_INVALID_RESPONSE |
La réponse JSON était tellement mal formée que le traitement a été interrompu.
Utilisez un validateur JSON pour vous assurer que votre réponse suit strictement les schémas d'intention. |
Oui |
EXECUTION_GAL_BAD_3P_RESPONSE |
L'association de compte a échoué en raison d'un format non valide dans la réponse du jeton.
Vérifiez que le format de réponse de votre serveur OAuth correspond aux exigences de Google. |
Oui |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
Le compte de l'utilisateur ne dispose pas des autorisations nécessaires pour effectuer cette action.
Vérifiez les niveaux d'accès demandés lors de l'authentification OAuth et assurez-vous qu'ils correspondent aux traits requis. |
Oui |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Le cloud du partenaire indique que l'utilisateur a dissocié son compte.
Assurez-vous que votre mappage agentUserId est stable et n'a pas été supprimé.
|
Oui |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
L'intégration est en lecture seule côté partenaire.
Vérifiez si le compte de l'utilisateur est suspendu ou en mode maintenance "lecture seule". |
Oui |
EXECUTION_GAL_UNLINKED_BY_3P |
Le compte a été dissocié de manière proactive par le service tiers.
Déterminez pourquoi l'utilisateur a été déconnecté (par exemple, réinitialisation de la sécurité). |
Oui |
EXECUTION_INVALID_JSON |
Google n'a pas pu analyser la charge utile de la réponse JSON.
Vérifiez que votre réponse ne contient pas d'erreurs de syntaxe, de crochets manquants ni de caractères non valides. |
Oui |
FAULTY_BATTERY |
Le matériel de l'appareil indique que la batterie est défaillante ou déchargée.
Indiquez à l'utilisateur d'utiliser la synthèse vocale ou l'application pour remplacer la batterie physique. |
Oui |
FUNCTION_NOT_SUPPORTED |
Le mode ou la fonction demandés ne sont pas compatibles avec l'appareil.
Assurez-vous que la réponse SYNC reflète précisément les capacités de l'appareil.
|
Oui |
HARD_ERROR |
Échec non temporaire qui ne sera pas résolu sans intervention manuelle.
À utiliser en cas de défaillance matérielle permanente ou d'état de compte irrécupérable. |
Oui |
INVALID_AUTH_TOKEN |
Google a reçu un code d'erreur HTTP 401 de votre service.
Le jeton d'accès n'a pas expiré, mais votre service l'a invalidé. Utilisez requestId dans Google Cloud Logging pour vérifier les journaux de votre service pour la maison connectée.
|
|
INVALID_JSON |
La structure de la réponse n'est pas valide (par exemple, des champs obligatoires sont manquants).
Validez votre réponse par rapport aux schémas JSON d'intention. |
Oui |
LOCK_FAILURE |
La serrure connectée n'a pas pu passer à l'état demandé.
Vérifiez si le matériel de la serrure est bloqué, si la batterie est faible ou si le moteur est défaillant. |
Oui |
MALFORMED_JSON |
La structure JSON est incorrecte (par exemple, chaînes ou objets non fermés).
Assurez-vous que votre traitement utilise une bibliothèque JSON standard pour sérialiser les réponses. |
Oui |
MISSING_STATE |
La réponse QUERY ne contenait pas l'état de l'appareil demandé.
Assure-toi que tous les traits définis dans SYNC sont pris en compte dans
chaque réponse QUERY.
|
Oui |
NETWORK_PROFILE_NOT_RECOGNIZED |
Le profil réseau demandé est inconnu de l'appareil.
Vérifiez que la chaîne du nom de profil correspond aux profils compatibles dans la réponse SYNC.
|
Oui |
NOT_IMPLEMENTED |
L'intention ou le trait demandés n'ont pas été implémentés par le partenaire.
N'incluez dans votre réponse SYNC que les traits que vous avez
entièrement implémentés.
|
Oui |
OAUTH_RECONNECT_CALL_TO_ACTION |
Déclenche une notification pour que l'utilisateur associe à nouveau son compte.
Utilisez cette option lorsque la session d'un utilisateur est invalidée et qu'une réauthentification OAuth manuelle est requise. |
Oui |
OPEN_AUTH_FAILURE |
Le jeton d'accès de l'utilisateur a expiré et Google ne peut pas l'actualiser, ou Google a reçu un code d'erreur HTTP 401 de votre service.
Si vous constatez une augmentation du taux de ce code, vérifiez si vous constatez également une augmentation du taux d'erreurs liées aux intents pour la maison connectée ou aux demandes de jeton d'actualisation. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
La chaîne errorCode renvoyée ne figure pas dans la liste des chaînes acceptées par Google.
Mappez vos erreurs internes à la liste officielle des erreurs. |
Oui |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Le champ payload de la réponse n'est pas un objet JSON valide.
Vérifiez la structure racine de votre réponse d'exécution. |
Oui |
PARTNER_RESPONSE_INVALID_STATUS |
La réponse status n'était pas SUCCESS, ERROR ni OFFLINE.
Assurez-vous que chaque résultat d'appareil dans votre réponse inclut une chaîne d'état valide. |
Oui |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
La réponse n'incluait pas les résultats pour toutes les commandes/tous les appareils demandés.
Chaque élément du tableau commands de la requête doit avoir une entrée de réponse correspondante.
|
Oui |
PARTNER_RESPONSE_MISSING_DEVICE |
Un appareil spécifique demandé par Google a été omis de la réponse.
Assurez-vous que votre réponse inclut chaque ID fourni dans la charge utile de la demande.
|
Oui |
PARTNER_RESPONSE_MISSING_PAYLOAD |
Il manque le champ obligatoire payload dans la réponse.
Assurez-vous que votre objet JSON de premier niveau inclut une clé payload.
|
Oui |
PARTNER_RESPONSE_NOT_OBJECT |
Impossible d'analyser l'intégralité de la réponse en tant qu'objet JSON.
Vérifiez la présence de caractères de fin ou de contenu non JSON dans le corps de la réponse HTTP. |
Oui |
PROTOCOL_ERROR |
Une erreur s'est produite dans le protocole de communication sous-jacent.
Examinez les problèmes d'en-tête HTTP ou les échecs de handshake SSL/TLS. |
Oui |
RELINK_REQUIRED |
L'utilisateur doit associer de nouveau son compte pour continuer à utiliser l'intégration.
Assurez-vous que votre serveur renvoie ce code lorsqu'un jeton d'actualisation est définitivement non valide. |
Oui |
REQUEST_ID_NOT_FOUND |
Google n'a pas trouvé l'ID de suivi interne de la demande.
Il s'agit généralement d'une erreur interne de la plate-forme. Surveillez les pics et contactez l'assistance. |
Oui |
RESOURCE_UNAVAILABLE |
La ressource demandée (appareil ou caractéristique) n'est pas disponible.
Vérifiez si l'appareil est "Occupé" ou s'il a été temporairement désactivé. |
Oui |
RESPONSE_TIMEOUT |
Le service d'exécution n'a pas répondu dans les neuf secondes.
Optimisez la latence du backend. Vérifiez si des requêtes de base de données sont lentes ou si le réseau régional présente une latence. |
Oui |
RESPONSE_UNAVAILABLE |
Aucune réponse n'a été reçue de l'URL d'exécution du partenaire.
Vérifiez que votre service est en cours d'exécution et que le point de terminaison ne plante pas. |
Oui |
SCENE_CANNOT_BE_APPLIED |
La scène demandée n'a pas pu être activée (par exemple, des appareils sont manquants).
Vérifiez l'état interne des scènes de l'utilisateur sur le cloud du partenaire. |
Oui |
STREAM_UNPLAYABLE |
Le flux de la caméra n'a pas pu être démarré ou a échoué.
Vérifiez la signalisation WebRTC/HLS et assurez-vous que l'URL du flux est valide. |
Oui |
TIMEOUT |
Un délai général a expiré lors du traitement de l'intention.
Vérifiez les journaux pour les délais d'expiration des services internes entre vos hubs cloud et d'appareils. |
Oui |
TRANSIENT_ERROR |
Une erreur temporaire est une erreur qui se résoudra d'elle-même.
Ces erreurs se manifestent généralement par une déconnexion d'un appareil ou d'un service. Également si de nouvelles connexions à un serveur ne peuvent pas être ouvertes. |
|
UNABLE_TO_LOCATE_DEVICE |
L'appareil n'a pas pu être trouvé à l'aide du trait Locator (par exemple, le ping a échoué).
Vérifiez la connectivité locale de l'appareil (Wi-Fi/Bluetooth). |
Oui |
UNABLE_TO_RING_DEVICE |
L'appareil a été contacté, mais sa fonction de sonnerie/d'alerte n'a pas pu être déclenchée.
Vérifiez l'état de l'alerte/du haut-parleur et les niveaux de volume du matériel. |
Oui |
UNABLE_TO_SILENCE_DEVICE |
L'appareil n'a pas pu arrêter son alerte/sonnerie active.
Examinez les échecs de communication entre le cloud et l'appareil physique. |
Oui |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
Une erreur imprévue s'est produite. L'utilisateur doit vérifier l'application partenaire.
À utiliser comme solution globale pour les erreurs sans équivalent spécifique compatible avec Google. |
Oui |
UNKNOWN_ERROR |
Échec générique sans autre détail.
Essayez de remplacer ce code par des codes d'erreur plus spécifiques pour améliorer le dépannage. |
Oui |
UNLOCK_FAILURE |
La serrure connectée n'a pas pu passer à l'état "Déverrouillé".
Recherchez les blocages matériels, les batteries faibles ou les codes saisis non valides. |
Oui |
Journaux sur les recherches
Une fois que vous êtes à l'aise pour surveiller vos intégrations à l'aide de métriques, l'étape suivante consiste à résoudre des erreurs spécifiques à l'aide de Cloud Logging. Un journal d'erreurs est une entrée de type JSON avec des champs contenant des informations utiles telles que l'heure, le code d'erreur et des détails sur l'intention de maison connectée à l'origine de l'erreur.
Plusieurs systèmes de Google Cloud envoient des journaux à votre projet à tout moment. Vous devez écrire des requêtes pour filtrer vos journaux et trouver ceux dont vous avez besoin. Les requêtes peuvent être basées sur une période, une ressource, la gravité des journaux ou des entrées personnalisées.
Vous pouvez utiliser les boutons de requête pour vous aider à créer vos filtres personnalisés.
Pour spécifier une période, cliquez sur le bouton de sélection de la période , puis choisissez l'une des options proposées. Les journaux seront filtrés et ceux qui proviennent de la plage de dates sélectionnée s'afficheront.
Pour spécifier une ressource, cliquez sur le menu déroulant Ressource, puis sélectionnez Projet d'action de l'Assistant Google. Cela ajoute un filtre à votre requête pour afficher les journaux provenant de votre projet.
Utilisez le bouton Gravité pour filtrer les journaux par niveau de gravité : Urgence, Info, Débogage, etc.
Vous pouvez également utiliser le champ "Requête" dans Logs Explorer pour saisir des entrées personnalisées. Le moteur de requête utilisé par ce champ accepte à la fois les requêtes de base, comme la correspondance de chaînes, et les types de requêtes plus avancés, y compris les comparateurs (<, >=, !=) et les opérateurs booléens (AND, OR, NOT).
Par exemple, l'entrée personnalisée ci-dessous renverrait des erreurs provenant d'un type d'appareil LIGHT :
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Consultez la bibliothèque de requêtes pour trouver d'autres exemples de requêtes efficaces pour les journaux.
Tester les corrections
Une fois que vous avez identifié les erreurs et appliqué les mises à jour pour les corriger, nous vous recommandons de tester minutieusement vos correctifs avec Google Home Test Suite. Nous fournissons un guide de l'utilisateur sur l'utilisation de Test Suite, qui vous explique comment tester efficacement vos modifications.
Ressources d'apprentissage
Ce document explique comment résoudre les erreurs dans votre action pour la maison connectée. Vous pouvez également consulter nos ateliers de programmation pour en savoir plus sur le débogage :
- Atelier de programmation sur le débogage de la maison connectée : guide de démarrage rapide pour déboguer l'intégration cloud de la maison connectée.
- Atelier de programmation sur le débogage de Local Home : guide de démarrage rapide pour déboguer l'intégration locale de la maison connectée.