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

Report State meldet an Google die Status von Nutzergeräten mit der angegebenen agentUserId (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 im Home Graph nachschlagen, anstatt vor dem Senden der EXECUTE-Absicht eine QUERY-Absicht an verschiedene Drittanbieter-Clouds zu senden.

Ohne Report State erfordert der Befehl Ok Google, mach das Wohnzimmer heller bei mehreren Lampen von verschiedenen Anbietern in einem Wohnzimmer die Auflösung mehrerer QUERY-Absichten, 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 , mit der der Status des Geräts erfasst wird, 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 in der 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 add und dann auf Dienstkonto 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 eine Option auf 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();
}
    

„Status melden“ testen

Damit Ihre Cloud-to-cloud Integration für 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 „Status melden“

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 Dashboard Report State bereitstellen.

Dashboard „Status melden“ 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. Folgen Sie nach dem Herunterladen der neuesten Version 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 mit der Schaltfläche Aktualisieren die Gerätestatus aktualisieren. Wenn sich der Gerätestatus ändert, wird die Zeile grün hervorgehoben.

Abweichungen bei „Status melden“

Die Genauigkeit des abfragebasierten Statusberichts gibt an, wie gut der neueste Statusbericht für ein Gerät mit dem Status des Geräts übereinstimmt, wenn ein Nutzer ihn abfragt. Dieser Wert sollte bei 99,5 % liegen. Weitere Informationen zum aktuellen Status der Genauigkeit von „Status melden“ Ihres Projekts finden Sie unter Gerätezustand – Statusgenauigkeit. Sie können die Details des Protokolls für Abweichungen bei „Status melden“ aus dem Log-Explorer aufrufen.

Hier ist ein Beispiel für ein Protokoll für Abweichungen bei „Status melden“:

{
  "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 bei „Status melden“

Fehlerantworten

Beim Aufrufen von Report State können Sie eine der folgenden Fehlerantworten erhalten. Diese Antworten werden in Form von HTTP-Statuscodes gesendet.

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 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.

Wenn ein Aufruf von „Status melden“ mit einem 404 NOT_FOUND-Fehler 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 wenn ein Nutzer die Verknüpfung seines Kontos aufhebt.

So beheben Sie 404-Fehler von „Status melden“:

1. Status des Nutzerkontos prüfen: Rufen Sie devices.sync für die agentUserId auf, die einen 404-Fehler zurückgegeben hat. So können Sie feststellen, ob der Fehler für das gesamte Nutzerkonto oder für ein bestimmtes Gerät gilt.
   • Wenn SYNC einen 404-Fehler zurückgibt, ist das Nutzerkonto nicht mehr mit Google verknüpft. Senden Sie für die Geräte dieses Nutzers keine Statusberichte mehr und fordern Sie keine Synchronisierung mehr an.
   • Wenn SYNC den Statuscode 200 OK zurückgibt, ist das Nutzerkonto weiterhin verknüpft. Der 404-Fehler ist also gerätespezifisch.
2. Geräteliste abgleichen: Wenn SYNC den Statuscode 200 OK zurückgibt, müssen Sie ermitteln, welche Geräte Google nicht mehr kennt. 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 wurde, verwenden Sie SYNC, um sicherzustellen, dass das Gerät mit Google synchronisiert wird. Wenn die Verknüpfung eines Geräts mit Google aufgehoben werden soll, melden Sie den Status für dieses Gerät nicht mehr und melden Sie den Status für andere gültige Geräte unter dieser agentUserId weiterhin.

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