Report State ist eine wichtige Funktion, mit der die Home-Aktion proaktiv den aktuellen 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, denen die angegebenen agentUserId
zugeordnet sind (in der ursprünglichen SYNC
-Anfrage gesendet). Wenn Google Assistant eine Aktion ausführen möchte, für die das Verständnis des aktuellen Status eines Geräts erforderlich ist, kann es einfach die Statusinformationen im Home Graph abrufen, anstatt vor dem Intent EXECUTE
einen QUERY
-Intent an verschiedene Drittanbieter-Clouds auszugeben.
Ohne Report State müssen angesichts von Lichtquellen von mehreren Anbietern in einem Wohnzimmer für den Befehl Ok Google, helleres Wohnzimmer mehrere QUERY
-Intents aufgelö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 dem anfänglichen SYNC
für ein Gerät sendet die Plattform einen QUERY
-Intent, der den Gerätestatus erfasst, um Home Graph zu erfassen.
Danach speichert Home Graph nur den mit Report State gesendeten Status.
Achte beim Aufrufen von Report State darauf, vollständige Statusdaten für ein bestimmtes Merkmal anzugeben. Home Graph aktualisiert den Status pro Trait und überschreibt alle Daten für dieses Trait, wenn ein Report State-Aufruf erfolgt. Wenn Sie beispielsweise den Status für das Trait 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 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
Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:
-
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-Token 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 aus den folgenden Tabs eine Option aus:
HTTP
Home Graph stellt einen HTTP-Endpunkt bereit.
- 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 sehen Sie eine JSON-Beispielanfrage 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
Home Graph stellt einen gRPC-Endpunkt bereit.
- 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 Google APIs Node.js-Client stellt Bindungen für die Home Graph API bereit.
- Initialisieren Sie den
google.homegraph
-Dienst mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit ReportStateAndNotificationRequest auf. Sie gibt einPromise
mit der 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.
- Initialisieren Sie
HomeGraphApiService
mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mitReportStateAndNotificationRequest
auf. Sie gibtReportStateAndNotificationResponse
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); }
Testberichtsstatus
Teste Report State, um deine Aktion auf die Zertifizierung vorzubereiten.
Dazu empfehlen wir die Verwendung des Home Graph-Viewers. Dies ist eine eigenständige Webanwendung, die weder heruntergeladen noch bereitgestellt werden muss.
Das Report State-Dashboard ist weiterhin verfügbar, wurde aber eingestellt und wird nicht mehr unterstützt.
Berichtsstatus-Dashboard
Voraussetzungen
Bevor Sie Ihre Aktion testen können, benötigen Sie Ihren Dienstkontoschlüssel und Ihren agentUserId
. Wenn Sie bereits Ihren Dienstkontoschlüssel und agentUserId
haben, lesen Sie Report State-Dashboard bereitstellen.
Dashboard für 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
- Agent-UserId hinzufügen
Klicken Sie dann auf Liste.
Daraufhin werden alle Ihre Geräte angezeigt. Sobald die Liste ausgefüllt ist, können Sie die Schaltfläche Aktualisieren verwenden, um den Gerätestatus zu aktualisieren. Bei einer Gerätestatusänderung wird die Zeile grün hervorgehoben.
Fehlermeldungen
Beim Aufrufen von Report State kann eine der folgenden Fehlerantworten angezeigt werden. 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 ein fehlerhaftes JSON-Format 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 wir das gewünschte Gerät nicht finden können. 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 DISCONNECT-Intents ordnungsgemäß verarbeitet werden.