Report State es una función importante que permite que la acción Home informe de manera proactiva el estado más reciente del dispositivo del usuario a Google Home Graph, en lugar de esperar un intent QUERY
.
Report State informa a Google los estados de los dispositivos de los usuarios con el agentUserId
especificado asociado (enviado en la solicitud SYNC
original). Cuando Google Assistant quiere realizar una acción que requiere comprender el estado actual de un dispositivo, puede simplemente buscar la información de estado en Home Graph, en lugar de emitir un intent QUERY
a varias nubes de terceros antes de emitir el intent EXECUTE
.
Sin Report State, dadas las luces de varios proveedores de una sala de estar, el comando Hey Google, iluminar mi sala de estar requiere resolver varios intents QUERY
enviados a varias nubes, en lugar de solo buscar los valores de brillo actuales según lo que se informó antes. Para brindar la mejor experiencia del usuario, Assistant debe tener el estado actual de un dispositivo, sin requerir un recorrido de ida y vuelta a él.
Después del SYNC
inicial de un dispositivo, la plataforma envía un intent QUERY
que recopila el estado del dispositivo para propagar Home Graph.
Después de ese punto, Home Graph solo almacena el estado que se envía con Report State.
Cuando llames a Report State, asegúrate de proporcionar datos de estado completos para una característica determinada. Home Graph actualiza los estados por característica y reemplaza todos los datos de esa característica cuando se realiza una llamada a Report State. Por ejemplo, si informas el estado de la característica StartStop, la carga útil debe incluir valores para isRunning
y isPaused
.
Comenzar
Para implementar Report State, sigue estos pasos:
Cómo habilitar la API de Google HomeGraph
-
En Google Cloud Console, ve a la página API de HomeGraph.
Ir a la página de la API de HomeGraph - Selecciona el proyecto que coincida con tu ID del proyecto de smart home.
- Haz clic en HABILITAR.
Crea una clave de cuenta de servicio
Sigue estas instrucciones para generar una clave de cuenta de servicio desde Google Cloud Console:
-
En Google Cloud Console, ve a la página Crear clave de cuenta de servicio.
Ir a la página Crear clave de la cuenta de servicio - En la lista Cuenta de servicio, selecciona Nueva cuenta de servicio.
- Escribe un nombre en el campo Nombre de cuenta de servicio.
- En el campo ID de la cuenta de servicio, ingresa un ID.
En la lista Función, selecciona Cuentas de servicio > Creador de tokens para cuenta de servicio.
En Tipo de clave, selecciona la opción JSON.
- Haz clic en Crear. Se descargará a tu computadora un archivo JSON con la clave.
Llama a la API
Selecciona una opción de las siguientes pestañas:
HTTP
Home Graph proporciona un extremo HTTP.
- Usa el archivo JSON de la cuenta de servicio que descargaste para crear un token web JSON (JWT). Para obtener más información, consulta Autenticación con una cuenta de servicio.
- Obtén un token de acceso de OAuth 2.0 con el permiso
https://www.googleapis.com/auth/homegraph
mediante oauth2l: - Crea la solicitud JSON con el
agentUserId
. Este es un ejemplo de una solicitud JSON para el estado del informe y la notificación: - Combina el estado del informe y la notificación JSON, y el token de tu solicitud HTTP POST al extremo de Google Home Graph. A continuación, se muestra un ejemplo de cómo realizar la solicitud en la línea de comandos con
curl
como prueba:
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 proporciona un extremo de gRPC.
- Obtén la definición del servicio de búferes de protocolo para la API de Home Graph.
- Sigue la documentación para desarrolladores de gRPC con el objetivo de generar stubs de cliente para uno de los lenguajes compatibles.
- Llama al método ReportStateAndNotification.
Node.js
El cliente de Node.js de las APIs de Google proporciona vinculaciones para la API de Home Graph.
- Inicializa el servicio
google.homegraph
con las credenciales predeterminadas de la aplicación. - Llama al método
reportStateAndNotification
con ReportStateAndNotificationRequest. Muestra unPromise
con 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 biblioteca cliente de la API de HomeGraph para Java proporciona vinculaciones para la API de Home Graph.
- Inicializa
HomeGraphApiService
con las credenciales predeterminadas de la aplicación. - Llama al método
reportStateAndNotification
conReportStateAndNotificationRequest
. Muestra 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); }
Estado del informe de prueba
A fin de preparar tu acción para la certificación, es importante que pruebes Report State.
Para ello, te recomendamos que uses la herramienta Visualizador de Home Graph, que es una app web independiente que no requiere descarga ni implementación.
El panel de Report State aún está disponible, pero está obsoleto y ya no es compatible.
Panel de estado del informe
Requisitos previos
Para poder probar la acción, necesitas la clave de la cuenta de servicio y tu agentUserId
. Si ya tienes la clave de la cuenta de servicio y agentUserId
, consulta Implementa el panel de Report State.
Implementa el panel Report State
Una vez que tengas la clave de la cuenta de servicio y el ID de usuario del agente para tu proyecto,
descarga e implementa la versión más reciente desde el
Panel de Report State.
Una vez que hayas descargado la versión más reciente, sigue las instrucciones del archivo README.MD
incluido.
Después de implementar el panel de Report State, accede al panel desde la siguiente URL (reemplaza your_project_id por el ID del proyecto):
http://<your-project-id>.appspot.com
En el panel, haz lo siguiente:
- Elige el archivo de claves de tu cuenta
- Agrega tu agentUserId
Luego, haz clic en Lista.
Todos tus dispositivos aparecen en la lista. Una vez que se completa la lista, puedes usar el botón Actualizar para actualizar los estados del dispositivo. Si hay un cambio de estado del dispositivo, la fila se destaca en verde.
Respuestas de error
Es posible que recibas una de las siguientes respuestas de error cuando llames a Report State. Estas respuestas se presentan en forma de códigos de estado HTTP.
400 Bad Request
: el servidor no pudo procesar la solicitud que envió el cliente debido a una sintaxis no válida. Entre las causas comunes, se incluyen el formato JSON con formato incorrecto o el uso denull
en lugar de “” para un valor de cadena.404 Not Found
: no se pudo encontrar el recurso solicitado, pero es posible que esté disponible en el futuro. Por lo general, esto significa que no podemos encontrar el dispositivo solicitado. También puede significar que la cuenta de usuario no está vinculada con Google o que recibimos unagentUserId
no válido. Asegúrate de queagentUserId
coincida con el valor proporcionado en tu respuesta SYNC y que estás manejando correctamente los intents DISCONNECT.