Informar estado

Report State es una función importante que permite que la Acción de Google Home informe de forma 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 a ellos (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 en una sala de estar, el comando Hey Google, aumenta el brillo de mi sala de estar requiere resolver varios intents QUERY enviados a varias nubes, en lugar de simplemente buscar los valores de brillo actuales según lo que se informó anteriormente. Para obtener la mejor experiencia del usuario, Assistant debe tener el estado actual de un dispositivo, sin necesidad de realizar un viaje 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 de estado completos para un atributo determinado. Home Graph actualiza los estados por atributo y reemplaza todos los datos de ese atributo cuando se realiza una llamada 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:

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

Habilita la API de Google HomeGraph

1. En la 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 tu ID del proyecto de 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 desde la Google Cloud Console:

1. En la Google Cloud Console, ve a la página Cuentas de servicio.

   Ir a la página Cuentas de servicio.

   Es posible que debas seleccionar un proyecto antes de que se te dirija a la página Cuentas de servicio.

2. Haz clic en addCrear cuenta de servicio.

3. Escribe un nombre en el campo Nombre de cuenta de servicio.

4. En el campo ID de cuenta de servicio, ingresa un ID.

5. Opcional: en el campo Descripción de la cuenta de servicio, escribe una descripción.

6. Haz clic en Crear y continuar.

7. En el menú desplegable Rol, selecciona Cuentas de servicio > Creador de tokens de identidad de OpenID Connect para cuentas de servicio.

8. Haz clic en Continuar.

9. Haz clic en Listo.

10. Selecciona la cuenta de servicio que acabas de crear de la lista de cuentas de servicio y elige Administrar claves en el menú more_vert Acciones.

11. Selecciona Agregar clave > Crear clave nueva.

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

13. Haz clic en Crear. Se descargará en tu computadora un archivo JSON que contiene tu 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).execute();
}
    

Estado del informe de prueba

Para preparar tu integración de Cloud-to-cloud para la certificación, es importante que pruebes Report State.

Para ello, te recomendamos que uses la herramienta de visualización 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 dejó de estar disponible y ya no es compatible.

Panel de estado de informes

Requisitos previos

Antes de poder probar tu integración de Cloud-to-cloud, necesitas tu clave de cuenta de servicio y tu agentUserId. Si ya tienes tu clave de cuenta de servicio y agentUserId, consulta Implementa el panel de Report State.

Implementa el panel de 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.

Se mostrarán todos tus dispositivos. Una vez que se complete la lista, puedes usar el botón Refresh para actualizar los estados de los dispositivos. Si hay un cambio en el estado del dispositivo, la fila se destaca en verde.

Informa una discrepancia de estado

La exactitud del estado del informe basado en consultas mide qué tan bien coincide el estado del informe más reciente de un dispositivo con el estado del dispositivo cuando un usuario lo consulta. Se espera que este valor sea del 99.5%. Para obtener más detalles sobre el estado actual de la precisión del estado del informe de tu proyecto, consulta Estado del dispositivo: Precisión del estado. También puedes ver los detalles del registro de discrepancias de Report State en el Explorador de registros.

Este es un ejemplo de un registro de discrepancias de Report State:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Definiciones de los campos del registro de discrepancias de estado del informe

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 un JSON con formato incorrecto o el uso de null en lugar de "" para un valor de cadena.

404 No encontrado

No se encontró 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 un agentUserId no válido. Asegúrate de que el agentUserId coincida con el valor proporcionado en tu respuesta de SYNC y de que estés controlando correctamente los intents de DISCONNECT.

Cuando una llamada a ReportState falla con un error 404 NOT_FOUND, indica un desajuste de sincronización entre tu nube y Home Graph. Esto puede suceder si se quita un dispositivo de Home Graph o si un usuario desvincula su cuenta.

Para controlar los errores 404 de Report State, usa el siguiente procedimiento:

1. Verifica el estado de la cuenta de usuario: Llama a devices.sync para el agentUserId que devolvió un error 404. Esto ayuda a determinar si el error es para toda la cuenta de usuario o para un dispositivo específico.
   • Si SYNC devuelve un error 404, la cuenta de usuario ya no está vinculada con Google. Deja de enviar Informar estado y Solicitar sincronización para los dispositivos de este usuario.
   • Si SYNC devuelve 200 OK, la cuenta de usuario aún está vinculada, lo que significa que el error 404 es específico del dispositivo.
2. Concilia la lista de dispositivos: Si SYNC devuelve 200 OK, debes identificar qué dispositivos ya no son conocidos para Google. Te recomendamos que compares la lista de dispositivos que Google tiene para el usuario con tu base de datos de dispositivos y que identifiques los dispositivos de tu sistema que no están en la lista de Google. Si un dispositivo se debe sincronizar con Google, pero aún no se comparte con Google, usa SYNC para asegurarte de que el dispositivo esté sincronizado con Google. Si un dispositivo se debe desvincular de Google, deja de informar el estado de ese dispositivo específico y sigue informando el de otros dispositivos válidos en ese agentUserId.

Informes de estado en línea y sin conexión

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }