Informar estado

Report State es una función importante que permite que la acción Home informe de forma proactiva el estado más reciente del dispositivo del usuario a Google Home Graph, en lugar de esperar a un intent QUERY.

Report State informa a Google los estados de los dispositivos de los usuarios con el agentUserId especificado asociado a ellos (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 Ok Google, ilumina 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 necesidad de un recorrido de ida y vuelta al dispositivo.

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 completos del estado de una característica dada. Home Graph actualiza los estados por trait 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:

• Habilitar la API de Google HomeGraph
• Crea una clave de cuenta de servicio
• Llama a la API

Cómo habilitar la API de Google HomeGraph

1. En Google Cloud Console, ve a la página de la API de HomeGraph.

   Ir a la página de la API de HomeGraph
2. Selecciona el proyecto que coincida con el ID del proyecto smart home.
3. Haz clic en HABILITAR.

Crea una clave de cuenta de servicio

Sigue estas instrucciones para generar una clave de cuenta de servicio a partir de Google Cloud Console:

1. En Google Cloud Console, ve a la página Crea una clave de cuenta de servicio.

   Ir a la página Crear clave de la cuenta de servicio
2. En la lista Cuenta de servicio, selecciona Nueva cuenta de servicio.
3. Ingresa un nombre en el campo Nombre de cuenta de servicio.
4. En el campo ID de cuenta de servicio, ingresa un ID.

5. En la lista Función, selecciona Cuentas de servicio > Creador de tokens de cuenta de servicio.

6. En Tipo de clave, selecciona la opción JSON.

7. Haz clic en Crear. Se descargará en tu computadora un archivo JSON con la clave.

Llama a la API

Selecciona una opción de las siguientes pestañas:

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

Estado del informe de prueba

A fin de preparar tu acción para la certificación, es importante probar Report State.

Para ello, te recomendamos usar la herramienta Visualizador de Home Graph, que es una app web independiente que no requiere descarga ni implementación.

El panel de Report State sigue disponible, pero está obsoleto y ya no es compatible.

Panel de estado de informes

Requisitos previos

Para poder probar la acción, necesitas tu clave de cuenta de servicio y tu agentUserId. Si ya tienes la clave de tu cuenta de servicio y agentUserId, consulta Implementa el panel Report State.

Implementa el panel Report State (Estado del informe)

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 Report State, accede al panel desde la siguiente URL (reemplaza your_project_id por el ID de tu proyecto):

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

En el panel, haz lo siguiente:

• Archivo de claves de la cuenta
• Agrega tu agentUserId

Luego, haz clic en Lista.

Aparecerán todos tus dispositivos. Una vez que se complete la lista, podrás 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 vienen 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 JSON con errores de formato o usar null en lugar de “” para un valor de string.
• 404 Not Found: No se pudo encontrar el recurso solicitado, pero puede estar 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 a Google o que recibimos un agentUserId no válido. Asegúrate de que el agentUserId coincida con el valor proporcionado en tu respuesta SYNC y de que controlas correctamente los intents DISCONNECT.