Berichtsstatus

Report State ist eine wichtige Funktion, mit der die Home-Aktion proaktiv den neuesten Status des Geräts des Nutzers an Google Home Graph zurückmelden kann, anstatt auf einen QUERY-Intent 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 angesichts von Lichtern von mehreren Anbietern in einem Wohnzimmer für den Befehl Ok Google, mein Wohnzimmer heller machen mehrere QUERY-Intents gelöst werden, die an mehrere Wolken gesendet wurden, anstatt nur die aktuellen Helligkeitswerte anhand der zuvor gemeldeten Helligkeitswerte abzurufen. Für eine optimale Nutzererfahrung muss Assistant den aktuellen Status eines Geräts haben, ohne dass ein Umlauf 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 speichert Home Graph nur den mit Report State gesendeten Status.

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. Es wird dann eine JSON-Datei mit Ihrem Schlüssel 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

Teste Report State, um deine Aktion auf die Zertifizierung vorzubereiten.

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 Aktion testen können, benötigen Sie den Dienstkontoschlüssel und die 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, greifen Sie über die folgende URL auf das Dashboard zu (ersetzen Sie 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 angezeigt 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.