Willkommen beim Google Home Developer Center, der neuen Anlaufstelle für Informationen über Smart-Home-Aktionen. Hinweis:Die Aktionen in der Actions Console werden weiterhin erstellt.

Benachrichtigungen für Smart-Home-Aktionen

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:

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

  1. Rufen Sie in Google Cloud Console die Seite HomeGraph API auf.

    Zur Seite „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

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

  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 siehst du ein Beispiel für eine JSON-Anfrage für Report State und für 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. 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:
  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 Protokollzwischenspeicher-Dienstdefinition 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 Node.js-Client von Google APIs stellt Bindungen für die Home Graph API bereit.

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

  1. Initialisieren Sie HomeGraphApiService mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die reportStateAndNotification-Methode mit der 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 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

  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 siehst du ein Beispiel für eine JSON-Anfrage für Report State und für 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. 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:
  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 Protokollzwischenspeicher-Dienstdefinition 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 Node.js-Client von Google APIs stellt Bindungen für die Home Graph API bereit.

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

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