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
-
Rufen Sie in der 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
So generieren Sie einen Dienstkontoschlüssel aus der Google Cloud Console:
-
Rufen Sie in der 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 im Feld Dienstkonto-ID eine ID ein.
Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.
Wählen Sie als Schlüsseltyp die Option JSON aus.
- 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:
HTTP
Der Home Graph stellt einen HTTP-Endpunkt bereit.
- Verwenden Sie die heruntergeladene JSON-Datei für das Dienstkonto, 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 der
agentUserId
. Hier ist eine Beispiel-JSON-Anfrage für den Berichtsstatus 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 in der Befehlszeile mit
curl
als Test stellen:
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
Die Home Graph stellt einen gRPC-Endpunkt bereit.
- Rufen Sie die Protocol Buffers-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 für Google APIs bietet Bindungen für die Home Graph API.
- Initialisieren Sie den
google.homegraph
-Dienst mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit der ReportStateAndNotificationRequest auf. Es wird einePromise
mit der 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 Home Graph API-Clientbibliothek für Java bietet Bindungen für die Home Graph API.
- Initialisieren Sie die
HomeGraphApiService
mit Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit demReportStateAndNotificationRequest
auf. Sie gibt einReportStateAndNotificationResponse
zurück.
// 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 vonnull
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ültigeagentUserId
erhalten. Achte darauf, dassagentUserId
mit dem Wert in deiner SYNC-Antwort übereinstimmt und du DISCONNECT-Intents richtig handhabst.