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 meldet, anstatt auf einen QUERY-Intent zu warten.

Report State meldet Google die Status der Nutzergeräte mit den angegebenen agentUserId, die ihnen zugeordnet sind (gesendet in der ursprünglichen SYNC-Anfrage). Wenn Google Assistant eine Aktion ausführen möchte, für die der aktuelle Status eines Geräts bekannt sein muss, kann es die Statusinformationen einfach im Home Graph nachschlagen, anstatt einen QUERY-Intent an verschiedene Drittanbieter-Clouds zu senden, bevor der EXECUTE-Intent gesendet wird.

Ohne Report State erfordert der Befehl Hey Google, mach das Licht im Wohnzimmer heller bei Lampen von mehreren Anbietern in einem Wohnzimmer das Auflösen 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 Anfrage an das Gerät gesendet werden muss.

Nach dem ersten SYNC für ein Gerät sendet die Plattform einen QUERY-Intent, der 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.

Achten Sie beim Aufrufen von Report State darauf, vollständige Statusdaten für eine bestimmte Eigenschaft anzugeben. Home Graph aktualisiert die Status pro Attribut und überschreibt alle Daten für dieses Attribut, wenn ein Report State-Aufruf erfolgt. Wenn du beispielsweise den Status für das Attribut StartStop meldest, muss die Nutzlast Werte für 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 HomeGraph API-Seite
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 des OpenID Connect-Identitätstokens für das Dienstkonto aus.

8. Klicken Sie auf Weiter.

9. Klicken Sie auf Fertig.

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

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

12. Wählen Sie als 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();
}
    

Testberichtstatus

Damit deine Cloud-to-cloud-Integration für die Zertifizierung bereit ist, musst du Report State testen.

Wir empfehlen, dafür das Home Graph-Anzeigetool zu verwenden. Das ist eine eigenständige Webanwendung, die nicht heruntergeladen oder bereitgestellt werden muss.

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

Dashboard für den Berichtsstatus

Vorbereitung

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

Dashboard „Report State“ bereitstellen

Sobald Sie den Dienstkontoschlüssel und die Agent-Nutzer-ID für Ihr Projekt haben, laden Sie die neueste Version aus dem Report State-Dashboard herunter und stellen Sie sie bereit. Nachdem du die aktuelle Version heruntergeladen hast, folge der Anleitung in der enthaltenen README.MD-Datei.

Nachdem Sie das Dashboard Report State 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

Gehen Sie im Dashboard so vor:

• Kontoschlüsseldatei auswählen
• agentUserId hinzufügen

Klicken Sie dann auf Liste.

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

Abweichung beim Berichtsstatus

Die Genauigkeit des abfragebasierten Berichtsstatus gibt an, wie gut der neueste Berichtsstatus für ein Gerät mit dem Status des Geräts übereinstimmt, wenn ein Nutzer danach sucht. Dieser Wert wird voraussichtlich bei 99,5 % liegen. Weitere Informationen zum aktuellen Status der Genauigkeit der Statusmeldung deines Projekts findest du unter Gerätezustand – Genauigkeit der Statusmeldung. Sie können sich die Details des Report State Discrepancy Log auch im Log-Explorer ansehen.

Hier ein Beispiel für ein Report State Discrepancy Log:

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

Definitionen der Felder im Protokoll zu Abweichungen beim Berichtsstatus

Fehlerantworten

Beim Aufrufen von Report State erhalten Sie möglicherweise eine der folgenden Fehlerantworten. Diese Antworten werden in Form von HTTP-Statuscodes zurückgegeben.

400 Fehlerhafte Anfrage

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 Nicht gefunden

Die angeforderte Ressource wurde nicht gefunden, ist aber möglicherweise in Zukunft verfügbar. In der Regel bedeutet das, 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. Achte darauf, dass der agentUserId mit dem Wert in deiner SYNC-Antwort übereinstimmt und dass du DISCONNECT-Intents richtig verarbeitest.

Wenn ein ReportState-Aufruf mit dem Fehler 404 NOT_FOUND fehlschlägt, deutet dies auf eine Synchronisierungsabweichung zwischen deiner Cloud und Home Graph hin. Das kann passieren, wenn ein Gerät aus Home Graph entfernt wird oder ein Nutzer die Verknüpfung seines Kontos aufhebt.

So behandeln Sie 404-Fehler von Report State:

1. Nutzerkontostatus prüfen: Rufen Sie devices.sync für die agentUserId auf, die einen 404-Fehler zurückgegeben hat. So lässt sich feststellen, ob der Fehler das gesamte Nutzerkonto oder ein bestimmtes Gerät betrifft.
   • Wenn SYNC einen 404-Fehler zurückgibt, ist das Nutzerkonto nicht mehr mit Google verknüpft. Senden von „Status melden“ und „Synchronisierung anfordern“ für die Geräte dieses Nutzers beenden.
   • Wenn SYNC „200 OK“ zurückgibt, ist das Nutzerkonto noch verknüpft. Der Fehler „404“ ist also gerätespezifisch.
2. Geräteliste abgleichen: Wenn SYNC den Status „200 OK“ zurückgibt, musst du herausfinden, welche Geräte Google nicht mehr bekannt sind. Wir empfehlen, die Liste der Geräte, die Google für den Nutzer hat, mit Ihrer Gerätedatenbank zu vergleichen und Geräte in Ihrem System zu identifizieren, die nicht in der Liste von Google enthalten sind. Wenn ein Gerät mit Google synchronisiert werden soll, aber noch nicht für Google freigegeben ist, verwende SYNC, um sicherzustellen, dass das Gerät mit Google synchronisiert wird. Wenn die Verknüpfung eines Geräts mit Google aufgehoben werden soll, beende die Statusmeldung für dieses Gerät und fahre mit der Meldung für andere gültige Geräte unter dieser agentUserId fort.

Berichterstellung zum Online- und Offlinestatus

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