Berichtsstatus

Klasse

Report State ist eine wichtige Funktion, mit der die Home-Aktion proaktiv den neuesten Status des Nutzergeräts an Google Home Graph zurückmelden kann, anstatt auf einen QUERY-Intent zu warten.

Report State meldet Google den Status der Nutzergeräte, denen die angegebenen agentUserId zugeordnet sind (in der ursprünglichen SYNC-Anfrage gesendet). Wenn Google Assistant eine Aktion ausführen möchte, die ein Verständnis des aktuellen Status eines Geräts erfordert, kann es einfach die Statusinformationen in Home Graph abrufen, anstatt den Intent QUERY an verschiedene Clouds von Drittanbietern zu senden, bevor der Intent EXECUTE ausgegeben wird.

Ohne Report State müssen angesichts der Beleuchtung mehrerer Anbieter in einem Wohnzimmer für den Befehl Ok Google, Helligkeit meines Wohnzimmers mehrere QUERY-Intents aufgelöst werden, die an mehrere Clouds gesendet wurden. Es muss nicht einfach die aktuellen Helligkeitswerte auf Grundlage der bisher gemeldeten Helligkeitswerte ermittelt werden. Für eine optimale Nutzererfahrung muss Assistant den aktuellen Status eines Geräts haben, ohne dass ein Umlauf zum Gerät erforderlich ist.

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

Wenn du Report State aufrufst, musst du vollständige Statusdaten für eine bestimmte Eigenschaft angeben. Home Graph aktualisiert den Status pro Eigenschaft und überschreibt bei einem Report State-Aufruf alle Daten für diese Eigenschaft. Wenn Sie beispielsweise den Status für die Trait StartStop melden, muss die Nutzlast Werte für isRunning und isPaused enthalten.

Erste Schritte

So implementieren Sie Report State:

Google HomeGraph API aktivieren

  1. Rufen Sie in 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 aus Google Cloud Console zu generieren:

Hinweis: Achten Sie darauf, dass Sie das richtige GCP-Projekt verwenden, wenn Sie diese Schritte ausführen. Dies ist das Projekt, das Ihrer smart home-Projekt-ID entspricht.

  1. Rufen Sie in 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:

HTTP

Home Graph stellt einen HTTP-Endpunkt bereit.

  1. Verwenden Sie die heruntergeladene JSON-Datei des Dienstkontos, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen findest du unter Authentifizierung mit einem Dienstkonto.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken im Bereich https://www.googleapis.com/auth/homegraph ab:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Erstellen Sie die JSON-Anfrage mit der agentUserId. Hier sehen Sie eine JSON-Beispielanfrage für den Berichtsstatus und die Benachrichtigung:
    4. {
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}
  4. Kombinieren Sie die JSON-Daten für den Berichtsstatus und die Benachrichtigungs-JSON-Datei sowie das Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier sehen Sie ein Beispiel dafür, wie Sie die Anfrage mit curl in der Befehlszeile als Test stellen:
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

Home Graph stellt einen gRPC-Endpunkt bereit.

  1. Rufen Sie die Protokollzwischenspeicher-Dienstdefinition für die Home Graph API ab.
  2. Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
  3. Rufen Sie die Methode ReportStateAndNotification auf.

Node.js

Der Google APIs-Node.js-Client stellt Bindungen für die Home Graph API bereit.

  1. Initialisieren Sie den google.homegraph-Dienst mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Sie gibt einen Promise mit ReportStateAndNotificationResponse zurück.
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
          }
        }
      }
    }
  }
});

Java

Die HomeGraph API-Clientbibliothek für Java enthält Bindungen für die Home Graph API.

  1. Initialisieren Sie HomeGraphApiService mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein ReportStateAndNotificationResponse zurückgegeben.
  // 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

Empfohlene Tools für diese Aufgabe

Damit Ihre Aktion für die Zertifizierung bereit ist, ist es wichtig, Report State zu testen.

Dazu empfehlen wir die Verwendung des Home Graph-Viewers, einer eigenständigen Webanwendung, die weder heruntergeladen noch bereitgestellt werden muss.

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

Dashboard für Berichtsstatus

Voraussetzungen

Bevor Sie Ihre Aktion testen können, benötigen Sie Ihren Dienstkontoschlüssel und Ihre agentUserId. Wenn Sie bereits Ihren Dienstkontoschlüssel und agentUserId haben, finden Sie weitere Informationen unter Report State-Dashboard bereitstellen.

Dashboard „Berichtsstatus“ bereitstellen

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

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

Führen Sie im Dashboard die folgenden Schritte aus:

  • Kontoschlüsseldatei auswählen
  • AgentUserId hinzufügen

Klicken Sie dann auf Liste.

Alle Ihre Geräte sind aufgeführt. Sobald die Liste ausgefüllt ist, können Sie den Gerätestatus über die Schaltfläche Aktualisieren aktualisieren. Bei einer Änderung des Gerätestatus wird die Zeile grün hervorgehoben.

Fehlerantworten

Beim Aufrufen von Report State wird möglicherweise eine der folgenden Fehlerantworten angezeigt. Diese Antworten werden in Form von HTTP-Statuscodes ausgegeben.

  • 400 Bad Request: Der Server konnte die vom Client gesendete Anfrage aufgrund einer ungültigen Syntax nicht verarbeiten. Häufige Ursachen sind fehlerhafte JSON-Daten 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 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. Prüfen Sie, ob agentUserId mit dem Wert in der SYNC-Antwort übereinstimmt und DISCONNECT-Intents ordnungsgemäß verarbeiten.
Zurück
Synchronisierungsanfrage
Weiter
Benachrichtigungen senden