État du rapport

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

Report State signale à Google les états des appareils utilisateur avec le agentUserId spécifié qui leur est associé (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 le Home Graph au lieu d'émettre une intent QUERY vers différents clouds tiers avant d'émettre l'intent EXECUTE.

Sans Report State, étant donné les lumières de plusieurs fournisseurs dans un salon, la commande Ok Google, éclaire mon salon nécessite de résoudre plusieurs intents QUERY envoyées à plusieurs clouds, au lieu de simplement rechercher les valeurs de luminosité actuelles en fonction de ce qui a été signalé précédemment. Pour une expérience utilisateur optimale, Assistant doit connaître l'état actuel d'un appareil, sans avoir à effectuer un aller-retour vers l'appareil.

Après la SYNC initiale d'un appareil, la plate-forme envoie une intent QUERY qui collecte l'état de l'appareil pour remplir Home Graph. À partir de ce moment, Home Graph ne stocke que l'état qui est 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 par trait et remplace toutes les données de ce trait lorsqu'un appel Report State est effectué. Par exemple, si vous signalez l'état du trait StartStop, la charge utile doit inclure des valeurs pour isRunning et isPaused.

Premiers pas

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 la Google Cloud Console, accédez à la page API HomeGraph.

   Accéder à la page de l'API HomeGraph
2. Sélectionnez le projet qui correspond à l'ID de votre 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 du 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 more_vert Actions menu.

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();
}
    

Tester Report State

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 Viewer Home Graph, qui est une application Web autonome qui ne nécessite aucun téléchargement ni déploiement.

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

Tableau de bord Report State

Prérequis

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

Déployer le tableau de bord Report State

Une fois que vous disposez de la clé de 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 de Report State Dashboard. Une fois la dernière version téléchargée, suivez les instructions du fichier README.MD inclus.

Une fois le tableau de bord Report State déployé, accédez au tableau de bord à partir 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 :

• Choisissez votre fichier de clé de compte.
• Ajoutez votre agentUserId.

Cliquez ensuite sur Liste.

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

Écart de Report State

La précision de l'état du rapport basé sur les requêtes mesure la correspondance entre le dernier état du rapport d'un appareil et son état lorsqu'un utilisateur l'interroge. Cette valeur doit ê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 de Report State

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 Bad Request : 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 JSON mal formé 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 pourra peut-être être disponible à l'avenir. En règle générale, 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 le agentUserId correspond à la valeur fournie dans votre SYNC et que vous gérez correctement les intents DISCONNECT.

Rapports d'é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": {},
        }
      }
    }