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 melden kann, anstatt auf eine QUERY-Absicht zu warten.

Report State meldet die Status der Nutzergeräte mit der angegebenen agentUserId, die ihnen zugeordnet ist, an Google (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 erforderlich ist, kann es die Statusinformationen einfach in Home Graph nachschlagen, anstatt vor dem Ausgeben des EXECUTE-Intents ein QUERY-Intent an verschiedene Drittanbieter-Clouds zu senden.

Ohne Report State erfordert der Befehl Hey Google, mach das Licht im Wohnzimmer heller bei mehreren Anbietern im Wohnzimmer die Auflösung mehrerer QUERY-Intents, die an mehrere Clouds gesendet werden, anstatt einfach die aktuellen Helligkeitswerte basierend auf den zuvor gemeldeten Werten abzurufen. Für eine optimale Nutzerfreundlichkeit muss Assistant den aktuellen Status eines Geräts kennen, ohne dass ein Roundtrip zum Gerät erforderlich ist.

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

Achten Sie beim Aufrufen von Report State darauf, dass Sie vollständige Statusdaten für ein bestimmtes Merkmal angeben. Home Graph aktualisiert Status auf Grundlage der einzelnen Eigenschaften und überschreibt alle Daten für diese Eigenschaft, wenn ein Report State-Aufruf erfolgt. Wenn Sie beispielsweise den Status für das StartStop-Trait melden, 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 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 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 eine Option aus den Tabs unten 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();
}
    

Testberichtsstatus

Damit Ihre Cloud-to-cloud-Integration für die Zertifizierung bereit ist, müssen Sie Report State testen.

Dazu empfehlen wir das Home Graph Viewer-Tool, eine eigenständige Web-App, die nicht heruntergeladen oder bereitgestellt werden muss.

Das Report State-Dashboard ist weiterhin verfügbar, aber veraltet 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 Ihren Dienstkontoschlüssel und agentUserId haben, lesen Sie den Abschnitt DashboardReport State bereitstellen.

Dashboard „Berichtstatus“ bereitstellen

Sobald Sie den Dienstkontoschlüssel und die Agent-Nutzer-ID für Ihr Projekt haben, laden Sie die aktuelle Version aus dem Report State-Dashboard herunter und stellen Sie sie bereit. Folgen Sie nach dem Herunterladen der neuesten Version der Anleitung in der enthaltenen README.MD-Datei.

Nachdem Sie das Report State-Dashboard bereitgestellt haben, können Sie über die folgende URL darauf zugreifen. Ersetzen Sie your_project_id durch Ihre Projekt-ID:

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

Gehen Sie im Dashboard so vor:

• Schlüsseldatei für Konto 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 Schaltfläche Aktualisieren verwenden, um die Gerätestatus zu aktualisieren. Wenn sich der Gerätestatus ändert, wird die Zeile grün hervorgehoben.

Statusabweichung melden

Die Genauigkeit des auf Abfragen basierenden Berichtsstatus gibt an, wie gut der aktuelle Berichtsstatus 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 Berichterstellung zur Statusgenauigkeit Ihres Projekts finden Sie unter Gerätezustand – Statusgenauigkeit. Sie können die Details des Berichtsprotokolls zu Abweichungen beim Status auch im Log-Explorer aufrufen.

Hier sehen Sie ein Beispiel für ein Protokoll zu Abweichungen im Berichtsstatus:

{
  "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 Diskrepanzen beim Berichtsstatus

Fehlerantworten

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

400 Fehlerhafte Anfrage

Der Server konnte die vom Client gesendete Anfrage aufgrund von ungültiger 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. Normalerweise bedeutet das, dass wir das angeforderte Gerät nicht finden können. Das kann auch bedeuten, dass das Nutzerkonto nicht mit Google verknüpft ist oder wir eine ungültige agentUserId erhalten haben. Achten Sie darauf, dass agentUserId mit dem in Ihrer SYNC-Antwort angegebenen Wert übereinstimmt und dass Sie DISCONNECT-Intents richtig verarbeiten.

Wenn ein ReportState-Aufruf mit dem Fehler 404 NOT_FOUND fehlschlägt, deutet dies auf eine Synchronisierungsabweichung zwischen Ihrer 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 beheben Sie 404-Fehler aus dem Bericht „Status“:

1. Status des Nutzerkontos 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. Das Senden von „Status melden“ und „Synchronisierung anfordern“ für die Geräte dieses Nutzers wird beendet.
   • Wenn SYNC „200 OK“ zurückgibt, ist das Nutzerkonto weiterhin verknüpft. Der 404-Fehler ist also gerätespezifisch.
2. Geräteliste abgleichen: Wenn SYNC den Status „200 OK“ zurückgibt, müssen Sie ermitteln, 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 in der Liste von Google fehlen. Wenn ein Gerät mit Google synchronisiert werden soll, aber noch nicht für Google freigegeben ist, verwende SYNC, um die Synchronisierung mit Google zu starten. Wenn die Verknüpfung eines Geräts mit Google aufgehoben werden soll, beenden Sie die Meldung des Status für dieses Gerät und melden Sie den Status weiterhin für andere gültige Geräte unter dieser agentUserId.

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