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 Ok Google, mach das Wohnzimmer heller bei Lampen von mehreren Anbietern in einem Wohnzimmer die Auflösung mehrerer QUERY-Intents, die an mehrere Clouds gesendet werden. Stattdessen werden einfach die aktuellen Helligkeitswerte auf Grundlage der zuvor gemeldeten Werte abgerufen. 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 Attribut 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 Merkmal StartStop 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ü Aktionen more_vert 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);
}
    

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, wurde jedoch 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 den Abschnitt Dashboard bereitstellen.Report State

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:

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

Fehlerantworten

Beim Aufrufen von Report State können Sie eine der folgenden Fehlerantworten erhalten. 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. 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. Achte darauf, dass agentUserId mit dem in deiner SYNC-Antwort angegebenen Wert übereinstimmt und dass du DISCONNECT-Intents richtig verarbeitest.

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