Ereignisse

Ereignisse sind asynchron und werden von Google Cloud Pub/Sub in einem einzigen Thema pro ProjectEreignisse liefern Updates für alle Geräte und Gebäude und der Erhalt von Ereignissen ist solange das Zugriffstoken nicht vom Nutzer widerrufen wird und die Ereignisnachrichten nicht abgelaufen.

Veranstaltungen aktivieren

Ereignisse sind eine optionale Funktion der SDM API. Weitere Informationen finden Sie unter Ereignisse aktivieren und erfahren Sie, wie Sie sie für Ihr Projectaktivieren.

Google Cloud Pub/Sub

Weitere Informationen finden Sie in der Google Cloud Pub/Sub-Dokumentation. wie Pub/Sub funktioniert. Wichtig ist insbesondere:

Ereignisabo

Wenn Ereignisse für Projectaktiviert sind, wird dir ein entsprechendes Thema angezeigt Project -ID im Format:

projects/sdm-prod/topics/enterprise-project-id

Um Ereignisse zu empfangen, erstellen Sie einen Pull- oder push für dieses Thema. für den Anwendungsfall. Es werden mehrere Abos für das SDM-Thema unterstützt. Weitere Informationen finden Sie unter Weitere Informationen finden Sie unter Abos verwalten. Informationen.

Ereignisse initiieren

Um zum ersten Mal Ereignisse zu initiieren, nachdem das Pub/Sub-Abo erstellt wurde, erstellen Sie einen <ph type="x-smartling-placeholder"></ph> devices.list. API-Aufruf als einmaligen Trigger. Ereignisse für alle Gebäude und Geräte werden danach veröffentlicht anrufen.

Ein Beispiel finden Sie in der Seite Autorisieren im Schnellstart Anleitung.

Ereignisreihenfolge

Pub/Sub garantiert nicht die sortierte Zustellung von Ereignissen und die Eingangsreihenfolge der Ereignisse ist möglicherweise nicht in der die Ereignisse tatsächlich eingetreten sind. timestamp verwenden zur Unterstützung beim Abgleich des Ereignisauftrags. Veranstaltungen können auch einzeln oder in Kombination mit anderen zu einer einzelnen Ereignisnachricht.

Weitere Informationen finden Sie unter Nachrichten sortieren:

Nutzer-IDs

Wenn Ihre Implementierung auf Nutzer ausgerichtet ist (und nicht auf Struktur oder Gerät), verwenden Sie die Methode Das Feld userID aus der Ereignisnutzlast, um Ressourcen und Ereignisse zu korrelieren. Dieses Feld ist Eine verschleierte ID, die einen bestimmten Nutzer repräsentiert.

Die userID ist auch im HTTP-Antwortheader jedes API-Aufrufs verfügbar.

Beziehungsereignisse

Beziehungsereignisse stellen eine relationale Aktualisierung einer Ressource dar. Wenn ein Gerät zum Beispiel einem Gebäude hinzugefügt wurden oder wenn ein Gerät aus einem Gebäude gelöscht wird.

Es gibt drei Arten von Beziehungsereignissen:

  • ERSTELLT
  • GELÖSCHT
  • AKTUALISIERT

Die Nutzlast für ein Beziehungsereignis lautet wie folgt:

Nutzlast

{
  "eventId" : "d93fe80c-dd14-4afb-80bd-b12dc7dca526",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

Bei einem Beziehungsereignis ist object die Ressource, die das Ereignis ausgelöst hat, und der subject ist die Ressource, mit der object jetzt eine Beziehung hat. Im Im Beispiel oben hat ein user einem Nutzer Zugriff auf dieses Gerät gewährt: developerund das autorisierte Gerät von userist jetzt mit dem autorisierten Struktur, die das Ereignis auslöst.

Ein subject kann nur ein Raum oder ein Gebäude sein. Wenn a developer keine Berechtigung zur Anzeige der Struktur von user, subject wird immer leer.

Felder

Feld Beschreibung Datentyp
eventId Die eindeutige Kennung des Ereignisses. string
Beispiel: „96305092-d82e-4e52-9115-29bfd0594bf0“
timestamp Die Uhrzeit, zu der das Ereignis aufgetreten ist. string
Beispiel: „2019-01-01T00:00:01Z“
relationUpdate Ein Objekt, das Details zur Aktualisierung der Beziehung enthält. object
userId Eine eindeutige, verschleierte Kennung, die den Nutzer repräsentiert. string
Beispiel: „AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi“

Unter Ereignisse finden Sie weitere Informationen zu den verschiedenen Ereignistypen und ihre Funktionsweise.

Beispiele

Die Ereignisnutzlasten unterscheiden sich für jede Art von Beziehungsereignis:

ERSTELLT

Gebäude erstellt

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Gerät erstellt

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Gerät erstellt

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

AKTUALISIERT

Gerät verschoben

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

GELÖSCHT

Gebäude gelöscht

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Gerät gelöscht

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Gerät gelöscht

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Beziehungsereignisse werden in folgenden Fällen nicht gesendet:

  • Ein Raum wurde gelöscht

Ressourcenereignisse

Ein Ressourcenereignis stellt eine Aktualisierung einer Ressource dar. Sie kann als Reaktion auf eine Änderung im Wert eines Trait-Felds, z. B. zum Ändern des Modus eines Thermostats. Es kann sich auch um eine Geräteaktion handeln, Ein Trait-Feld wie das Drücken einer Gerätetaste wird nicht geändert.

Ein Ereignis, das als Reaktion auf eine Änderung des Werts des Trait-Felds generiert wurde, enthält ein traits-Objekt, ähnlich einem GET-Aufruf des Geräts:

Nutzlast

{
  "eventId" : "ba462282-5053-4e3c-bf38-612b802dfa53",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Verwenden Sie die Methode Einzelperson Trait-Dokumentation zum Nutzlastformat für jede Ressource zur Änderung von Trait-Feldern .

Ein Ereignis, das als Reaktion auf eine Geräteaktion generiert wird, durch die ein Trait-Feld nicht geändert wird, hat auch einen mit einem resourceUpdate-Objekt, aber mit einem events-Objekt anstelle eines traits-Objekts:

Nutzlast

{
  "eventId" : "a556db20-2bab-4bd4-bb39-9c036a252a7e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MnCcivUK74q3Zq7CNUSsnYcAcM...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Diese Arten von Ressourcenereignissen sind mit bestimmten Merkmalen definiert. Beispiel: Der Parameter Das Bewegungsereignis ist in der CameraMotion trait. Dokumentation zu jedem Merkmal ansehen um mehr über das Nutzlastformat für diese Arten von Ressourcenereignissen zu erfahren.

Felder

Feld Beschreibung Datentyp
eventId Die eindeutige Kennung des Ereignisses. string
Beispiel: „a556db20-2bab-4bd4-bb39-9c036a252a7e“
timestamp Die Uhrzeit, zu der das Ereignis aufgetreten ist. string
Beispiel: „2019-01-01T00:00:01Z“
resourceUpdate Ein Objekt, das Details zur Ressourcenaktualisierung enthält. object
userId Eine eindeutige, verschleierte Kennung, die den Nutzer repräsentiert. string
Beispiel: „AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi“
eventThreadId Die eindeutige Kennung für den Ereignisthread. string
Beispiel: „d67cd3f7-86a7-425e-8bb3-462f92ec9f59“
eventThreadState Der Status des Ereignisthreads. string
Werte: „STARTED“, „UPDATED“, „ENDED“
resourceGroup Ein Objekt, das Ressourcen angibt, die ähnliche Aktualisierungen für dieses Ereignis haben könnten. Die Ressource des Ereignisses selbst (aus dem resourceUpdate-Objekt) ist immer in diesem Objekt vorhanden. object

Unter Ereignisse finden Sie weitere Informationen zu den verschiedenen Ereignistypen und ihre Funktionsweise.

Aktualisierbare Benachrichtigungen

Benachrichtigungen basierend auf Ressourcenereignissen können in einer App implementiert werden, z. B. für Android oder iOS Um die Anzahl der gesendeten Benachrichtigungen zu verringern, aktualisierbare Benachrichtigungen implementiert werden, wenn werden basierend auf nachfolgenden Ereignissen innerhalb desselben Ereignisses mit neuen Informationen aktualisiert. Diskussions-Thread.

Ausgewählte Ereignisse unterstützen aktualisierbare Benachrichtigungen und sind getaggt als Aktualisierbar  Dokumentation. Diese Ereignisse ein zusätzliches Feld namens eventThreadId in der Nutzlast. Verwenden können Sie einzelne Ereignisse miteinander verknüpfen, um ein vorhandenes die einem Nutzer angezeigt wurde.

Ein Ereignisthread ist nicht mit einer Ereignissitzung identisch. Ereignisthread einen aktualisierten Status für ein vorheriges Ereignis im selben Thread identifiziert. Die Ereignissitzung identifiziert separate Ereignisse, die miteinander in Beziehung stehen, und kann es mehrere Ereignis-Threads für eine bestimmte Ereignissitzung geben.

Zu Benachrichtigungszwecken werden die verschiedenen Ereignistypen in verschiedene Threads.

Diese Threadgruppierung und die Zeitlogik werden von Google verarbeitet und unterliegen jederzeit ändern. developer sollte Benachrichtigungen basierend auf den Ereignis-Threads und Sitzungen, die von der SDM API bereitgestellt werden.

Thread-Status

Ereignisse, die aktualisierbare Benachrichtigungen unterstützen, haben auch eine eventThreadState. Feld, das den Status des Ereignisthreads zu diesem Zeitpunkt angibt. Dieses hat die folgenden Werte:

  • STARTED: Das erste Ereignis in einem Ereignisthread.
  • UPDATED: Ein Ereignis in einem laufenden Terminthread. Es kann null oder mehr Ereignisse mit diesem Status in einem einzelnen Thread geben.
  • ENDED: Das letzte Ereignis in einem Ereignis-Thread, das je nach Thread-Typ ein Duplikat des letzten UPDATED-Ereignisses sein kann.

Mit diesem Feld können Sie den Fortschritt eines Ereignisthreads verfolgen und beendet.

Ereignisfilterung

Es kann vorkommen, dass von einem Gerät erkannte Ereignisse aus der Veröffentlichung herausgefiltert werden. an ein SDM-Pub/Sub-Thema. Dieses Verhalten wird als Ereignisfilterung bezeichnet. Der Zweck der Ereignisfilterung besteht darin, Zu viele ähnliche Ereignisnachrichten innerhalb kurzer Zeit zu veröffentlichen

Es kann beispielsweise sein, dass eine Nachricht in einem SDM-Thema veröffentlicht wird. für ein erstes Motion-Ereignis. Sonstiges Nachrichten für Motion werden erst nach Ablauf eines bestimmten Zeitraums von der Veröffentlichung herausgefiltert. Nach diesem Zeitraum kann eine Ereignisnachricht für diesen Ereignistyp erneut veröffentlicht werden.

Ereignisse, die in der Google Home App (GHA) werden weiterhin im Ereignisverlauf von userangezeigt. Solche -Ereignisse generieren keine App-Benachrichtigung (auch wenn dieser Benachrichtigungstyp aktiviert).

Jeder Ereignistyp hat seine eigene Ereignisfilterlogik, die durch und kann sich jederzeit ändern. Diese Logik zur Ereignisfilterung unabhängig vom Ereignisthread und der Sitzungslogik.

Dienstkonten

Für die Verwaltung der SDM API werden Dienstkonten empfohlen Abos und Ereignisnachrichten. Ein Dienstkonto wird von einer Anwendung oder einem eine virtuelle Maschine, keine Person, und hat ihren eigenen eindeutigen Kontoschlüssel.

Die Dienstkontoautorisierung für die Pub/Sub API verwendet Zweibeiniges OAuth (2LO).

Gehen Sie bei der 2LO-Autorisierung so vor:

  • developer fordert mithilfe eines Dienstschlüssels ein Zugriffstoken an.
  • developer verwendet das Zugriffstoken mit API-Aufrufen.

Weitere Informationen zu Google 2LO und zur Einrichtung findest du unter OAuth 2.0 für Server-zu-Server verwenden Anwendungen.

Autorisierung

Das Dienstkonto muss für die Verwendung mit dem Pub/Sub API:

  1. Cloud Pub/Sub aktivieren API in Google Cloud.
  2. Erstellen Sie ein Dienstkonto und einen Dienstkontoschlüssel wie unter Dienstkonto erstellen Wir empfehlen, ihr nur die Rolle Pub/Sub Subscriber (Pub/Sub-Abonnent) zuzuweisen. Achten Sie darauf, laden Sie den Dienstkontoschlüssel auf den Computer herunter, Pub/Sub API
  3. Geben Sie Ihre Anmeldedaten zur Authentifizierung (Dienstkontoschlüssel) an Ihr Anwendungscode anwenden. Folgen Sie dazu der Anleitung auf der Seite im vorherigen oder fordern Sie mit oauth2l manuell ein Zugriffstoken an, den API-Zugriff schnell testen möchten.
  4. Verwenden Sie die Anmeldedaten des Dienstkontos oder das Zugriffstoken mit dem Pub/Sub project.subscriptions API um Nachrichten abzurufen und zu bestätigen.

OAuth2l

Google oauth2l ist ein Befehlszeilentool für OAuth, das in Go geschrieben wurde. Installation für Mac oder Linux mit Go.

  1. Wenn Go nicht auf Ihrem System installiert ist, laden Sie die App zuerst herunter und installieren Sie sie.
  2. Sobald Go installiert ist, installieren Sie oauth2l und fügen Sie den Speicherort zu PATH hinzu. Umgebungsvariable: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Rufen Sie mit oauth2l ein Zugriffstoken für die API ab. Verwenden Sie dabei den entsprechenden OAuth-Bereiche: 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
    Wenn sich Ihr Dienstschlüssel z. B. hier befindet, ~/myServiceKey-eb0a5f900ee3.json: 
    oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...

Weitere Informationen finden Sie in der README-Datei zu oauth2l. Informationen.

Google API-Clientbibliotheken

Für Google APIs, die OAuth verwenden, sind mehrere Clientbibliotheken verfügbar. 2.0 Unter Google API-Clientbibliotheken finden Sie weitere Informationen zu den Sprache Ihrer Wahl.

Wenn Sie diese Bibliotheken mit dem Pub/Sub APIverwenden, verwenden Sie die Methode folgende Bereichsstring(s):

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

Fehler

In Bezug auf diese Anleitung können folgende Fehlercodes zurückgegeben werden:

Fehlermeldung RPC Fehlerbehebung
Kamerabild kann nicht mehr heruntergeladen werden. DEADLINE_EXCEEDED Ereignisbilder laufen 30 Sekunden nach der Veröffentlichung des Ereignisses ab. Laden Sie das Bild unbedingt vor dem Ablaufdatum herunter.
Ereignis-ID gehört nicht zur Kamera. FAILED_PRECONDITION Verwende die korrekte eventID, die vom Kameraereignis zurückgegeben wurde.

Siehe API-Fehlercode-Referenz für die vollständige Liste der API-Fehlercodes.