Auf dieser Seite wird erläutert, wie Google Chat-Apps Ereignisse in Google Chat empfangen und darauf reagieren können.
Ein Google Chat-Ereignis stellt eine Aktivität oder Änderung in Google Chat dar, z. B. eine neue Nachricht in einem Gruppenbereich. Ihre Chat-App kann Ereignisse verwenden, um zu verstehen, was passiert ist, und entsprechende Maßnahmen zu ergreifen oder auf sinnvolle Weise auf Ihre Nutzer zu reagieren.
Hier einige Beispiele für die Verwendung von Ereignissen:
- Neue Nachrichten in einem Gruppenbereich im Blick behalten und darauf reagieren, z. B. nach bestimmten Schlüsselwörtern oder Wortgruppen suchen.
- Senden Sie Nutzern eine Willkommensnachricht, wenn sie dem Gruppenbereich beitreten, um die Richtlinien für den Gruppenbereich zu erläutern oder Tipps zur effektiven Nutzung der Chat-App zu geben.
- Chataktivitäten verfolgen und analysieren. Beispielsweise können Sie einen monatlichen Bericht über neue Mitglieder oder die Nachrichten senden, die die meisten Reaktionen oder Antworten erhalten.
- Plattformübergreifend kommunizieren Nutzer können beispielsweise Nachrichten von Nutzern auf einer anderen Messaging-Plattform senden und empfangen, ohne Google Chat zu verlassen.
Funktionsweise von Ereignissen
Wenn in Google Chat etwas passiert, wird eine Google Chat API-Ressource erstellt, aktualisiert oder gelöscht. In Google Chat werden Ereignisse verwendet, um Ihrer Chat-App Informationen zum Typ der aufgetretenen Aktivität und zur betroffenen Chat API-Ressource zu liefern.
Message-Ressource erstellt wird.
Chat erstellt dann ein Ereignis, das Daten zur neuen Nachricht enthält.In Google Chat werden Ereignisse nach Typ kategorisiert. Mithilfe von Ereignistypen können Sie filtern und nur die Art von Informationen erhalten, die Sie benötigen. Außerdem können Sie ähnliche Aktivitäten auf dieselbe Weise verarbeiten.
In der folgenden Tabelle sehen Sie, wie sich eine Aktivität in Google Chat auf eine zugehörige Chat API-Ressource auswirkt und welche Art von Ereignis Ihre Chat-App empfängt:
| Aktivität | Chat API-Ressource | Ereignistyp |
|---|---|---|
| Ein Nutzer postet eine Nachricht in einem Google Chat-Bereich. | Eine Message-Ressource wird erstellt. |
Neue Nachricht |
| Ein Nutzer wird Administrator eines Gruppenbereichs. | Eine Membership-Ressource wird aktualisiert. |
Aktualisierte Mitgliedschaft |
| Ein Nutzer reagiert auf eine Nachricht. | Eine Reaction-Ressource wird erstellt. |
Neue Reaktion |
| Ein Nutzer verlässt einen Gruppenbereich. | Eine Membership-Ressource wird gelöscht. |
Gelöschte Mitgliedschaft |
Ereignisse von Google Chat empfangen
Ihre Chat-App kann Ereignisse auf zwei Arten empfangen:
- Abonnieren Sie Ereignisse über die Google Workspace Events API, um Ereignisse zu erhalten, sobald sie auftreten.
- Rufen Sie die Chat API auf, um nach aktuellen Ereignissen zu suchen.
In der folgenden Tabelle werden die Unterschiede und Gründe für das Abfragen von oder Abonnieren von Ereignissen erläutert:
| Ereignisse abonnieren | Ereignisse abfragen | |
|---|---|---|
| Anwendungsfälle |
|
|
| API | Google Workspace Events API | Chat API |
| Quelle der Ereignisse | Gruppenbereiche, Nutzer und Google Workspace-Organisationen (-Entwicklervorschau) | Nur Gruppenbereiche |
| Unterstützte Ereignisse |
Eine Liste der unterstützten Ereignistypen finden Sie in der Google Workspace Events API-Dokumentation unter Ereignistypen zum Erstellen von Abos. |
Eine Liste der unterstützten Ereignistypen finden Sie in der Chat API-Referenzdokumentation unter der Ressource spaceEvents.
|
| Ereignisformat | Eine Google Cloud Pub/Sub-Nachricht, die gemäß der CloudEvent-Spezifikation formatiert ist. Weitere Informationen finden Sie unter Struktur von Google Workspace-Ereignissen. |
Eine Chat API-Ressource (
spaces.spaceEvent)
|
| Ereignisdaten | Base64-codierter String mit oder ohne Ressourcendaten. Beispielnutzlasten finden Sie unter Ereignisdaten. | JSON-Nutzlast, die Ressourcendaten enthält. Einige Ereignistypen enthalten nur bestimmte Ressourcenfelder. Beispielnutzlasten finden Sie in der Referenzdokumentation. |
Beispiel: Ereignisse zu Mitgliedschaften in einem Gruppenbereich abfragen oder abonnieren
In diesem Beispiel möchte eine Chat-App Informationen zu Änderungen an Mitgliedern eines Chatbereichs erhalten. Im Gruppenbereich finden die folgenden Mitgliedschaftsaktivitäten statt:
- Ein Nutzer tritt dem Gruppenbereich bei, wodurch eine
Membership-Ressource erstellt und ein New Member-Ereignis ausgelöst wird. - Ein Nutzer wird zum Space-Manager, wodurch die
Membership-Ressource für den Nutzer aktualisiert und ein Ereignis für ein aktualisiertes Mitglied ausgelöst wird. - Ein Nutzer verlässt den Gruppenbereich, wodurch die Ressource
Membershipfür den Nutzer gelöscht und ein Ereignis „Mitglied gelöscht“ ausgelöst wird.
Ereignisse im Zusammenhang mit Mitgliedschaften abonnieren
Damit die Chat-App Ereignisse in Echtzeit empfangen kann, ruft sie die Methode subscriptions.create() der Google Workspace Events API auf, um den Chatbereich für alle Arten von Mitgliedschaftsereignissen zu abonnieren. Nach dem Erstellen des Abos kann die Chat-App Mitgliedschaftsereignisse empfangen.
In Abbildung 2 hat die Chat-App ein aktives Abo für den Gruppenbereich. Die App empfängt also ein Ereignis, wenn sich eine Mitgliedschaft im Gruppenbereich ändert. Die Chat-App kann dann in Echtzeit auf alle Aktivitäten reagieren, z. B. eine private Willkommensnachricht an das Mitglied senden, das dem Gruppenbereich beigetreten ist.
Informationen zum Erstellen von Abos mit der Google Workspace Events API finden Sie in der Dokumentation zur Google Workspace Events API.
Letzte Mitgliedschaftsereignisse abfragen
Anstatt die Mitgliedschaftsereignisse zu empfangen, wenn sie auftreten, kann eine Chat-App die Chat API aufrufen, um die letzten Ereignisse im Gruppenbereich aufzulisten, die mit der Mitgliedschaftsaktivität zusammenhängen.
In Abbildung 3 ruft eine Chat-App die Chat API-Methode spaces.spaceEvents.list() auf, nachdem alle Mitgliedschaftsaktivitäten stattgefunden haben, und filtert die Abfrage nach neuen, aktualisierten und gelöschten Mitgliedschaftsereignissen. Die Chat API gibt eine Liste von spaceEvent-Ressourcen zurück, die die einzelnen Mitgliedschaftsänderungen darstellen.
Die Chat-App kann dann basierend auf der letzten Aktivität eine Verarbeitung oder Antwort vornehmen, z. B. eine wöchentliche Nachricht mit einer Zusammenfassung der Mitgliedschaftsaktivitäten im Gruppenbereich in den letzten 7 Tagen posten.
Informationen zum Abfragen von Ereignissen mit der Chat API finden Sie unter Ereignisse aus einem Google Chat-Bereich auflisten.
Einschränkungen und Auslieferungsverhalten
Allgemeine Beschränkungen
- Damit der Nutzer oder die Chat-App Ereignisse im Zusammenhang mit der Mitgliedschaft empfangen kann, muss er oder sie direktes Mitglied des Gruppenbereichs sein. Wenn sie indirekt über eine Google-Gruppe einem Gruppenbereich hinzugefügt, aktualisiert oder daraus entfernt wurden, erhält das Abo diese Mitgliedschaftsereignisse nicht. Informationen zur Funktionsweise von Google-Gruppenmitgliedschaften finden Sie unter Google-Gruppen zu Gruppenbereichen hinzufügen.
Nutzerabos
-
Bei Abos für Nutzer werden Ereignisse zu neuen Mitgliedern in Direktnachrichten oder unbenannten Gruppenchats (
google.workspace.chat.membership.v1.created) erst ausgelöst, nachdem die erste Nachricht gepostet wurde.
Kundenabos
Für Kundenabos gelten die folgenden Einschränkungen:
- Die Google Workspace-Organisation muss mindestens eine Enterprise-SKU-Lizenz haben.
- Eine Chat-App kann nur ein Kundenabo für eine bestimmte Google Workspace-Organisation erstellen. Eine Google Workspace-Organisation kann insgesamt bis zu fünf Kundenabos haben, die von verschiedenen Chat-Apps erstellt wurden.
Für Kundenabos gilt bei der Ereignisübermittlung Folgendes:
- Gruppenbereichsereignisse: Werden nur zugestellt, wenn das Ereignis in einem Gruppenbereich auftritt, der von Ihrer Google Workspace-Organisation verwaltet wird.
- Nutzerereignisse: Werden nur zugestellt, wenn das Ereignis für einen Nutzer auftritt, der zu Ihrer Google Workspace-Organisation gehört.
Die einzige Ausnahme von diesen Regeln sind Ereignisse im Zusammenhang mit der Mitgliedschaft. Ihr Abo kann Mitgliedschaftsereignisse sowohl von Gruppenbereichen, die von Ihrer Organisation verwaltet werden, als auch von Gruppenbereichen, die von externen Organisationen verwaltet werden, empfangen. Die Zustellung hängt jedoch davon ab, welche Organisation den Gruppenbereich verwaltet:
Spaces, die von Ihrer Google Workspace-Organisation verwaltet werden
Wenn sich die Mitgliedschaft in einem Gruppenbereich ändert, der von der Google Workspace-Organisation verwaltet wird, wird dies als Gruppenbereichsereignis übermittelt.
Der Ressourcenname eines Space-Ereignisses hat das folgende Format:
spaces/{spaceId}/spaceEvents/{spaceEventId}
Von externen Organisationen verwaltete Gruppenbereiche
Wenn sich die Mitgliedschaft eines Nutzers, der von Ihrer Google Workspace-Organisation verwaltet wird, in einem Gruppenbereich ändert, der von einer externen Organisation verwaltet wird (z. B. in einem externen benannten Gruppenbereich oder einer Direktnachricht, die von einem externen Nutzer erstellt wurde), erhält Ihr Abo dieses Ereignis als Nutzerereignis.
Der Ressourcenname eines Nutzerereignisses hat das folgende Format:
users/{userId}/userEvents/{userEventId}