Bienvenue dans le Centre des développeurs Google Home, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque : Vous continuerez à créer des actions dans la console Actions.

Signaler l'état

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
:

Report State est une fonctionnalité importante qui permet à l'action Home de signaler de manière proactive l'état le plus récent de l'appareil de l'utilisateur à Google Home Graph rather than waiting for a QUERY intent.

Report State signale à Google les états des appareils des utilisateurs auxquels est associé l'identifiant agentUserId spécifié (envoyé dans la requête SYNC d'origine). Quand Google Assistant wants to take an action that requires understanding the current state of a device, it can simply look up the state information in the Home Graph instead of issuing a QUERY intent to various third-party clouds prior to issuing the EXECUTE intent.

Sans Report State, étant donné que les lumières de plusieurs fournisseurs d'un salon, la commande Ok Google, éclaire mon salon nécessite la résolution de plusieurs intents QUERY envoyés à plusieurs clouds, au lieu de rechercher simplement les valeurs de luminosité actuelles sur la base 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 effectuer d'aller-retour.

Après le SYNC initial d'un appareil, la plate-forme envoie un intent QUERY qui rassemble 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, assurez-vous de fournir des données d'état complètes pour une caractéristique donnée. Home Graph met à jour les états par caractéristique et écrase toutes les données de cette caractéristique lors d'un appel Report State. Par exemple, si vous générez un rapport d'état pour la caractéristique StartStop, la charge utile doit inclure des valeurs à la fois pour isRunning et isPaused.

Commencer

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

Activer l'API Google HomeGraph

  1. Dans le Google Cloud Console , go to the HomeGraph API page.

    Accéder à la page de l'API HomeGraph
  2. Sélectionnez le projet correspondant à votre smart home project ID.
  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:

Remarque : Veillez à utiliser le bon projet GCP lorsque vous effectuez ces étapes. Il s'agit du projet correspondant à votre ID de projet smart home.
  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 de compte de service, saisissez un ID.
  5. Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons du 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:

HTTP

Home Graph fournit un point de terminaison HTTP

  1. Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez la page S'authentifier à l'aide d'un compte de service.
  2. Obtenez un jeton d'accès OAuth 2.0 avec le champ d'application https://www.googleapis.com/auth/homegraph à l'aide de oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Créez la requête JSON avec agentUserId. Voici un exemple de requête JSON pour l'état et la notification des rapports:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Combinez les données JSON "State Report" et "Notification" avec le jeton de votre requête HTTP POST au point de terminaison Google Home Graph. Voici un exemple d'envoi de requête dans la ligne de commande à l'aide de curl, à des fins de test:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

Home Graph fournit un point de terminaison gRPC

  1. Obtenez la définition de service de tampons de protocole pour l'API Home Graph.
  2. Suivez la documentation pour les développeurs gRPC afin de générer des simulations de client pour l'un des langages compatibles.
  3. Appelez la méthode ReportStateAndNotification.

Node.js

Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.

  1. Initialisez le service google.homegraph à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Elle renvoie un Promise avec ReportStateAndNotificationResponse.
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
          }
        }
      }
    }
  }
});
    

Java

La bibliothèque cliente de l'API HomeGraph pour Java fournit des liaisons pour l'API Home Graph.

  1. Initialisez HomeGraphApiService à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Elle renvoie un ReportStateAndNotificationResponse.
  // 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

Outils recommandés pour cette tâche

Pour préparer la certification à l'action, il est important de tester Report State.

Pour ce faire, nous vous recommandons d'utiliser l'outil Home Graph, 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 obsolète et n'est plus compatible.

Tableau de bord sur l'état des rapports

Prérequis

Avant de pouvoir tester votre action, vous avez besoin de votre clé de compte de service et de votre agentUserId. Si vous possédez déjà votre clé de compte de service et agentUserId, consultez Déployer le tableau de bord Report State.

Déployer le tableau de bord d'état du rapport

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 depuis le tableau de bord Report State. Une fois la dernière version téléchargée, suivez les instructions du fichier README.MD inclus.

Après avoir déployé le tableau de bord Report State, accédez au tableau de bord à partir de l'URL suivante (remplacez your_project_id par votre ID de projet):

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

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

  • Choisir un fichier de clé de compte
  • Ajoutez votre user-agent agent

Cliquez ensuite sur Liste.

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

Réponses aux erreurs

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. Parmi les causes courantes, on peut citer le format 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 peut être disponible à l'avenir. En général, cela signifie que nous ne pouvons pas trouver 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 DISSOCIER.