État du rapport

Report State est une fonctionnalité importante qui permet à l'action Google Home de signaler de manière proactive l'état le plus récent de l'appareil de l'utilisateur à Google Home Graph au lieu d'attendre un intent QUERY.

Report State indique à Google l'état des appareils des utilisateurs associés à l'agentUserId spécifié (envoyé dans la requête SYNC d'origine). Lorsque Google Assistant souhaite effectuer une action qui nécessite de comprendre l'état actuel d'un appareil, il peut simplement rechercher les informations d'état dans Home Graph au lieu d'émettre un intent QUERY vers différents clouds tiers avant d'émettre l'intent EXECUTE.

Sans Report State, si un salon est équipé de lumières provenant de plusieurs fournisseurs, la commande Ok Google, augmente la luminosité de mon salon nécessite de résoudre plusieurs intents QUERY envoyés à plusieurs clouds, au lieu de simplement rechercher les valeurs de luminosité actuelles en fonction de ce qui a été précédemment signalé. Pour une expérience utilisateur optimale, Assistant doit disposer de l'état actuel d'un appareil, sans nécessiter d'aller-retour vers l'appareil.

Après la requête SYNC initiale pour un appareil, la plate-forme envoie un intent QUERY qui collecte l'état de l'appareil pour renseigner Home Graph. Après cela, Home Graph ne stocke que l'état envoyé avec Report State.

Lorsque vous appelez Report State, veillez à fournir des données d'état complètes pour un trait donné. Home Graph met à jour les états trait par trait et écrase toutes les données de ce trait lorsqu'un appel Report State est effectué. Par exemple, si vous indiquez l'état du trait StartStop, la charge utile doit inclure des valeurs pour isRunning et isPaused.

Commencer

Pour implémenter Report State, procédez comme suit :

• Activer l'API Google HomeGraph
• Créer une clé de compte de service
• Appeler l'API

Activer l'API Google HomeGraph

1. Dans Google Cloud Console, accédez à la page de l'API HomeGraph.

   Accéder à la page de l'API HomeGraph
2. Sélectionnez le projet qui correspond à votre ID de projet smart home.
3. Cliquez sur ACTIVER.

Créer une clé de compte de service

Suivez ces instructions pour générer une clé de compte de service à partir de Google Cloud Console :

1. Dans la Google Cloud Console, accédez à la page Comptes de service.

   Accéder à la page "Comptes de service"

   Vous devrez peut-être sélectionner un projet avant d'accéder à la page "Comptes de service".

2. Cliquez sur addCréer un compte de service.

3. Dans le champ Nom du compte de service, saisissez un nom.

4. Dans le champ ID du compte de service, saisissez un ID.

5. Dans le champ Description du compte de service, saisissez une description.

6. Cliquez sur Créer et continuer.

7. Dans le menu déroulant Rôle, sélectionnez Comptes de service > Créateur de jetons d'identité OpenID Connect du compte de service.

8. Cliquez sur Continuer.

9. Cliquez sur OK.

10. Sélectionnez le compte de service que vous venez de créer dans la liste des comptes de service, puis sélectionnez Gérer les clés dans le menu more_vert Actions.

11. Sélectionnez Ajouter une clé > Créer une clé.

12. Pour Type de clé, sélectionnez l'option JSON.

13. Cliquez sur Créer. Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.

Appeler l'API

Sélectionnez une option dans les onglets ci-dessous :

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request).execute();
}
    

État du rapport de test

Pour préparer votre intégration Cloud-to-cloud à la certification, il est important de tester Report State.

Pour ce faire, nous vous recommandons d'utiliser l'outil de visualisation Home Graph, qui est une application Web autonome ne nécessitant ni téléchargement, ni déploiement.

Le tableau de bord Report State est toujours disponible, mais il est obsolète et n'est plus pris en charge.

Tableau de bord Report State

Prérequis

Avant de pouvoir tester votre intégration Cloud-to-cloud, vous devez disposer de votre clé de compte de service et de votre agentUserId. Si vous disposez déjà de votre clé de compte de service et de agentUserId, consultez Déployer le tableau de bord Report State.

Déployer le tableau de bord ReportState

Une fois que vous disposez de la clé du compte de service et de l'ID utilisateur de l'agent pour votre projet, téléchargez et déployez la dernière version à partir du tableau de bord Report State. Une fois que vous avez téléchargé la dernière version, suivez les instructions du fichier README.MD inclus.

Une fois le tableau de bord Report State déployé, accédez-y à l'aide de l'URL suivante (remplacez your_project_id par l'ID de votre projet) :

http://<your-project-id>.appspot.com

Dans le tableau de bord, procédez comme suit :

• Sélectionner le fichier de clé de votre compte
• Ajouter votre agentUserId

Cliquez ensuite sur Liste.

Tous vos appareils sont listés. Une fois la liste renseignée, vous pouvez utiliser le bouton Actualiser pour mettre à jour l'état des appareils. Si l'état de l'appareil change, la ligne est mise en surbrillance en vert.

Signaler un écart d'état

La précision de l'état du rapport basé sur une requête mesure la correspondance entre le dernier état du rapport d'un appareil et l'état de l'appareil lorsqu'un utilisateur l'interroge. Cette valeur devrait être de 99,5%. Pour en savoir plus sur l'état actuel de la précision de l'état du rapport de votre projet, consultez État de l'appareil – Précision de l'état. Vous pouvez également consulter les détails du journal des écarts de Report State dans l'explorateur de journaux.

Voici un exemple de journal des écarts de Report State :

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Définitions des champs du journal des écarts d'état des rapports

Réponses d'erreur

Vous pouvez recevoir l'une des réponses d'erreur suivantes lorsque vous appelez Report State. Ces réponses se présentent sous la forme de codes d'état HTTP.

400 Requête erronée

Le serveur n'a pas pu traiter la requête envoyée par le client en raison d'une syntaxe non valide. Les causes courantes incluent un fichier JSON incorrect ou l'utilisation de null au lieu de "" pour une valeur de chaîne.

404 Not Found

La ressource demandée est introuvable, mais elle sera peut-être disponible ultérieurement. En général, cela signifie que nous ne trouvons pas l'appareil demandé. Cela peut également signifier que le compte utilisateur n'est pas associé à Google ou que nous avons reçu un agentUserId non valide. Assurez-vous que agentUserId correspond à la valeur fournie dans votre réponse SYNC et que vous gérez correctement les intents DISCONNECT.

Lorsqu'un appel ReportState échoue avec une erreur 404 NOT_FOUND, cela indique une incohérence de synchronisation entre votre cloud et Home Graph. Cela peut se produire si un appareil est supprimé de Home Graph ou si un utilisateur dissocie son compte.

Pour gérer les erreurs 404 de Report State, procédez comme suit :

1. Vérifier l'état du compte utilisateur : appelez devices.sync pour l'agentUserId qui a renvoyé une erreur 404. Cela permet de déterminer si l'erreur concerne l'ensemble du compte utilisateur ou un appareil spécifique.
   • Si SYNC renvoie une erreur 404, le compte utilisateur n'est plus associé à Google. Arrêtez d'envoyer Report State et Request Sync pour les appareils de cet utilisateur.
   • Si SYNC renvoie le code 200 OK, le compte utilisateur est toujours associé, ce qui signifie que l'erreur 404 est spécifique à l'appareil.
2. Rapprocher la liste des appareils : si SYNC renvoie "200 OK", vous devez identifier les appareils qui ne sont plus connus de Google. Nous vous recommandons de comparer la liste des appareils dont Google dispose pour l'utilisateur avec votre base de données d'appareils, et d'identifier les appareils de votre système qui ne figurent pas dans la liste de Google. Si un appareil doit être synchronisé avec Google, mais qu'il n'est pas encore partagé avec Google, utilisez SYNC pour vous assurer que l'appareil est synchronisé avec Google. Si un appareil doit être dissocié de Google, arrêtez de signaler l'état de cet appareil spécifique et continuez à signaler l'état des autres appareils valides sous cet agentUserId.

Rapports sur l'état en ligne et hors connexion

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }