Stato rapporto

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

Report State segnala a Google gli stati dei dispositivi utente con il agentUserId specificato associato (inviato nella richiesta originale SYNC). 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 a vari cloud di terze parti prima di emettere l'intent EXECUTE.

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

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

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

Inizia

Per implementare Report State:

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

Abilita l'API Google HomeGraph

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

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

Crea una chiave dell'account di servizio

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

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

   Vai alla pagina Account di servizio.

   Prima di accedere alla pagina Service account, potrebbe essere necessario selezionare un progetto.

2. Fai clic su addCrea service account.

3. Nel campo Nome service account, inserisci un nome.

4. Nel campo ID service account, 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 Service account > Service Account OpenID Connect Identity Token Creator.

8. Fai clic su Continua.

9. Fai clic su Fine.

10. Seleziona il service account che hai appena creato dall'elenco dei service account 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 di seguito:

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

Testare Report State

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

A questo scopo, ti consigliamo di utilizzare lo strumento Viewer 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 Report State

Prerequisiti

Prima di poter testare l'integrazione Cloud-to-cloud, devi disporre della chiave dell'account di servizio e del tuo agentUserId. Se hai già la chiave dell'account di servizio e agentUserId consulta Eseguire il deployment della Report State dashboard.

Eseguire il deployment della dashboard Report State

Dopo aver ottenuto la chiave dell'account di servizio e l'ID utente agente per il tuo progetto, scarica ed esegui il deployment dell'ultima versione da Report State Dashboard. Dopo aver scaricato 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 l'ID progetto):

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

Nella dashboard:

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

Quindi, fai clic su Elenca.

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 di un dispositivo cambia, la riga viene evidenziata in verde.

Discrepanze di Report State

L'accuratezza dello stato del report basata sulle query misura la corrispondenza tra l'ultimo stato del report per un dispositivo e lo stato del dispositivo quando un utente esegue una query. Questo valore dovrebbe essere pari al 99,5%. Per maggiori dettagli sullo stato attuale dell' accuratezza di Report State del tuo progetto, consulta Integrità del dispositivo - Accuratezza dello stato. Puoi anche visualizzare i dettagli del log delle discrepanze di Report State da Esplora log.

Ecco un esempio di log delle discrepanze di 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"
}

Definizioni dei campi del log delle discrepanze di Report State

Risposte di errore

Quando chiami Report State, potresti ricevere una delle seguenti risposte di errore. Queste risposte sono in 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 : la risorsa richiesta non è stata trovata, ma potrebbe essere disponibile in futuro. In genere, 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 il agentUserId corrisponda al valore fornito nella risposta SYNC e che gestisci correttamente gli intent DISCONNECT.

Generazione di 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": {},
        }
      }
    }