Résoudre les erreurs d'intégration de Matter

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 déboguer les problèmes avec les journaux d'erreurs Google Cloud Logging. Chaque fois qu'un échec se produit lors de la réalisation des intentions de l'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.

La résolution des erreurs se fait en deux étapes :

  1. Surveillez l'état de vos projets grâce aux métriques de la maison connectée.
  2. Examinez les problèmes en consultant les descriptions détaillées des erreurs dans les journaux d'erreurs.

Erreurs de surveillance

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 déboguer :

  • Le graphique Taux de réussite est le premier graphique à consulter lorsque vous surveillez la fiabilité de vos projets. Les baisses dans ce graphique peuvent indiquer une panne pour une partie ou la totalité 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 de 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. Le tableau ci-dessous présente les erreurs signalées par le Google Home platform et la manière de les résoudre.

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 suivant 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 Actionnable par le partenaire
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 vos journaux de fulfillment. 		Oui
AGENT_UNAVAILABLE_ERROR Google n'a pas pu accéder à l'URL de traitement du partenaire.

Vérifiez que votre serveur est en ligne, que le pare-feu ne bloque pas Google et que l'URL est correcte. 		Oui
COMMAND_FAILED Une erreur générique s'est produite lors de l'exécution d'une commande.

Consultez vos journaux de fulfillment pour trouver la cause racine de l'erreur requestId. 		Oui
EXECUTION_BACKEND_FAILURE_URL_ERROR Google a reçu une erreur HTTP 4xx (autre que 401) de votre fulfillment.

Vérifiez les journaux de votre serveur Web pour détecter les réponses 403, 404 ou 400. 		Oui
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT Le délai d'attente de 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 saturé. Vérifiez également que l'appareil cible est allumé, en ligne et synchronisé. 		Oui
EXECUTION_BACKEND_FAILURE_URL_ROBOTED L'URL de fulfillment est bloquée par le fichier robots.txt ou des filtres de sécurité.

Assurez-vous que votre point de terminaison de fulfillment 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 fulfillment.

Assurez-vous que l'URL du point de terminaison est stable, correcte et accessible publiquement, et que le service est en cours d'exécution. Utilisez l'requestId dans Google Cloud Logging pour consulter les journaux de votre service pour la maison connectée. Ajoutez des vérifications d'état et une gestion des nouvelles tentatives. Examiner les plantages de serveur, les expirations de délai ou les erreurs de passerelle 502/503. 		Oui
EXECUTION_BAILOUT_INVALID_RESPONSE La réponse JSON était tellement incorrecte que le traitement a été interrompu.

Utilisez un outil de validation JSON pour vous assurer que votre réponse respecte strictement les schémas d'intent. 		Oui
EXECUTION_GAL_BAD_3P_RESPONSE Échec de l'association du compte 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 champs d'application 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 mappage agentUserId est stable et n'a pas été purgé. 		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 les changements d'état du compte de manière appropriée et demandez aux utilisateurs d'associer à nouveau le compte si les jetons sont confirmés comme révoqués.
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P L'intégration est en lecture seule du côté du 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 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 fluide. 		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 ou de caractères non valides. 		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 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 défectueuse (par exemple, des chaînes ou des objets non fermés).

Assurez-vous que votre fulfillment utilise une bibliothèque JSON standard pour sérialiser les réponses. 		Oui
NOT_IMPLEMENTED L'intent ou la caractéristique demandés n'ont pas été implémentés par le partenaire.

N'incluez dans votre réponse SYNC que les caractéristiques que vous avez entièrement implémentées. 		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 de maison connectée ou aux demandes de jetons 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 de fulfillment. 		Oui
PARTNER_RESPONSE_INVALID_STATUS La réponse status n'était pas SUCCESS, ERROR ou 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'inclut pas les résultats pour toutes les commandes/tous les appareils demandés.

Vérifiez que la structure de votre réponse est conforme à 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 obligatoire payload est manquant dans la réponse.

Assurez-vous que votre objet JSON de niveau supérieur 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 si le corps de votre réponse HTTP contient des caractères de fin ou du contenu non JSON. Assurez-vous que payload.commands[] est un objet JSON valide 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 demande.

Il s'agit généralement d'une erreur de plate-forme interne. Surveillez les pics et contactez l'assistance. 		Oui
RESOURCE_UNAVAILABLE La ressource demandée (appareil ou trait) 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 fulfillment n'a pas répondu dans les 9 secondes.

Optimisez la latence du backend. Recherchez les requêtes de base de données lentes ou les retards du réseau régional. 		Oui
RESPONSE_UNAVAILABLE Aucune réponse n'a été reçue de l'URL de fulfillment 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'expiration général s'est produit lors du traitement de l'intent.

Vérifiez les journaux pour détecter les délais d'expiration des services internes entre votre cloud et vos hubs d'appareils. 		Oui

Journaux sur les recherches

Une fois que vous êtes à l'aise avec la surveillance de 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 dont les champs contiennent des informations utiles telles que l'heure, le code d'erreur et des détails sur l'intent de maison connectée d'origine.

Plusieurs systèmes de Google Cloud envoient en permanence des journaux à votre projet. 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é du journal ou des entrées personnalisées.

Interroger les journaux Cloud

Vous pouvez utiliser les boutons de requête pour créer vos filtres personnalisés.

Créer des requêtes de journaux Cloud

Pour spécifier une période, cliquez sur le bouton de sélection de la période et choisissez l'une des options proposées. Cela filtrera les journaux et affichera ceux qui proviennent de la période sélectionnée.

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 résultats par Urgence, Info, Débogage et d'autres niveaux de gravité des journaux.

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, telles que 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 renvoie 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 sur 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 corrections 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 :

Précédent
Cloud Logging pour les litiges