Stato rapporto

Report State è una funzionalità importante che consente all'azione Google 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 comunica a Google gli stati dei dispositivi utente con il agentUserId specificato associato (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é emettere un intent QUERY in vari cloud di terze parti prima di emettere l'intent EXECUTE.

Senza Report State, date le luci di più fornitori in un soggiorno, il comando Ok Google, illumina il soggiorno richiede la risoluzione di più intenti QUERY inviati a più cloud, anziché semplicemente la ricerca dei valori di luminosità correnti in base a quanto è stato segnalato in precedenza. Per una migliore esperienza utente, Assistant deve conoscere lo stato attuale di un dispositivo, senza richiedere un viaggio di andata e ritorno al dispositivo.

Dopo la SYNC iniziale per un dispositivo, la piattaforma invia un intent QUERY che raccoglie lo stato del dispositivo per compilare Home Graph. Dopo questo punto, Home Graph memorizza solo lo stato inviato con Report State.

Quando chiami Report State, assicurati di fornire dati di stato completi per una determinata caratteristica. Home Graph aggiorna gli stati in base alla caratteristica e sovrascrive tutti i dati per quella caratteristica quando viene effettuata una chiamata Report State. Ad esempio, se stai segnalando lo stato per la caratteristica StartStop, il payload deve includere valori sia per isRunning che per isPaused.

Inizia

Per implementare Report State, segui questi passaggi:

• Abilita l'API Google HomeGraph
• Crea una chiave dell'account di servizio
• Chiama l'API

Abilita l'API Google HomeGraph

1. In Google Cloud Console, vai alla pagina 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.

Crea una chiave del service account

Segui queste istruzioni per generare una chiave del service account da Google Cloud Console:

1. In Google Cloud Console, vai alla pagina Service account.

   Vai alla pagina Service account.

   Potresti dover selezionare un progetto prima di accedere alla pagina Service Account.

2. Fai clic su addCrea service account.

3. Nel campo Nome account di servizio, inserisci un nome.

4. Nel campo ID account di servizio, inserisci un ID.

5. Nel campo Descrizione service account, inserisci una descrizione.

6. Fai clic su Crea e continua.

7. Dal menu a discesa Ruolo, seleziona Account di servizio > Service Account OpenID Connect Identity Token Creator.

8. Fai clic su Continua.

9. Fai clic su Fine.

10. Seleziona l'account di servizio appena creato dall'elenco degli account di servizio e seleziona Gestisci chiavi dal menu more_vert Azioni.

11. Seleziona Aggiungi chiave > Crea nuova chiave.

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

13. 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 del test

Per preparare l'integrazione di Cloud-to-cloud per la certificazione, è importante testare Report State.

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

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

Dashboard Stato report

Prerequisiti

Prima di poter testare l'integrazione di Cloud-to-cloud, devi disporre della chiave dell'account di servizio e di agentUserId. Se hai già la chiave del service account e agentUserId, vedi Deploy the Report State Dashboard.

Esegui il deployment della dashboard Stato report

Una volta ottenuti la chiave dell'account di servizio e l'ID utente agente per il tuo progetto, scarica e implementa l'ultima versione dalla Report State dashboard. Una volta scaricata l'ultima versione, segui le istruzioni riportate nel file README.MD incluso.

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

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

Nella dashboard:

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

Quindi, fai clic su Elenco.

Vengono elencati tutti i tuoi dispositivi. Una volta compilato l'elenco, puoi utilizzare il pulsante Aggiorna per aggiornare gli stati dei dispositivi. Se lo stato del dispositivo cambia, la riga viene evidenziata in verde.

Segnala discrepanza nello stato

L'accuratezza dello stato dei report basati su query misura il grado di corrispondenza tra lo stato più recente del report per un dispositivo e lo stato del dispositivo quando un utente esegue una query. Questo valore dovrebbe essere pari al 99,5%.

Risposte di errore

Quando chiami Report State, potresti ricevere una delle seguenti risposte di errore. Queste risposte si presentano sotto forma di codici di stato HTTP.

• 400 Bad Request - Il server non è riuscito a 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 stringa.
• 404 Not Found - Impossibile 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 tu gestisca correttamente gli intent DISCONNECT.

Report sullo stato online e offline

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