Stato rapporto

Report State è una funzionalità importante che consente all'azione Home di segnalare in modo proattivo lo stato più recente del dispositivo dell'utente a Google Home Graph anziché attendere un intent QUERY.

Report State segnala a Google gli stati dei dispositivi degli utenti a cui è associato il valore agentUserId specificato (inviato nella richiesta SYNC originale). Quando Google Assistant vuole intraprendere un'azione che richiede la comprensione dello stato attuale di un dispositivo, può semplicemente cercare le informazioni sullo stato in Home Graph anziché inviare un intent QUERY a vari cloud di terze parti prima di inviare l'intent EXECUTE.

Senza Report State, date le luci di più fornitori in un salotto, il comando Hey Google, illumina il mio salotto richiede la risoluzione di più intent QUERY inviati a più cloud, anziché semplicemente controllare i valori di luminosità correnti in base a quanto è stato segnalato in precedenza. Per una migliore esperienza utente, Assistant deve avere lo stato attuale di un dispositivo, senza richiedere un round trip.

Dopo il valore SYNC iniziale di un dispositivo, la piattaforma invia un intent QUERY che raccoglie lo stato del dispositivo per compilare Home Graph. Dopodiché, Home Graph memorizza solo lo stato inviato con Report State.

Quando chiami Report State, assicurati di fornire dati completi sullo stato per un determinato trait. Home Graph aggiorna gli stati in base al trait e sovrascrive tutti i dati per quel tratto quando viene effettuata una chiamata a Report State. Ad esempio, se stai segnalando lo stato per il tratto StartStop, il payload deve includere i valori sia per isRunning che per isPaused.

Inizia

Per implementare Report State:

• Abilita l'API Google HomeGraph
• Creare una chiave dell'account di servizio
• Chiamare l'API

Attiva l'API Google HomeGraph

1. In Google Cloud Console, vai alla pagina dell'API HomeGraph.

   Vai alla pagina dell'API HomeGraph
2. Seleziona il progetto che corrisponde al tuo ID progetto smart home.
3. Fai clic su ABILITA.

Creare una chiave dell'account di servizio

Segui queste istruzioni per generare una chiave dell'account di servizio dal Google Cloud Console:

1. In Google Cloud Console, vai alla pagina Crea chiave account di servizio.

   Vai alla pagina Crea chiave dell'account di servizio
2. Dall'elenco Account di servizio, seleziona Nuovo account di servizio.
3. Inserisci un nome nel campo Nome account di servizio.
4. Nel campo ID account di servizio, inserisci un ID.

5. Nell'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.

6. In Tipo di chiave, seleziona l'opzione JSON.

7. Fai clic su Crea. Un file JSON contenente la chiave viene scaricato sul computer.

Chiama l'API

Seleziona un'opzione dalle schede seguenti:

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

Stato del report di test

Per preparare l'azione per la certificazione, è importante testare Report State.

Per farlo, consigliamo di utilizzare lo strumento Visualizzatore Home Graph, un'app web autonoma che non richiede download o deployment.

La dashboard Report State è ancora disponibile, ma è stata ritirata e non è più supportata.

Dashboard dello stato dei report

Prerequisiti

Per poter testare l'azione, devi avere bisogno della chiave dell'account di servizio e di agentUserId. Se hai già la chiave dell'account di servizio e agentUserIdconsulta Eseguire il deployment della Report StateDashboard.

Eseguire il deployment della dashboard dello stato del report

Dopo aver ottenuto la chiave dell'account di servizio e l'ID utente agente per il tuo progetto, scarica la versione più recente dalla Report State dashboard ed eseguine il deployment. Una volta scaricata l'ultima versione, segui le istruzioni del file README.MD incluso.

Dopo aver eseguito il deployment della dashboard Report State, accedi alla dashboard dal seguente URL (sostituisci your_project_id con l'ID del tuo progetto):

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

Nella dashboard, procedi nel seguente modo:

• Scegli il file della chiave dell'account
• Aggiungi il tuo agentUserId

Poi, fai clic su Elenco.

Sono elencati tutti i tuoi dispositivi. Una volta che l'elenco è compilato, puoi utilizzare il pulsante Aggiorna per aggiornare gli stati del dispositivo. In caso di modifica dello stato del dispositivo, la riga è evidenziata in verde.

Risposte di errore

Potresti ricevere una delle seguenti risposte di errore quando chiami Report State. Queste risposte si presentano sotto forma di codici di stato HTTP.

• 400 Bad Request - Il server non è stato in grado di elaborare la richiesta inviata dal client a causa di una sintassi non valida. Le cause comuni includono JSON non valido o l'utilizzo di null anziché "" per un valore di stringa.
• 404 Not Found - Non è stato possibile trovare la risorsa richiesta, ma potrebbe essere disponibile in futuro. In genere, questo significa che non riusciamo a trovare il dispositivo richiesto. Potrebbe anche significare che l'account utente non è collegato a Google o che abbiamo ricevuto un agentUserId non valido. Assicurati che agentUserId corrisponda al valore fornito nella risposta SYNC e che gestisci correttamente gli intent DISCONNECT.