Report State est une fonctionnalité importante qui permet à l'action 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 l'état des appareils des utilisateurs auxquels l'élément agentUserId
spécifié est associé (envoyé dans la requête SYNC
d'origine). Lorsque Google Assistant souhaite effectuer une action nécessitant de comprendre l'état actuel d'un appareil, il peut simplement rechercher les informations d'état dans Home Graph au lieu d'envoyer un intent QUERY
à différents clouds tiers avant d'émettre l'intent EXECUTE
.
Sans Report State, étant donné que les ampoules de plusieurs fournisseurs sont présentes dans un salon, la commande Ok Google, éclaircir mon salon nécessite de résoudre plusieurs intents QUERY
envoyés à plusieurs clouds, au lieu de simplement rechercher les valeurs de luminosité actuelles d'après ce qui a été précédemment signalé. Pour une expérience utilisateur optimale, Assistant doit connaître l'état actuel d'un appareil, sans qu'un aller-retour ne soit nécessaire.
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.
Ensuite, 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 une caractéristique donnée. 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 à la fois pour isRunning
et isPaused
.
Premiers pas
Pour implémenter Report State, procédez comme suit:
Activer l'API Google HomeGraph
-
Dans Google Cloud Console, accédez à la page API HomeGraph.
Accéder à la page de l'API HomeGraph - Sélectionnez le projet qui correspond à l'ID de votre projet smart home.
- 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:
-
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 - Dans la liste Compte de service, sélectionnez Nouveau compte de service.
- Dans le champ Nom du compte de service, saisissez un nom.
- Dans le champ ID du compte de service, saisissez un ID.
Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons du compte de service.
Pour le type de clé, sélectionnez l'option JSON.
- 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
- Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez S'authentifier à l'aide d'un compte de service.
- Obtenez un jeton d'accès OAuth 2.0 avec le champ d'application
https://www.googleapis.com/auth/homegraph
à l'aide d'oauth2l: - Créez la requête JSON avec le
agentUserId
. Voici un exemple de requête JSON pour l'état du rapport et la notification: - Combinez les valeurs JSON d'état et de notification du rapport ainsi que le jeton dans votre requête HTTP POST adressée au point de terminaison Google Home Graph. Voici un exemple d'exécution de la requête dans la ligne de commande en utilisant
curl
comme test:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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.
- Obtenez la définition du service Protocol Buffers pour l'API Home Graph.
- Suivez la documentation gRPC pour les développeurs afin de générer des bouchons de client pour l'un des langages compatibles.
- Appelez la méthode ReportStateAndNotification.
Node.js
Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.
- Initialisez le service
google.homegraph
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
reportStateAndNotification
avec ReportStateAndNotificationRequest. Elle renvoie unPromise
avec la réponse 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.
- Initialisez
HomeGraphApiService
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
reportStateAndNotification
avec laReportStateAndNotificationRequest
. Elle renvoie unReportStateAndNotificationResponse
.
// 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
Afin de préparer votre action pour 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 pas de téléchargement ni de déploiement.
Le tableau de bord Report State est toujours disponible, mais est obsolète et n'est plus compatible.
Tableau de bord d'état du rapport
Conditions préalables
Avant de pouvoir tester votre action, 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 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-y à 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:
- Sélectionnez le fichier de clé de votre 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 l'état des appareils. En cas de changement d'état de l'appareil, la ligne est surlignée en vert.
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 le format JSON incorrect ou l'utilisation denull
au lieu de "" pour une valeur de chaîne.404 Not Found
: la ressource demandée est introuvable, mais elle pourrait l'être ultérieurement. En général, cela signifie que nous ne parvenons pas à trouver l'appareil demandé. Cela peut également signifier que le compte utilisateur n'est pas associé à Google ou que nous avons reçu unagentUserId
non valide. Assurez-vous queagentUserId
correspond à la valeur fournie dans votre réponse SYNC et que vous gérez correctement les intents DISCONNECT.