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-Intention zu warten.

Report State meldet Google den Status der Nutzergeräte, die mit der angegebenen agentUserId verknüpft sind (in der ursprünglichen SYNC-Anfrage gesendet). 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 der Home Graph abrufen, anstatt vor dem Senden der EXECUTE-Intention eine QUERY-Intention an verschiedene Drittanbieter-Clouds zu senden.

Ohne Report State müssen bei mehreren Lampen von verschiedenen Anbietern in einem Wohnzimmer mehrere QUERY-Intents aufgelöst werden, die an mehrere Clouds gesendet wurden, wenn der Befehl Hey Google, helleres Licht im Wohnzimmer gegeben wird. Andernfalls werden einfach die aktuellen Helligkeitswerte anhand der zuvor gemeldeten Daten abgerufen. Für eine optimale Nutzererfahrung muss Assistant den aktuellen Status eines Geräts kennen, ohne dass eine Rückschleife zum Gerät erforderlich ist.

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

Achten Sie beim Aufrufen von Report State darauf, vollständige Statusdaten für ein bestimmtes Merkmal anzugeben. Home Graph aktualisiert Zustände pro Merkmal und überschreibt alle Daten für dieses Merkmal, wenn ein Report State-Aufruf erfolgt. Wenn Sie beispielsweise den Status für das Attribut StartStop melden, muss die Nutzlast sowohl Werte für isRunning als auch für isPaused enthalten.

Jetzt starten

So implementierst du 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

So generieren Sie einen Dienstkontoschlüssel aus der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.

   Zur Seite Dienstkontoschlüssel erstellen
2. Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
3. Geben Sie im Feld Dienstkontoname einen Namen ein.
4. Geben Sie im Feld Dienstkonto-ID eine ID ein.

5. Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.

6. Wählen Sie als Schlüsseltyp die Option JSON aus.

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

API aufrufen

Wählen Sie auf den folgenden Tabs 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);
}
    

Status des Testberichts

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

Wir empfehlen dazu das Home Graph-Viewer-Tool, eine eigenständige Webanwendung, die nicht heruntergeladen oder bereitgestellt werden muss.

Das Report State-Dashboard ist zwar weiterhin verfügbar, wird aber nicht mehr unterstützt.

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

Dashboard „Meldestatus“ bereitstellen

Sobald Sie den Dienstkontoschlüssel und die Nutzer-ID des Agents für Ihr Projekt haben, laden Sie die neueste Version aus dem Report State-Dashboard herunter und implementieren Sie sie. Nachdem Sie die neueste Version heruntergeladen haben, folgen Sie der Anleitung in der enthaltenen README.MD-Datei.

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

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

Gehen Sie auf dem Dashboard so vor:

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

Klicken Sie dann auf Liste.

Alle Ihre Geräte sind aufgeführt. 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.

Fehlerantworten

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

• 400 Bad Request: Der Server konnte die vom Client gesendete Anfrage aufgrund einer ungültigen Syntax nicht verarbeiten. Häufige Ursachen sind fehlerhafte JSON-Dateien oder die Verwendung von null anstelle von „"" für einen Stringwert.
• 404 Not Found: Die angeforderte Ressource konnte nicht gefunden werden, ist aber möglicherweise in Zukunft verfügbar. Normalerweise bedeutet das, dass wir das angeforderte Gerät nicht finden können. Möglicherweise ist das Nutzerkonto auch nicht mit Google verknüpft oder wir haben eine ungültige agentUserId erhalten. Achte darauf, dass agentUserId mit dem Wert in deiner SYNC-Antwort übereinstimmt und du DISCONNECT-Intents richtig handhabst.