Te damos la bienvenida al Centro para desarrolladores de Google Home, el nuevo destino para aprender a desarrollar acciones para el hogar inteligente. Nota: Continuarás compilando acciones en la Consola de Actions.

Estado del informe

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.
Nota:

Report State es una función importante que permite que la acción Home informe proactivamente el estado más reciente del dispositivo del usuario a Google Home Graph rather than waiting for a QUERY intent..

Report State informa a Google los estados de los dispositivos del usuario con el agentUserId especificado asociado a ellos (enviado en la solicitud original SYNC). Cuando 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.

Sin Report State, dadas las luces de varios proveedores en una sala de estar, el comando Ok Google, ilumina mi sala de estar requiere resolver varios intents QUERY enviados a múltiples nubes, en lugar de buscar los valores de brillo actuales en función de lo que se informó anteriormente. Para obtener la mejor experiencia del usuario, Assistant necesita tener el estado actual de un dispositivo, sin necesidad de un recorrido de ida y vuelta.

Después de la SYNC inicial de un dispositivo, la plataforma envía un intent QUERY que reúne el estado del dispositivo para propagar Home Graph. Después de ese momento, 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 por 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.

Cómo comenzar

Para implementar Report State, sigue estos pasos:

Habilitar la API de Google HomeGraph

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

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

Crear una clave de cuenta de servicio

Sigue estas instrucciones para generar una clave de cuenta de servicio desde el Google Cloud Console:

Nota: Asegúrate de usar el proyecto de GCP correcto cuando realices estos pasos. Este es el proyecto que coincide con tu ID del proyecto de smart home.
  1. En la Google Cloud Console, ve a la página Crear clave de la cuenta de servicio.

    Ir a la página Crear clave de la cuenta de servicio
  2. En la lista Cuenta de servicio, selecciona Cuenta de servicio nueva.
  3. Ingresa un nombre en el campo Nombre de cuenta de servicio.
  4. Ingresa un ID en el campo ID de cuenta de servicio.
  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á a tu computadora un archivo JSON con la clave.

Llamar a la API

Selecciona una opción de las pestañas a continuación:

HTTP

Home Graph proporciona un extremo HTTP.

  1. Usa el archivo JSON descargado de la cuenta de servicio para crear un token web JSON (JWT). Para obtener más información, consulta Autentica mediante una cuenta de servicio.
  2. Obtén un token de acceso de OAuth 2.0 con el permiso https://www.googleapis.com/auth/homegraph mediante oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crea la solicitud JSON con el agentUserId. El siguiente es un ejemplo de solicitud JSON para el estado del informe y la notificación:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Combina el estado del informe y el JSON de la notificación con el token de tu solicitud HTTP POST al extremo de Google Home Graph. Aquí hay un ejemplo de cómo realizar la solicitud en la línea de comandos mediante curl, como una prueba:
  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 proporciona un extremo de gRPC.

  1. Obtén la definición del servicio de los búferes de protocolo para la API de Home Graph.
  2. Sigue la documentación de gRPC para desarrolladores a fin de generar stubs cliente para uno de los lenguajes compatibles.
  3. Llama al método ReportStateAndNotification.

Node.js

El cliente Node.js de las API de Google proporciona vinculaciones para la API de Home Graph.

  1. Inicializa el servicio google.homegraph con las credenciales predeterminadas de la aplicación.
  2. Llama al método reportStateAndNotification con ReportStateAndNotificationRequest. Muestra un Promise con el 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 vínculos a la API de Home Graph.

  1. Inicializa HomeGraphApiService con las credenciales predeterminadas de la aplicación.
  2. Llama al método reportStateAndNotification con ReportStateAndNotificationRequest. Muestra un objeto 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);
}
    

Estado del informe de prueba

Herramientas recomendadas para esta tarea

A fin de que tu acción esté lista para la certificación, es importante que pruebes Report State.

Para hacerlo, recomendamos usar la herramienta de visualizador Home Graph, que es una aplicación web independiente que no requiere descargas ni implementaciones.

El panel Report State todavía está disponible, pero es obsoleto y ya no es compatible.

Informar sobre el panel de estado

Requisitos previos

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

Implemente el panel Report State

Una vez que tengas la clave de la cuenta de servicio y el ID de usuario del agente para el proyecto, descarga y, luego, implementa la versión más reciente desde el Report Statepanel. 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 del proyecto):

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

En el panel, haz lo siguiente:

  • Elegir el archivo de clave de la cuenta
  • Agrega tu userUserId

Luego, haz clic en Lista.

Se mostrarán todos los dispositivos. Una vez que se propague 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 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 la sintaxis no válida. Las causas comunes incluyen JSON con formato incorrecto o el uso de null en lugar de "" para un valor de string.
  • 404 Not Found: no se pudo encontrar el recurso solicitado, pero podría 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 con Google o que recibimos un agentUserId no válido. Asegúrate de que agentUserId coincida con el valor proporcionado en tu respuesta SYNC y de que manejes los intents DISCONNECT de forma correcta.