Mit Benachrichtigungen kann die smart home-Aktion Google Assistant verwenden, um mit Nutzern über wichtige gerätebezogene Ereignisse oder Änderungen zu kommunizieren. Sie können Benachrichtigungen implementieren, um Nutzer rechtzeitig über Geräteereignisse zu benachrichtigen, z. B. wenn jemand an der Tür ist, oder um eine angeforderte Änderung des Gerätestatus zu melden, z. B. wenn ein Türschloss einrastet oder klemmt.
Die Aktion smart home kann die folgenden Benachrichtigungstypen an Nutzer senden:
Proaktive Benachrichtigungen: Der Nutzer wird über ein smart home-Geräteereignis informiert, ohne dass zuvor Anfragen an seine Geräte gesendet wurden (z. B. Türklingeln).
Folgeantworten: Eine Bestätigung, dass eine Gerätebefehlsanfrage erfolgreich war oder fehlgeschlagen ist, z. B. beim Sperren einer Tür. Verwenden Sie diese Benachrichtigungen für Gerätebefehle, deren Abschluss einige Zeit in Anspruch nimmt. Folgeantworten werden nur unterstützt, wenn Gerätebefehlsanfragen von intelligenten Lautsprechern und Smart Displays gesendet werden.
Assistant stellt Nutzern diese Benachrichtigungen als Ankündigungen auf intelligenten Lautsprechern und Smart Displays zur Verfügung. Proaktive Benachrichtigungen sind standardmäßig deaktiviert. Nutzer können alle proaktiven Benachrichtigungen von Google Home app (GHA) aktivieren oder deaktivieren.
Ereignisse, die Benachrichtigungen auslösen
Bei Geräteereignissen sendet die Aktionsausführung eine Benachrichtigungsanfrage an Google. Das Gerät, das von deiner smart home-Aktion unterstützt wird, bestimmt, welche Arten von Benachrichtigungsereignissen verfügbar sind und welche Daten du in diese Benachrichtigungen aufnehmen kannst.
Die folgenden Eigenschaften unterstützen proaktive Benachrichtigungen:
Merkmal | Veranstaltungen |
---|---|
Objekterkennung | Objekte, die vom Gerät erkannt werden, z. B. wenn ein erkanntes Gesicht an der Tür erkannt wird Beispiel: „Alice und Bob sind an der Haustür.“ |
RunCycle | Das Gerät schließt einen Zyklus ab. Beispiel: „Der Waschmaschinenzyklus ist abgeschlossen.“ |
SensorState | Das Gerät erkennt einen unterstützten Sensorstatus. Beispiel: „Der Rauchmelder hat Rauch erkannt.“ |
Temperaturregelung | Das Gerät erreicht einen Temperatursollwert. Beispiel: „Der Ofen wurde auf 350 Grad vorgeheizt.“ |
Scharf schalten | Das System wechselt in den Voralarm mit einem Countdown für den Zutritt, der durch eine offene Tür ausgelöst wird. |
Kamerastream | Link zum Livestream der Kamera, nachdem ein Objekt oder eine Bewegung vom Gerät erkannt wurde. |
Bewegungserkennung | „Die Bewegung wurde am 1. Juli 2020 um 12:00 Uhr erkannt.“ |
Die folgenden Eigenschaften unterstützen nachfolgende Antworten:
Merkmal | Veranstaltungen |
---|---|
Scharf schalten | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.ArmDisarm . Beispiel: „Das Sicherheitssystem wurde scharf geschaltet.“
|
Schloss entsperren | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.LockUnlock . Beispiele: „Die Haustür ist verriegelt.“ oder „Die Tür ist klemmen“.
|
Netzwerksteuerung | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.TestNetworkSpeed . Beispiel: „Ihr Netzwerkgeschwindigkeitstest ist abgeschlossen. Die Downloadgeschwindigkeit auf dem Router im Büro beträgt derzeit 80,2 kbit/s und die Uploadgeschwindigkeit 9,3 kbit/s.“
|
OpenClose | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.OpenClose . Beispiele: Die Vordertür wurde geöffnet oder Die Tür konnte nicht geöffnet werden.
|
Startstopp | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.StartStop . Beispiel: „Der Staubsauger wurde gestartet.“
|
Alle Gerätetypen unterstützen Benachrichtigungen für die entsprechenden Merkmale.
Benachrichtigungen für die Smart-Home-Aktion erstellen
Fügen Sie der Aktion "smart home" in diesen Phasen Benachrichtigungen hinzu:
- Gib an, ob Benachrichtigungen über die smart home-App deines Geräts aktiviert sind. Wenn Nutzer Benachrichtigungen in deiner App aktivieren oder deaktivieren, sende eine
SYNC
-Anfrage, um Google über die Änderung des Geräts zu informieren. - Wenn ein relevantes Geräteereignis oder eine Statusänderung ausgelöst wird, die eine Benachrichtigung auslöst, senden Sie eine Benachrichtigungsanfrage durch Aufrufen der Report State
reportStateAndNotification
API. Wenn sich der Gerätestatus geändert hat, können Sie sowohl einen Status als auch eine Benachrichtigungsnutzlast zusammen in Ihrem Report State- und Ihrem Benachrichtigungsaufruf senden.
In den folgenden Abschnitten werden diese Schritte ausführlicher behandelt.
Angeben, ob Benachrichtigungen in Ihrer App aktiviert sind
Nutzer können auswählen, ob sie proaktive Benachrichtigungen erhalten möchten, indem sie dieses Feature in GHA aktivieren. In der App für Ihr smart home-Gerät können Sie optional auch die Möglichkeit hinzufügen, dass Nutzer Benachrichtigungen vom Gerät explizit ein- oder ausschalten, z. B. über die App-Einstellungen.
Mit einem Aufruf von SYNC können Sie Google mitteilen, dass Benachrichtigungen für Ihr Gerät aktiviert sind. Damit werden die Gerätedaten aktualisiert. Sie sollten eine SYNC
-Anfrage wie diese senden, wenn Nutzer diese Einstellung in Ihrer App ändern.
Geben Sie in der SYNC
-Antwort eine der folgenden Aktualisierungen an:
- Wenn der Nutzer Benachrichtigungen in deiner Geräte-App explizit aktiviert hat oder du keine Ein-/Aus-Schaltfläche zur Verfügung stellst, setze die Property
devices.notificationSupportedByAgent
auftrue
. - Wenn der Nutzer Benachrichtigungen in deiner Geräte-App explizit deaktiviert hat, setze die Property
devices.notificationSupportedByAgent
auffalse
.
Das folgende Snippet zeigt ein Beispiel für die Einstellung Ihrer SYNC-Antwort:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Benachrichtigungsanfragen an Google senden
Zum Auslösen von Benachrichtigungen auf der Assistant sendet deine Auftragsausführung eine Benachrichtigungsnutzlast über Report State und einen Notification API-Aufruf an die Google Home Graph.
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.
Benachrichtigung senden
Führen Sie die Benachrichtigungsanfrage mit der devices.reportStateAndNotification
API aus.
Ihre JSON-Anfrage muss einen eventId
enthalten. Das ist eine eindeutige ID, die von Ihrer Plattform für das Ereignis generiert wird, das die Benachrichtigung auslöst. Die eventId
sollte eine Zufalls-ID sein, die sich jedes Mal unterscheidet, wenn Sie eine Benachrichtigungsanfrage senden.
Fügen Sie im notifications
-Objekt, das Sie in Ihrem API-Aufruf verwenden, einen priority
-Wert ein, der definiert, wie die Benachrichtigung angezeigt werden soll. Das Objekt notifications
kann je nach Geräteeigenschaft unterschiedliche Felder enthalten.
Führen Sie einen der folgenden Pfade aus, um die Nutzlast festzulegen und die API aufzurufen:
Proaktive Benachrichtigungsnutzlast senden
Wählen Sie zum Aufrufen der API eine der folgenden Optionen aus:
HTTP
Die Home Graph API 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 siehst du ein Beispiel für eine JSON-Anfrage für Report State und für Notification: - Kombiniere die Report State und das Benachrichtigungs-JSON 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
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "ObjectDetection": { "priority": 0, "detectionTimestamp": 1534875126750, "objects": { "named": [ "Alice" ], "unclassified": 2 } } } } } } }
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 API 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { ObjectDetection: { priority: 0, detectionTimestamp: 1534875126750, objects: { named: ['Alice'], unclassified: 2 } } } } } } } });
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 notification payload. Map<?, ?> notifications = Map.of( "ObjectDetection", Map.of( "priority", 0, "detectionTimestamp", 1534875126, "objects", Map.of("named", List.of("Alice"), "unclassifed", 2))); // Send notification. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications)))); homegraphService.devices().reportStateAndNotification(request);
Nutzlast für nachfolgende Antwort senden
Die Nutzlast für eine nachfolgende Antwort enthält den Status der Anfrage, Fehlercodes für Ereignisfehler (falls zutreffend) und den gültigen followUpToken
, die während der EXECUTE
-Intent-Anfrage angegeben wurden. Das followUpToken
-Objekt muss innerhalb von fünf Minuten verwendet werden, damit es gültig bleibt und die Antwort der ursprünglichen Anfrage korrekt zugeordnet wird.
Das folgende Snippet zeigt ein Beispiel für eine Nutzlast einer EXECUTE
-Anfrage mit dem Feld followUpToken
.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", }], "execution": [{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": false, "followUpToken": "PLACEHOLDER" } }] }] } }] };
Google verwendet die followUpToken
-Funktion, um die Benachrichtigung nur auf dem Gerät auszugeben, mit dem der Nutzer ursprünglich interagiert hat, und nicht an alle Geräte des Nutzers.
Wählen Sie zum Aufrufen der API eine der folgenden Optionen aus:
HTTP
Die Home Graph API 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 siehst du ein Beispiel für eine JSON-Anfrage für Report State und für Notification: - Kombiniere die Report State und das Benachrichtigungs-JSON 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
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "NetworkControl": { "priority": 0, "followUpResponse": { "status": "SUCCESS", "followUpToken": "PLACEHOLDER", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2 } } } } } } }
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 API 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 followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken; 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { NetworkControl: { priority: 0, followUpResponse: { status: 'SUCCESS', followUpToken, networkDownloadSpeedMbps: 23.3, networkUploadSpeedMbps: 10.2, } } } } } } } });
Java
Die HomeGraph API-Clientbibliothek für Java stellt Bindungen für die Home Graph API bereit.
HomeGraphApiService
mit Standardanmeldedaten für Anwendungen initialisieren- Rufen Sie die
reportStateAndNotification
-Methode mit derReportStateAndNotificationRequest
auf.ReportStateAndNotificationResponse
wird 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(); // Extract follow-up token. ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0]; String followUpToken = (String) executeInputs .getPayload() .getCommands()[0] .getExecution()[0] .getParams() .get("followUpToken"); // Build device follow-up response payload. Map<?, ?> followUpResponse = Map.of( "NetworkControl", Map.of( "priority", 0, "followUpResponse", Map.of( "status", "SUCCESS", "followUpToken", followUpToken, "networkDownloadSpeedMbps", 23.3, "networkUploadSpeedMbps", 10.2))); // Send follow-up response. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse)))); homegraphService.devices().reportStateAndNotification(request);
Logging
Benachrichtigungen unterstützen das Ereignis-Logging wie unter Mit Cloud Logging auf Ereignislogs zugreifen beschrieben. Diese Logs sind nützlich, um die Qualität von Benachrichtigungen innerhalb Ihrer Aktion zu testen und aufrechtzuerhalten.
Hier sehen Sie das Schema eines notificationLog
-Eintrags:
Attribut | Beschreibung |
---|---|
requestId |
ID der Anfrage. |
structName |
Name der Benachrichtigungsstruktur, z. B. "ObjectDetection". |
status |
Gibt den Status der Benachrichtigung an. |
Das Feld status
enthält verschiedene Statuswerte, die auf Fehler in der Benachrichtigungsnutzlast hinweisen können. Einige davon sind möglicherweise nur für Aktionen verfügbar, die noch nicht für die Produktion freigegeben wurden.
Beispielstatus:
Status | Beschreibung |
---|---|
EVENT_ID_MISSING |
Gibt an, dass das Pflichtfeld eventId fehlt.
|
PRIORITY_MISSING |
Gibt an, dass das Feld priority fehlt.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Gibt an, dass die notificationSupportedByAgent -Eigenschaft des benachrichtigenden Geräts in SYNC auf „false“ festgelegt ist.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Gibt an, dass der Nutzer auf dem benachrichtigenden Gerät im GHA keine Benachrichtigungen aktiviert hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht für die Produktion freigegeben wurden. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Gibt an, dass der Nutzer das benachrichtigende Gerät keinem Zuhause/Struktur zugewiesen hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht für die Produktion freigegeben wurden. |
Zusätzlich zu diesen allgemeinen Statuswerten, die für alle Benachrichtigungen gelten können, enthält das Feld „status
“ gegebenenfalls auch merkmalespezifische Status (z.B. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).