Berichtsstatus

Report State ist eine wichtige Funktion, mit der die Google Home Aktion den aktuellen Status des Geräts des Nutzers proaktiv an Google Home Graph zurückmelden kann, anstatt auf eine QUERY Absicht zu warten.

Report State meldet Google die Status von Nutzergeräten mit der angegebenen agentUserId verknüpft ist (in der ursprünglichen SYNC Anfrage). Wenn Google Assistant eine Aktion ausführen möchte für die der aktuelle Status eines Geräts erforderlich ist, kann er die Statusinformationen einfach in Home Graph nachschlagen, anstatt vor dem Senden der EXECUTE-Absicht eine QUERY-Absicht an verschiedene Clouds von Drittanbietern zu senden.

Ohne Report State erfordert der Befehl Hey Google, mach mein Wohnzimmer heller bei Lampen von mehreren Anbietern in einem Wohnzimmer die Auflösung mehrerer QUERY-Intents, die an mehrere Clouds gesendet werden, anstatt einfach die aktuellen Helligkeitswerte basierend auf den zuvor gemeldeten Werten nachzuschlagen. Für eine optimale Nutzererfahrung muss Assistant den aktuellen Status eines Geräts kennen, ohne dass eine Round-Trip-Kommunikation mit dem Gerät erforderlich ist.

Nach der ersten SYNC für ein Gerät sendet die Plattform eine QUERY-Absicht , die den Status des Geräts erfasst, um Home Graph zu füllen. Danach speichert Home Graph nur den Status, der mit Report State gesendet wird.

Wenn Sie Report State aufrufen, müssen Sie vollständige Statusdaten für ein bestimmtes Merkmal angeben. Home Graph aktualisiert die Status auf Merkmalsbasis und überschreibt alle Daten für dieses Merkmal, wenn ein Report State Aufruf erfolgt. StartStopmal „StartStop“ melden, muss die Nutzlast Werte für beide isRunning und isPaused enthalten.

Jetzt starten

So implementieren Sie Report State:

• Google HomeGraph API aktivieren
• Dienstkontoschlüssel erstellen
• API aufrufen

Google HomeGraph API aktivieren

1. Rufen Sie in der Google Cloud Console die Seite HomeGraph API auf.

   Zur Seite „HomeGraph API“
2. Wählen Sie das Projekt aus, das Ihrer smart home Projekt-ID entspricht.
3. Klicken Sie auf AKTIVIEREN.

Dienstkontoschlüssel erstellen

Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel über die Google Cloud Console zu generieren:

1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.

   Zur Seite „Dienstkonten“.

   Möglicherweise müssen Sie ein Projekt auswählen, bevor Sie zur Seite „Dienstkonten“ weitergeleitet werden.

2. Klicken Sie auf addDienstkonto erstellen.

3. Geben Sie im Feld Dienstkontoname einen Namen ein.

4. Geben Sie im Feld Dienstkonto-ID eine ID ein.

5. Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.

6. Klicken Sie auf Erstellen und fortfahren.

7. Wählen Sie im Drop-down-Menü Rolle die Option Dienstkonten > Ersteller von OpenID Connect-Identitätstokens für Dienstkonten aus.

8. Klicken Sie auf Weiter.

9. Klicken Sie auf Fertig.

10. Wählen Sie das gerade erstellte Dienstkonto in der Liste der Dienstkonten aus und wählen Sie Schlüssel verwalten im Menü more_vert Aktionen aus.

11. Wählen Sie Schlüssel hinzufügen > Neuen Schlüssel erstellen aus.

12. Wählen Sie für den Schlüsseltyp die Option JSON aus.

13. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

API aufrufen

Wählen Sie auf den Tabs unten eine Option aus:

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

„Berichtstatus“ testen

Damit Ihre Cloud-to-cloud Integration für die Zertifizierung bereit ist, ist es wichtig, Report State zu testen.

Dazu empfehlen wir das Tool Home Graph Viewer, eine eigenständige Webanwendung, für die kein Download oder keine Bereitstellung erforderlich ist.

Das Report State Dashboard ist weiterhin verfügbar, wurde aber eingestellt und wird nicht mehr unterstützt.

Dashboard „Berichtstatus“

Vorbereitung

Bevor Sie Ihre Cloud-to-cloud Integration testen können, benötigen Sie Ihren Dienstkontoschlüssel und Ihre agentUserId. Wenn Sie bereits Ihren Dienstkontoschlüssel und agentUserId haben, lesen Sie Dashboard Report State bereitstellen.

Dashboard „Berichtstatus“ bereitstellen

Sobald Sie den Dienstkontoschlüssel und die Agent-Nutzer-ID für Ihr Projekt haben, laden Sie die neueste Version von Report State Dashboardherunter und stellen Sie sie bereit. Nachdem Sie die neueste Version heruntergeladen haben, folgen Sie der Anleitung in der Datei README.MD.

Nachdem Sie das Report State Dashboard bereitgestellt haben, rufen Sie es über die folgende URL auf (ersetzen Sie your_project_id durch Ihre Projekt-ID):

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

Führen Sie auf dem Dashboard folgende Schritte aus:

• Wählen Sie Ihre Kontoschlüsseldatei aus.
• Fügen Sie Ihre agentUserId hinzu.

Klicken Sie dann auf Liste.

Alle Ihre Geräte werden aufgelistet. Sobald die Liste gefüllt ist, können Sie die Schaltfläche Aktualisieren verwenden, um die Gerätestatus zu aktualisieren. Wenn sich der Gerätestatus ändert, wird die Zeile grün hervorgehoben.

Abweichungen beim Berichtstatus

Die Genauigkeit des abfragebasierten Berichtstatus gibt an, wie gut der aktuelle Berichtstatus für ein Gerät mit dem Status des Geräts übereinstimmt, wenn ein Nutzer danach fragt. Dieser Wert sollte bei 99,5 % liegen. Weitere Informationen zum aktuellen Status der Genauigkeit des Berichtstatus Ihres Projekts finden Sie unter Gerätezustand – Statusgenauigkeit. Sie können die Details des Protokolls für Abweichungen beim Berichtstatus auch im Log-Explorer aufrufen.

Hier ist ein Beispiel für ein Protokoll für Abweichungen beim Berichtstatus:

{
  "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"
}

Felddefinitionen für das Protokoll für Abweichungen beim Berichtstatus

Fehlerantworten

Beim Aufrufen von Report State kann eine der folgenden Fehlerantworten zurückgegeben werden. Diese Antworten werden in Form von HTTP-Statuscodes gesendet.

• 400 Bad Request - Der Server konnte die vom Client gesendete Anfrage aufgrund einer ungültigen Syntax nicht verarbeiten. Häufige Ursachen sind fehlerhaftes JSON oder die Verwendung von null anstelle von "" für einen Stringwert.
• 404 Not Found - Die angeforderte Ressource wurde nicht gefunden, ist aber möglicherweise in Zukunft verfügbar. In der Regel bedeutet dies, dass wir das angeforderte Gerät nicht finden können. Es kann auch bedeuten, dass das Nutzerkonto nicht mit Google verknüpft ist oder wir eine ungültige agentUserId erhalten haben. Achten Sie darauf, dass die agentUserId mit dem in Ihrer SYNC Antwort angegebenen Wert übereinstimmt und dass Sie DISCONNECT Absichten ordnungsgemäß verarbeiten.

Online- und Offline-Statusberichte

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