Willkommen beim Google Home Developer Center, der neuen Anlaufstelle für Smart-Home-Aktionen. Hinweis:Sie erstellen weiterhin Aktionen in der Actions Console.

Benachrichtigungen für Smart-Home-Aktionen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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:

  1. 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.
  2. 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 auf true.
  • Wenn der Nutzer Benachrichtigungen in deiner Geräte-App explizit deaktiviert hat, setze die Property devices.notificationSupportedByAgent auf false.

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

  1. Im Google Cloud Console, go to the HomeGraph API page.

    Zur Seite der HomeGraph API
  2. Wählen Sie das Projekt aus, das Ihrer smart home-Projekt-ID entspricht.
  3. Klicken Sie auf AKTIVIEREN.

Dienstkontoschlüssel erstellen

Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:

Hinweis: Achten Sie darauf, dass Sie bei diesen Schritten das richtige GCP-Projekt verwenden. Dies ist das Projekt, das Ihrer smart home-Projekt-ID entspricht.
  1. Rufen Sie in Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.

    Zur Seite Dienstkontoschlüssel erstellen
  2. Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
  3. Geben Sie im Feld Dienstkontoname einen Namen ein.
  4. Geben Sie in das Feld Dienstkonto-ID eine ID ein.
  5. Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.

  6. Wählen Sie für Schlüsseltyp die Option JSON aus.

  7. 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

  1. 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.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem Bereich https://www.googleapis.com/auth/homegraph ab:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Erstellen Sie die JSON-Anfrage mit agentUserId. Hier ein Beispiel für eine JSON-Anfrage für Report State und Notification:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. 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:
  7. 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

  1. Rufen Sie die Servicedefinition des Protokollpuffers für die Home Graph API ab.
  2. Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
  3. Rufen Sie die Methode ReportStateAndNotification auf.

Node.js

Der Google APIs-Node.js-Client bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den Dienst google.homegraph mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein Promise 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.

  1. Initialisieren Sie die HomeGraphApiService mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein ReportStateAndNotificationResponse 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

  1. 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.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem Bereich https://www.googleapis.com/auth/homegraph ab:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Erstellen Sie die JSON-Anfrage mit agentUserId. Hier ein Beispiel für eine JSON-Anfrage für Report State und Notification:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. 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:
  7. 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

  1. Rufen Sie die Servicedefinition des Protokollpuffers für die Home Graph API ab.
  2. Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
  3. Rufen Sie die Methode ReportStateAndNotification auf.

Node.js

Der Google APIs-Node.js-Client bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den Dienst google.homegraph mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein Promise 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.

  1. HomeGraphApiService mit Standardanmeldedaten für Anwendungen initialisieren
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein ReportStateAndNotificationResponse 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).