refresh_date: 2023-01-06
Google Cloud vous fournit les outils nécessaires pour surveiller la fiabilité de vos projets avec Google Cloud Monitoring et résoudre les problèmes à l'aide des Google Cloud Logging journaux d'erreurs. Chaque fois qu'un échec se produit lors du traitement des intents utilisateur, le pipeline Google Home Analytics enregistre cet échec dans vos métriques et publie un journal d'erreurs dans les journaux de votre projet.
Pour résoudre les problèmes, vous devez suivre deux étapes :
- Surveillez l'état de vos projets à l'aide des 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.
Surveiller les erreurs
Vous pouvez utiliser Google Cloud Monitoring dashboards pour accéder aux métriques de votre projet. Certains graphiques clés sont particulièrement utiles pour surveiller la qualité et résoudre les problèmes :
- 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 de près ce graphique pour détecter toute irrégularité après chaque modification ou mise à jour de votre projet.
- Les graphiques Répartition des erreurs sont très 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 la 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 la Google Home platform. Consultez le tableau suivant pour obtenir des informations sur la résolution des problèmes. Pour obtenir la liste complète des codes d'erreur, consultez Erreurs et exceptions.
| Code d'erreur | Description | Action du partenaire possible |
|---|---|---|
AGENT_ISSUE |
Un problème général s'est produit avec l'agent cloud du partenaire.
Recherchez les exceptions ou les plantages non gérés dans vos journaux de traitement. |
Oui |
AGENT_UNAVAILABLE_ERROR |
Google n'a pas pu accéder à l'URL de traitement 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 |
BACKEND_FAILURE_URL_TIMEOUT |
La requête de 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 le requestId dans Google Cloud Logging pour consulter
les journaux de votre service pour la maison connectée. Examinez les plantages de serveur, les délais d'attente,
ou les erreurs de passerelle 502/503.
|
|
COMMAND_FAILED |
Un échec générique s'est produit lors de l'exécution d'une commande.
Consultez vos journaux de traitement pour trouver la cause première du requestId
spécifique.
|
Oui |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google a reçu une erreur HTTP 4xx (autre que 401) de votre
traitement.
Recherchez les réponses 403, 404 ou 400 dans les journaux de votre serveur Web. |
Oui |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
L'URL de traitement est bloquée par robots.txt ou des filtres de sécurité.
Assurez-vous que votre point de terminaison de traitement est accessible aux robots d'exploration/services de Google. |
Oui |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google a reçu une erreur HTTP 5xx de votre service de traitement.
Assurez-vous que le service d'URL du point de terminaison est stable, correct et accessible au public et que le service est en cours d'exécution. Ajoutez des vérifications d'état et une gestion des nouvelles tentatives. Examinez 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é abandonné.
Utilisez un validateur JSON pour vous assurer que votre réponse suit strictement les schémas d'intent. |
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 cette action.
Vérifiez les niveaux d'accès demandés lors de l'authentification OAuth et assurez-vous qu'ils correspondent aux caractéristiques requises. |
Oui |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
Le cloud partenaire indique que l'utilisateur a dissocié son compte.
Assurez-vous que votre agentUserId mappage est stable et qu'il n'a pas
été supprimé.
|
Oui |
EXECUTION_GAL_NOT_FOUND |
Les jetons d'accès et d'actualisation de l'utilisateur stockés dans Google ne sont pas valides ou
ne peuvent pas être actualisés, ce qui empêche l'authentification et l'accès au
service partenaire.
Assurez-vous que les jetons restent valides et synchronisés, gérez correctement les modifications d'état du compte et demandez aux utilisateurs de réassocier le compte si les jetons sont confirmés comme étant révoqués. |
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 de maintenance "affichage seul" . |
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é ). Assurez-vous que le serveur OAuth du partenaire répond correctement aux requêtes refresh_token de Google pour émettre de nouveaux jetons d'accès
de manière transparente.
|
Oui |
EXECUTION_INVALID_JSON |
Google n'a pas pu analyser la charge utile de la réponse JSON.
Recherchez les erreurs de syntaxe, les crochets manquants ou les caractères non valides dans votre réponse. |
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 le requestId dans Google Cloud Logging pour consulter 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'intent . |
Oui |
MALFORMED_JSON |
La structure JSON est endommagée (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 |
NOT_IMPLEMENTED |
L'intent ou la caractéristique demandée n'a pas été implémentée par le partenaire.
N'incluez que les caractéristiques que vous avez entièrement implémentées dans votre réponse SYNC.
|
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 requêtes de jeton d'actualisation. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
La chaîne errorCode renvoyée ne figure pas dans la liste compatible de 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
objet valide.
Vérifiez la structure racine de votre réponse de traitement. |
Oui |
PARTNER_RESPONSE_INVALID_STATUS |
Le status de la réponse n'était pas SUCCESS, ERROR ni OFFLINE.
Assurez-vous que chaque résultat d'appareil de 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 de toutes les commandes/de tous les appareils demandés.
Validez la structure de votre réponse par rapport à la documentation pour les développeurs Google Home Assurez-vous que la réponse n'est pas tronquée ou qu'elle ne renvoie pas un corps vide en raison d'une erreur interne du serveur. 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 requête.
|
Oui |
PARTNER_RESPONSE_MISSING_PAYLOAD |
Le champ payload obligatoire est manquant dans la réponse.
Assurez-vous que votre objet JSON de premier niveau inclut une clé payload.
|
Oui |
PARTNER_RESPONSE_NOT_OBJECT |
L'ensemble de la réponse n'a pas pu être analysé en tant qu'objet JSON.
Recherchez les caractères de fin ou le contenu non JSON dans le corps de votre réponse HTTP. Assurez-vous que payload.commands[] est un objet JSON approprié avec des ID, un état et des états facultatifs.
|
Oui |
REQUEST_ID_NOT_FOUND |
Google n'a pas trouvé l'ID de suivi interne de la requête.
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 de traitement n'a pas répondu dans les neuf secondes.
Optimisez la latence du backend. Vérifiez si les requêtes de base de données sont lentes ou si le réseau régional est lent. |
Oui |
RESPONSE_UNAVAILABLE |
Aucune réponse n'a été reçue de l'URL de traitement du partenaire.
Vérifiez que votre service est en cours d'exécution et que le point de terminaison ne plante pas. |
Oui |
TIMEOUT |
Un délai d'attente général s'est produit lors du traitement de l'intent.
Recherchez les délais d'attente internes du service entre vos hubs cloud et d'appareil dans les journaux. |
Oui |
Journaux sur les recherches
Une fois que vous êtes à l'aise avec la surveillance de vos intégrations à l'aide de métriques, la prochaine étape 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 concernant l'intent pour la maison connectée d'origine.
Plusieurs systèmes de Google Cloud envoient des journols à 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, ressource, une gravité de journal 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 et choisissez l'une des options fournies. Les journaux seront filtrés et ceux qui proviennent de la période sélectionnée s'afficheront.
Pour spécifier une ressource, cliquez sur le menu déroulant Ressource, puis sélectionnez Projet d'action Google Assistant. Un filtre est ajouté à votre requête pour afficher les journaux provenant de votre projet.
Utilisez le bouton Gravité pour filtrer par Urgence, Info, Débogage, et d'autres niveaux de gravité de journal.
Vous pouvez également utiliser le champ "Requête" dans le Logs Explorer
pour saisir des entrées personnalisées. Le moteur de requête utilisé par ce champ est compatible avec les requêtes de base, telles que la correspondance de chaînes, et avec des 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 les 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 dans les journaux.
Tester les corrections
Une fois que vous avez identifié les erreurs et appliqué des mises à jour pour les corriger, nous vous recommandons de tester vos corrections de manière approfondie 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 Déboguer la maison connectée: guide de démarrage rapide pour déboguer l'intégration cloud pour la maison connectée.
- Atelier de programmation Déboguer la maison locale: guide de démarrage rapide pour déboguer l'intégration locale pour la maison connectée.