Google Home Vitals (Cloud)

Cette suite de tableaux de bord et d'alertes vous aide à maintenir de manière proactive une intégration de haute qualité avec l'écosystème Google Home. Google s'engage à aider ses partenaires à développer un écosystème de haute qualité pour tous les clients.

Le tableau de bord comporte trois sections, chacune couvrant un élément clé qui contribue à la qualité d'une intégration globale.

1. Métriques Google vers partenaire : mesurent l'état des appels de Google vers votre backend cloud.

2. État du système : métriques de partenaire à Google : mesure l'état des appels de votre système à Google.

3. État de l'appareil : précision de l'état : mesure la précision des états stockés dans les systèmes Google, qui sont utilisés pour répondre aux requêtes des utilisateurs.

Lorsque les métriques ne respectent pas leurs valeurs cibles, elles sont mises en évidence en rouge pour indiquer un problème susceptible d'avoir un impact sur l'expérience utilisateur. Les informations suivantes fournissent des détails sur chaque cible et expliquent pourquoi elle est importante pour vos utilisateurs.

Si le bouton suivant ne vous redirige pas directement vers le tableau de bord, vous pouvez y accéder en sélectionnant la page Présentation, puis Tableaux de bord. Ensuite, dans la liste Mes tableaux de bord, sélectionnez Tableau de bord des données vitales Google Home (Cloud) pour afficher votre tableau de bord.

Accéder à Google Dashboard

Métriques Google pour les partenaires

La métrique Taux de réussite des requêtes/exécutions >= 99, 5% mesure la fréquence à laquelle les commandes des utilisateurs sont exécutées correctement.Elle permet d'éviter les réponses de l'Assistant telles que "Je n'arrive pas à accéder à l'appareil" ou la confirmation incorrecte d'une commande qui n'a pas été exécutée.

Qu'est-ce qu'un "succès" ?

Une transaction est marquée comme réussie si la plate-forme Google Home reçoit une réponse valide indiquant que l'action prévue a été effectuée ou que l'état demandé a été récupéré.

Les réponses qui incluent des exceptions non bloquantes (par exemple, un état SUCCESS accompagné d'une exception lowBattery) sont comptabilisées comme des transactions réussies. La commande a atteint l'appareil et l'intention a été satisfaite malgré l'avertissement.

Qu'est-ce qu'un échec ?

Les erreurs listées sur la page Codes d'erreur courants de la plate-forme et marquées comme Action requise du partenaire sont considérées comme des "échecs" lors du calcul des taux de réussite des requêtes et des exécutions. De plus, les erreurs trouvées sur Erreurs et exceptions sont également des "Échecs", à l'exception des suivantes :

La métrique Latence de requête/d'exécution (p90) <= 1 000 ms mesure le temps d'attente pour l'action demandée et permet de s'assurer que les utilisateurs n'ont pas à attendre trop longtemps (par exemple, quelques secondes pour que leur lumière s'éteigne).

Statistiques relatives à la latence

La latence est un indicateur essentiel de la réactivité de votre intégration pour l'utilisateur final. Le tableau de bord suit la latence au 90e centile (P90), qui représente l'expérience de vos utilisateurs les plus "lents" (par exemple, un P90 de 800 ms signifie que 90% des requêtes sont traitées en 800 ms ou moins).

Google mesure la latence différemment pour les vérifications d'état et les commandes d'appareil afin de garantir la précision technique.

1. Latence des REQUÊTES (interrogatives)

Cette métrique mesure le temps d'aller-retour Cloud-to-cloud lorsque Google demande l'état actuel d'un appareil.

• Début : Google envoie une requête action.devices.QUERY à votre URL de traitement.
• Période de mesure : temps nécessaire à votre cloud pour recevoir, traiter et retransmettre la réponse HTTP complète à Google.
• Fin : Google reçoit et accuse réception de la charge utile de la réponse finale de votre service.

2. Latence EXECUTE (action)

Il s'agit du temps d'accusé de réception de la commande lorsque Google envoie une demande de contrôle à un appareil.

• Début : Google envoie une requête action.devices.EXECUTE à votre URL de traitement.
• Période de mesure : temps nécessaire à votre cloud pour recevoir la commande et renvoyer une réponse d'accusé de réception.
• Fin : Google reçoit la réponse d'état SUCCESS, PENDING ou OFFLINE.
• Champ d'application technique : cette métrique mesure le temps d'accusé de réception de la réponse entre le cloud de Google et le vôtre. Elle ne mesure pas le temps nécessaire au matériel physique (par exemple, une ampoule) pour effectuer le changement d'état physique, car cela implique souvent une latence du réseau maillé local en dehors du chemin cloud à cloud.

Options de réduction de la latence

Recommandations d'architecture pour le géoroutage

Si l'implémentation d'une adresse IP Anycast n'est pas possible, nous vous recommandons les alternatives économiques suivantes pour vous assurer que les utilisateurs sont desservis par le centre de données régional le plus proche.

1. Équilibrage de charge global (GLB)

   Au lieu du routage statique, utilisez un équilibreur de charge d'application global (disponible auprès de la plupart des principaux fournisseurs de services cloud).

   • Fonctionnement : vous configurez un point d'entrée global unique (URL) situé à la périphérie du réseau. L'équilibreur de charge détecte automatiquement l'origine géographique de la requête à partir des clusters de traitement de Google et achemine le trafic vers le backend régional opérationnel le plus proche.

   • Avantage : cela permet de bénéficier des performances d'Anycast avec une complexité de configuration et des coûts considérablement réduits.

2. DNS tenant compte de la géolocalisation (GeoDNS)

   • Fonctionnement : configurez votre fournisseur DNS pour qu'il résolve votre URL de traitement sur différentes adresses IP en fonction de l'emplacement géographique de la requête DNS.

   • Implémentation : assurez-vous que votre fournisseur DNS est optimisé pour les points de sortie de Google. Lorsque les services de traitement régionaux de Google (par exemple, aux États-Unis, dans l'UE ou en Asie) résolvent votre domaine, ils reçoivent l'adresse IP du centre de données dans cette région spécifique.

Stratégies d'optimisation au niveau de la couche Application

Au-delà du routage au niveau de l'infrastructure, vous pouvez implémenter les stratégies suivantes au niveau de l'application pour réduire la latence dans le traitement des requêtes.

1. Méthode de proxy "Trampoline"

   Si vous devez conserver un centre de données principal, utilisez des serveurs proxy régionaux légers (Trampolines) pour gérer l'établissement de la connexion initiale.

   1. Google accède à votre URL mondiale.

   2. Un proxy régional (par exemple, une fonction Nginx ou Lambda légère) reçoit la requête.

   3. Le proxy transfère la charge utile sur votre backbone interne à haut débit vers la base de données principale.

   Avantage : cela réduit le temps de "prise de contact TCP", qui est souvent le principal facteur de latence pour les requêtes longue distance.

2. Indication de la région du jeton d'accès

   Lors du processus d'association de compte (OAuth), votre système peut identifier la région du domicile de l'utilisateur.

   Implémentation : encodez un identifiant de région dans le access_token émis pour Google. Lorsque Google envoie une demande d'exécution, votre passerelle peut inspecter immédiatement le jeton et acheminer la demande vers le cluster régional approprié sans avoir besoin d'une recherche dans la base de données.

État du système : métriques "Partenaire vers Google"

Le maintien d'un taux de réussite supérieur ou égal à 99, 5% permet de s'assurer que les états des appareils sont corrects dans Google Home, que les appareils sont ajoutés et supprimés, que les automatisations se déclenchent et que les événements de l'historique s'affichent dans l'onglet "Activité" de Google Home app (GHA).

Le taux de réussite est calculé en fonction des codes de réponse HTTP renvoyés par Google lorsque votre cloud envoie des mises à jour d'état. Pour s'assurer que les partenaires ne sont pas pénalisés en cas de problèmes d'infrastructure côté Google, la métrique exclut les erreurs internes de Google du nombre d'échecs. Les appels d'API inclus dans le calcul se trouvent dans la documentation de référence de l'API HomeGraph.

Qu'est-ce qu'un "succès" ?

2xx (Succès) : la mise à jour de l'état a été reçue et traitée par Home Graph.

Qu'est-ce qu'un échec ?

Les erreurs 4xx (erreur du partenaire) représentent des échecs et indiquent un problème avec la requête envoyée depuis votre cloud. Voici quelques codes courants :

400 Requête incorrecte

Cause : le serveur n'a pas pu traiter la requête en raison d'une syntaxe non valide. Les causes courantes incluent un code JSON mal formé ou l'utilisation de la valeur "null" au lieu de "" pour une valeur de chaîne.

Solution : Assurez-vous que le corps de la requête est un fichier JSON valide (structure non déformée et valeurs nulles pour les champs de chaîne), et vérifiez que agentUserId correspond à la valeur de la réponse SYNC.

404 Not Found

Cause : deviceId ou agentUserId introuvable dans HomeGraph (pas encore synchronisé, déjà dissocié ou ID non correspondant).

Solution :

1. Assurez-vous que agentUserId correspond à la valeur fournie dans votre réponse SYNC.
2. Utilisez l'API Home Graph SYNC pour déterminer si l'erreur 404 "Not Found" (Introuvable) est due à un appareil ou à un utilisateur manquant dans HomeGraph.
3. Veillez à déclencher requestSync après l'ajout, la suppression, le changement de nom ou la mise à jour d'un appareil ou d'un compte pour vous assurer que l'état reste à jour.
4. Gérez correctement les intents DISCONNECT pour arrêter de signaler les appareils obsolètes. Après avoir reçu l'intention DISCONNECT, votre service cloud doit cesser de publier les modifications sur Google avec Request Sync et Report State.

429 : Ressource épuisée

Cause : Votre intégration a dépassé le quota qui lui est alloué.

Solution : suivez les instructions de la section "Étape 2a : Déboguer les problèmes de quota" du tableau de bord de gestion des quotas. Pour en savoir plus, vous pouvez également consulter Quotas et limites pour la maison connectée.

État de l'appareil : précision de l'état

Atteindre ou dépasser un taux de précision de l'état de 99,5% permet de garantir que les utilisateurs voient des résultats corrects lorsqu'ils consultent l'état des appareils ou utilisent des fonctionnalités d'IA comme Demander à Home. Si la précision de l'état est faible, il est possible que les automatisations ne se déclenchent pas et que les entrées de l'historique n'apparaissent pas au bon moment dans l'onglet "Activité" de GHA. Pour en savoir plus, consultez État du rapport.

Le tableau de bord de qualité effectue un suivi horaire à l'aide de deux métriques distinctes : Précision globale et Combinaison type/trait la plus basse.

1. Composants de précision

La métrique est dérivée d'échantillons pour lesquels Google peut vérifier l'état signalé par rapport à un résultat d'intention connu.

2. Métriques du tableau de bord (calcul horaire)

Le tableau de bord calcule la précision sur la base d'un intervalle d'une heure. Si une heure comporte moins de 100 échantillons au total (S_Total < 100), la précision pour cette heure est définie sur N/A.

Vue 1 : Précision globale (moyenne mondiale)

Cela représente la précision totale de votre intégration pour tous les types d'appareils et toutes les caractéristiques combinés. Il fournit une moyenne pondérée de l'état de santé de l'ensemble de votre écosystème.

• Calcul : précision totale de l'état sur tous les appareils / total de l'état sur tous les appareils.

Vue 2 : Combinaison type/trait la plus basse

Cela permet d'identifier la catégorie spécifique la moins fiable de votre intégration. Il empêche les appareils à volume élevé et de haute qualité de masquer les appareils à volume faible et de basse qualité. Par exemple, si vous avez un volume élevé de lumières avec une précision d'état supérieure à 99,5 %, mais un faible volume d'interrupteurs avec une faible précision d'état, cela met en évidence l'amélioration nécessaire au niveau des interrupteurs, qui peut être perdue dans une valeur moyenne.

• Calcul : minimum de la justesse de l'état / total de l'état pour toutes les combinaisons de traits/d'appareils.

3. Améliorer la précision de l'état et de l'intégrité des appareils

Des écarts se produisent lorsque l'état stocké dans le Home Graph ne correspond pas aux résultats d'une REQUÊTE en temps réel.

Erreurs "Champ manquant"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Cause : avec l'erreur DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD ou DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, l'ensemble des champs de charge utile diffère entre votre réponse QUERY et votre requête Report State pour le même appareil.

Solution : Assurez-vous que la structure des données est identique dans les deux chemins d'accès. Si un trait est inclus dans SYNC, les champs correspondants doivent être présents et cohérents dans les rapports proactifs et les requêtes réactives.

Erreurs "Inexact"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Cause : Pour l'erreur DETAILED_ACCURACY_RESULT_INACCURATE, il existe une différence entre la valeur renvoyée dans la réponse QUERY et la dernière valeur de l'état du rapport.

Solution : Assurez-vous que l'état du rapport est déclenché chaque fois que l'état d'un appareil change, et que l'état du rapport et la requête fournissent toujours les mêmes valeurs à jour et tous les champs requis pour maintenir la cohérence des données.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Cause : avec l'erreur DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, le partenaire a exécuté la commande avec succès, mais n'a pas renvoyé l'état de l'appareil mis à jour à Google.

Solution : Envoyez toujours une mise à jour Report State après l'exécution d'une commande afin que HomeGraph reçoive le nouvel état de l'appareil.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Cause : Pour l'erreur DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, aucun état n'a été reçu pour cet appareil (l'état est vide et l'horodatage indiqué est à l'époque), malgré les résultats de la requête qui fournissent l'état actuel. Cela indique que les mises à jour de l'état ne sont pas déclenchées, qu'elles n'atteignent pas HomeGraph ou que l'appareil ne signale pas correctement les transitions de son état de connectivité ou de fonctionnement.

Solution : Assurez-vous que l'état du rapport est déclenché et envoyé pour tous les changements d'état. Vérifiez que la logique du backend gère correctement les mises à jour de l'état, confirme la réussite de la diffusion à Google HomeGraph et garantit que l'appareil synchronise constamment son état pour que l'interface utilisateur et le moteur d'automatisation soient précis.