Benachrichtigungen erlauben smart home Action to use Google Assistant to communicate with users about important device-related events or changes. You can implement notifications to alert users to timely device events, for example when someone is at the door, or to report on a requested device state change, such as when a door lock bolt has been successfully engaged or has jammed.
Die Aktion smart home kann die folgenden Benachrichtigungstypen an Nutzer senden:
Proaktive Benachrichtigungen: Der Nutzer wird über ein smart home-Geräteereignis benachrichtigt, ohne dass vorher Nutzeranfragen an seine Geräte gesendet wurden, z. B. an der Türklingel.
Follow-up-Antworten: Eine Bestätigung, dass eine Gerätebefehlsanfrage erfolgreich war oder fehlgeschlagen ist, z. B. beim Verriegeln 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 bereit. 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
Wenn Geräteereignisse auftreten, 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:
Straßenbahn | Ereignisse |
---|---|
Objekterkennung | Vom Gerät erkannte Objekte, z. B. wenn an der Tür ein erkanntes Gesicht 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.“ |
Sensorstatus | Das Gerät erkennt einen unterstützten Sensorstatus. Beispiel: „Der Rauchmelder erkennt Rauch.“ |
Temperaturregler | Das Gerät hat einen Temperatursollwert erreicht. Beispiel: „Der Ofen wurde auf 350 Grad vorgeheizt.“ |
Scharf schalten | Das Gerät wird in einen Voralarm versetzt und durch eine offene Tür ausgelöst. |
Kamerastream | Link zum Livestream der Kamera, nachdem ein Objekt oder eine Bewegung vom Gerät erkannt wurde. |
Bewegungserkennung | „Am 1. Juli 2020 um 12 Uhr wurde eine Bewegung erkannt.“ |
Die folgenden Eigenschaften unterstützen Folgeantworten:
Straßenbahn | Ereignisse |
---|---|
Scharf schalten | Abschlussstatus und Statusänderung nach Ausführung des action.devices.commands.ArmDisarm -Gerätebefehls. Beispiel: „Das Sicherheitssystem wurde scharf geschaltet.“
|
Schloss entsperren | Abschlussstatus und Statusänderung nach Ausführung des action.devices.commands.LockUnlock -Gerätebefehls. Beispiele: „Die Haustür wurde verriegelt“ oder „Die Haustür ist klemmt“.
|
Netzwerksteuerung | Abschlussstatus und Statusänderung nach Ausführung des action.devices.commands.TestNetworkSpeed -Gerätebefehls. Beispiel: „Ihr Netzwerkgeschwindigkeitstest ist abgeschlossen. Die Downloadgeschwindigkeit des Routers im Büro beträgt derzeit 80,2 kbit/s und die Uploadgeschwindigkeit 9,3 kbit/s.“
|
Öffnen/Schließen | Abschlussstatus und Statusänderung nach Ausführung des action.devices.commands.OpenClose -Gerätebefehls. Beispiele: „Die Haustür wurde geöffnet“ oder „Die Haustür konnte nicht geöffnet werden“
|
Startstopp | Abschlussstatus und Statusänderung nach Ausführung des action.devices.commands.StartStop -Gerätebefehls. 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 Google an, wenn Benachrichtigungen von deiner smart home-Geräte-App aktiviert sind. Wenn Nutzer in deiner App Benachrichtigungen aktivieren oder deaktivieren, sende eine
SYNC
-Anfrage, um Google über die Geräteänderung zu informieren. - Wenn ein relevantes Geräteereignis oder eine Statusänderung zum Auslösen einer Benachrichtigung erfolgt, sende eine Benachrichtigungsanfrage durch Aufrufen von Report State
reportStateAndNotification
API. If the device state changed, you can send both a state and notification payload together in your Report State and Notification call.
In den folgenden Abschnitten werden diese Schritte ausführlicher beschrieben.
Angeben, ob Benachrichtigungen in der App aktiviert sind
Nutzer können auswählen, ob sie proaktive Benachrichtigungen erhalten möchten, indem sie diese Funktion in der GHA aktivieren. In der App für Ihr smart home-Gerät können Sie optional die Möglichkeit für Nutzer hinzufügen, Benachrichtigungen vom Gerät aus umzuschalten, z. B. über Ihre App-Einstellungen.
Geben Sie Google an, dass Benachrichtigungen für Ihr Gerät aktiviert sind, indem Sie einen Anfrage-SYNC-Aufruf ausführen, um die Gerätedaten zu aktualisieren. Sie sollten eine SYNC
-Anfrage wie diese senden, wenn Nutzer diese Einstellung in Ihrer App ändern.
Senden Sie in der SYNC
-Antwort eine der folgenden Benachrichtigungen:
- Wenn der Nutzer Benachrichtigungen in Ihrer Geräte-App explizit aktiviert hat oder Sie keine Option zum Umschalten zur Verfügung stellen, setzen Sie das Attribut
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 Assistant sendet die Auftragsausführung eine Benachrichtigungsnutzlast an Google Home Graph via a Report State and Notification API call..
Google HomeGraph API aktivieren
-
Im Google Cloud Console, go to the HomeGraph API page.
Zur Seite der 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
Senden Sie die Benachrichtigungsanfrage über die devices.reportStateAndNotification
API.
Ihre JSON-Anfrage muss eine eventId
enthalten. Dies ist eine eindeutige ID, die von Ihrer Plattform für das Ereignis generiert wird, das die Benachrichtigung auslöst. eventId
sollte eine zufällige ID sein, die sich jedes Mal unterscheidet, wenn Sie eine Benachrichtigungsanfrage senden.
Fügen Sie in das notifications
-Objekt, das Sie in Ihrem API-Aufruf übergeben, einen priority
-Wert ein, der definiert, wie die Benachrichtigung angezeigt werden soll. Das Objekt notifications
kann je nach Geräteattribut unterschiedliche Felder enthalten.
Folgen Sie einem dieser Pfade, um die Nutzlast festzulegen und die API aufzurufen:
Nutzlast der proaktiven Benachrichtigung senden
Wählen Sie zum Aufrufen der API eine der folgenden Optionen aus:
HTTP
Die Home Graph API 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 Report State und Notification: - Kombinieren Sie Report State und JSON für Benachrichtigungen mit dem Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier siehst du ein Beispiel dafür, wie du die Anfrage in der Befehlszeile mit
curl
testest:
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 Servicedefinition des Protokollpuffers 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 bietet Bindungen für die Home Graph API.
- Initialisieren Sie den Dienst
google.homegraph
mit Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit ReportStateAndNotificationRequest auf. Es wird einPromise
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', 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 bietet Bindungen für die Home Graph API.
- Initialisieren Sie die
HomeGraphApiService
mit Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mitReportStateAndNotificationRequest
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 einer Folgeantwort senden
Die Nutzlast für eine Folgeantwort enthält den Status der Anfrage, Fehlercodes für Ereignisfehler (falls zutreffend) und die gültige followUpToken
, die während der EXECUTE
-Intent-Anfrage angegeben wurde. Die followUpToken
muss innerhalb von fünf Minuten verwendet werden, um gültig zu bleiben und die Antwort der ursprünglichen Anfrage ordnungsgemäß zuzuordnen.
Das folgende Snippet zeigt ein Beispiel für eine Nutzlast der Anfrage EXECUTE
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
, 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 zu senden.
Wählen Sie zum Aufrufen der API eine der folgenden Optionen aus:
HTTP
Die Home Graph API 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 Report State und Notification: - Kombinieren Sie Report State und JSON für Benachrichtigungen mit dem Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier siehst du ein Beispiel dafür, wie du die Anfrage in der Befehlszeile mit
curl
testest:
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 Servicedefinition des Protokollpuffers 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 bietet Bindungen für die Home Graph API.
- Initialisieren Sie den Dienst
google.homegraph
mit Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit ReportStateAndNotificationRequest auf. Es wird einPromise
mit der 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 bietet Bindungen für die Home Graph API.
HomeGraphApiService
mit Standardanmeldedaten für Anwendungen initialisieren- Rufen Sie die Methode
reportStateAndNotification
mitReportStateAndNotificationRequest
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(); // 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 Benachrichtigungsqualität in deiner Aktion zu testen und aufrechtzuerhalten.
Das folgende Beispiel zeigt das Schema eines notificationLog
-Eintrags:
Attribut | Beschreibung |
---|---|
requestId |
ID der Benachrichtigungsanfrage. |
structName |
Name der Benachrichtigungsstruktur, z. B. „ObjectDetection“. |
status |
Gibt den Status der Benachrichtigung an. |
Das Feld status
enthält verschiedene Status, die auf Fehler in der Benachrichtigungsnutzlast hinweisen können. Einige davon sind möglicherweise nur für Aktionen verfügbar, die noch nicht in der Produktion eingeführt wurden.
Beispiele für Status:
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 Eigenschaft notificationSupportedByAgent des Benachrichtigungsgeräts, die in SYNC angegeben ist, falsch ist.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Gibt an, dass der Nutzer auf dem Gerät, das benachrichtigt wird, im GHA nicht aktiviert ist. Dieser Status ist nur für Aktionen verfügbar, die noch nicht im Produktions-Track eingeführt wurden. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Gibt an, dass der Nutzer dem Benachrichtigungsgerät kein Zuhause/Gebäude zugewiesen hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht im Produktions-Track eingeführt wurden. |
Zusätzlich zu diesen allgemeinen Statusangaben, die für alle Benachrichtigungen gelten können, kann das Feld status
auch zustandsspezifische Status enthalten (z.B. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).