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.
.

El informe de estado es una función importante que permite a la acción de casa inteligente informar proactivamente sobre el estado más reciente del dispositivo del usuario en el Home Graph de Google, en lugar de esperar un intent QUERY.

Informa a Google los estados de los dispositivos de los usuarios con el agentUserId especificado asociado (enviado en la solicitud original SYNC). Cuando Asistente de Google quiere realizar una acción que requiere comprender el estado actual de un dispositivo, puede buscar la información de estado en el Home Graph en lugar de emitir un intent QUERY para varias nubes de terceros antes de emitir el intent EXECUTE.

Sin el estado de informe, dadas las luces de varios proveedores en una sala de estar, el comando Ok Google, iluminar mi sala de estar requiere resolver varios intents QUERY enviados a múltiples nubes, en lugar de solo buscar los valores de brillo actuales según lo que se informó antes. Para obtener la mejor experiencia del usuario, Asistente de Google debe tener el estado actual de un dispositivo, sin requerir un recorrido de ida y vuelta.

Después del SYNC inicial para un dispositivo, la plataforma envía un intent QUERY que recopila el estado del dispositivo a fin de propagar el gráfico de la página principal. Después de ese punto, Home Graph solo almacena el estado que se envía con el estado del informe.

Cuando llames a State State, asegúrate de proporcionar datos de estado completos para una característica en particular. Home Graph actualiza los estados por característica y reemplaza todos los datos de esa característica cuando se realiza una llamada de estado de informe. Por ejemplo, si informas el estado de la característica StartStop, la carga útil debe incluir valores para isRunning y isPaused.

Comienza ahora

Para implementar el estado del informe, siga estos pasos:

Habilita la API de Google HomeGraph

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

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

Crea una clave de cuenta de servicio

Sigue estas instrucciones para generar una clave de cuenta de servicio desde GCP 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 casa inteligente.
  1. En GCP Console, ve a la página Crea una 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. En el campo ID de cuenta de servicio, ingresa un ID.
  5. En la lista Función, selecciona Cuentas de servicio > Creador de tokens para cuenta de servicio.

  6. Para el 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 siguientes pestañas:

HTTP

La API de 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 con 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 agentUserId. Esta es una solicitud JSON de muestra 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 JSON del informe y el JSON de la notificación y el token en tu solicitud HTTP POST al extremo del grafo de Google Home. A continuación, te mostramos un ejemplo de cómo realizar la solicitud en la línea de comandos con curl, como 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

La API de Home Graph proporciona un extremo de gRPC

  1. Obtén la definición del servicio del búfer de protocolo para la API de Home Graph.
  2. Sigue la documentación para desarrolladores de gRPC a fin de generar stubs de clientes de 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 Promise 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 con la API de Home Graph.

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

A fin de preparar tu acción para la certificación, es importante probar el estado del informe.

Requisitos previos

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

Implementa el panel de estado del informe

Una vez que tengas la clave de la cuenta de servicio y el agenteUserId para tu proyecto, descarga y, luego, implementa la versión más reciente desde el panel de estado de informes. 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:

  • Elige el archivo de claves de tu cuenta
  • Agrega tu userUserId

Luego, haga clic en Lista.

Se mostrarán todos tus 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 al estado del informe. 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. Las causas comunes incluyen JSON con formato incorrecto o usar null en lugar de "" para un valor de string.
  • 404 Not Found: 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 agentUserId coincida con el valor proporcionado en tu respuesta SYNC y de que manejes los intents DISCONNECT de forma correcta.