État du rapport

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

Report State signale à Google les états des appareils des utilisateurs auxquels le agentUserId spécifié 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 Home Graph au lieu d'émettre un intent QUERY à divers clouds tiers avant d'émettre l'intent EXECUTE.

Sans Report State, étant donné que les lumières de plusieurs fournisseurs se trouvent dans un salon, la commande Ok Google, éclaire 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é 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 l'SYNC initiale pour un appareil, la plate-forme envoie un intent QUERY qui collecte l'état de l'appareil pour renseigner Home Graph. À partir de ce moment-là, 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 par trait et écrase toutes les données de ce trait lorsqu'un appel Report State est effectué. Par exemple, si vous signalez l'état de la caractéristique 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 API HomeGraph.

   Accéder à la page de l'API HomeGraph
2. Sélectionnez le projet correspondant à votre ID de projet smart home.
3. Cliquez sur ENABLE (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 Google Cloud Console, accédez à la page Créer une clé de compte de service.

   Accéder à la page Créer une clé de compte de service
2. Dans la liste Compte de service, sélectionnez Nouveau 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 la liste Rôle, sélectionnez Comptes de service > Créateur de jetons de compte de service.

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

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

É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 Home Graph Viewer, qui est une application Web autonome qui ne nécessite 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 de l'état des rapports

Prérequis

Avant de pouvoir tester votre intégration Cloud-to-cloud, 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 de agentUserId, consultez Déployer le tableau de bord Report State.

Déployer le tableau de bord "État des rapports"

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 depuis le 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 que vous avez déployé le tableau de bord Report State, 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

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

• Choisir votre fichier de clé de compte
• Ajouter votre agentUserId

Cliquez ensuite sur List (Liste).

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

Réponses d'erreur

L'une des réponses d'erreur suivantes peut s'afficher 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 incorrecte. 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 n'a pas été trouvée, mais elle pourrait l'être à l'avenir. Cela signifie généralement 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.