Report State ist eine wichtige Funktion, mit der die Aktion Home den neuesten Status des Geräts des Nutzers an Google Home Graph zurückgeben kann, anstatt auf den Intent QUERY
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 das Verständnis des aktuellen Status eines Geräts erfordert, kann es einfach die Statusinformationen in Home Graph aufrufen, anstatt einen QUERY
-Intent für verschiedene Clouds von Drittanbietern auszugeben, bevor der Intent EXECUTE
ausgegeben wird.
Ohne Report State müssen bei Beleuchtungen von mehreren Anbietern in einem Wohnzimmer mehrere Befehle für QUERY
, die an mehrere Clouds gesendet werden, aufgelöst werden, anstatt nur die aktuellen Helligkeitswerte basierend auf zuvor gemeldeten Werten zu ermitteln. Weitere Informationen Für eine optimale Nutzerfreundlichkeit muss Assistant den aktuellen Status eines Geräts haben, ohne dass ein Umlauf zum Gerät erforderlich ist.
Nach dem ersten SYNC
für ein Gerät sendet die Plattform einen QUERY
-Intent, der den Status des Geräts erfasst und Home Graph füllt.
Danach speichert Home Graph nur den Status, der mit Report State gesendet wird.
Achten Sie beim Aufrufen von Report State darauf, vollständige Statusdaten für eine bestimmte Eigenschaft bereitzustellen. Home Graph aktualisiert den Status pro Eigenschaft und überschreibt alle Daten für diese Eigenschaft, wenn ein Report State-Aufruf ausgeführt wird. Wenn Sie beispielsweise den Status für die Eigenschaft StartStop melden, muss die Nutzlast Werte für isRunning
und isPaused
enthalten.
Erste Schritte
So implementierst du Report State:
Google HomeGraph API aktivieren
-
Rufen Sie in Google Cloud Console die Seite HomeGraph API auf.
Zur Seite „HomeGraph API“ - Wählen Sie das Projekt aus, das Ihrer smart home-Projekt-ID entspricht.
- Klicken Sie auf AKTIVIEREN.
Dienstkontoschlüssel erstellen
Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:
-
Rufen Sie in Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.
Zur Seite Dienstkontoschlüssel erstellen - Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
- Geben Sie im Feld Dienstkontoname einen Namen ein.
- Geben Sie in das Feld Dienstkonto-ID eine ID ein.
Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.
Wählen Sie für Schlüsseltyp die Option JSON aus.
- 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 bietet einen HTTP-Endpunkt
- Verwenden Sie die heruntergeladene JSON-Datei des Dienstkontos, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen finden Sie unter Authentifizierung mit einem Dienstkonto.
- Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem Bereich
https://www.googleapis.com/auth/homegraph
ab: - Erstellen Sie die JSON-Anfrage mit
agentUserId
. Hier ein Beispiel für eine JSON-Anfrage für den Berichtstatus und die Benachrichtigung: - Kombiniere den Berichtsstatus und die JSON-Benachrichtigung mit dem Token in deiner HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Das folgende Beispiel zeigt, wie Sie die Anfrage als Test mit
curl
in der Befehlszeile ausführen:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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 bietet einen gRPC-Endpunkt
- Rufen Sie die Protokollzwischenspeicher-Dienstdefinition für die Home Graph API ab.
- Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
- Rufen Sie die Methode ReportStateAndNotification auf.
Node.js
Der Node.js-Client von Google APIs stellt Bindungen für die Home Graph API bereit.
- Initialisieren Sie den
google.homegraph
-Dienst mit Standardanmeldedaten für Anwendungen. - Rufen Sie die
reportStateAndNotification
-Methode mit der Methode ReportStateAndNotificationRequest auf. Es wird einPromise
mit ReportStateAndNotificationResponse zurückgegeben.
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 stellt Bindungen für die Home Graph API bereit.
- Initialisieren Sie
HomeGraphApiService
mit Standardanmeldedaten für Anwendungen. - Rufen Sie die
reportStateAndNotification
-Methode mit derReportStateAndNotificationRequest
auf. Es wird einReportStateAndNotificationResponse
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); }
Status des Testberichts
Damit du deine Aktion auf die Zertifizierung vorbereiten kannst, solltest du zuerst Report State testen.
Dazu empfehlen wir die Verwendung des Home Graph-Viewer-Tools. Das ist eine eigenständige Web-App, die weder heruntergeladen noch bereitgestellt werden muss.
Das Report State-Dashboard ist noch verfügbar, wurde jedoch eingestellt und nicht mehr unterstützt.
Dashboard für Berichtstatus
Voraussetzungen
Bevor Sie die Aktion testen können, benötigen Sie Ihren Dienstkontoschlüssel und agentUserId
. Wenn Sie Ihren Dienstkontoschlüssel bereits haben und agentUserId
lesen, finden Sie weitere Informationen unter Dashboard Report State bereitstellen.
Berichtsstatus-Dashboard bereitstellen
Sobald Sie den Dienstkontoschlüssel und die User-ID des Agents für Ihr Projekt haben, können Sie die neueste Version aus dem Report State
Dashboard herunterladen und bereitstellen.
Nachdem Sie die neueste Version heruntergeladen haben, folgen Sie der Anleitung aus der enthaltenen README.MD
-Datei.
Nachdem Sie das Dashboard Report State bereitgestellt haben, können Sie über die folgende URL auf das Dashboard zugreifen. Ersetzen Sie dabei your_project_id durch Ihre Projekt-ID:
http://<your-project-id>.appspot.com
Im Dashboard gehen Sie so vor:
- Kontoschlüsseldatei auswählen
- AgentUserID hinzufügen
Klicken Sie dann auf Liste.
Alle Ihre Geräte werden aufgeführt. Sobald die Liste ausgefü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.
Fehlermeldungen
Beim Aufrufen von Report State wird möglicherweise eine der folgenden Fehlerantworten angezeigt. Diese Antworten erfolgen in 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 fehlerhafter JSON-Code oder die Verwendung vonnull
anstelle von „“ für einen Stringwert.404 Not Found
: Die angeforderte Ressource wurde nicht gefunden, ist aber möglicherweise in Zukunft verfügbar. In der Regel bedeutet dies, dass das gewünschte Gerät nicht gefunden wird. Es kann auch bedeuten, dass das Nutzerkonto nicht mit Google verknüpft ist oder wir eine ungültigeagentUserId
erhalten haben. Achten Sie darauf, dassagentUserId
mit dem Wert in Ihrer SYNC-Antwort übereinstimmt und dass Sie DISCONNECT-Intents richtig verarbeiten.