Auf dieser Seite erhalten Sie einen Überblick über die Google Workspace Events API und erfahren, wie Sie damit Ereignisse in Google Workspace abonnieren können.
Google Workspace-Ereignisse stellen Änderungen an Google Workspace-Ressourcen dar, z. B. das Erstellen, Aktualisieren oder Löschen von Ressourcen. Ihre Anwendung kann eine Google Workspace-Ressource abonnieren, damit Sie relevante Ereignisse erhalten, die Sie interessieren.
So empfängt Ihre App Ereignisse
Damit Ihre Anwendung Google Workspace-Ereignisse empfangen kann, erstellen Sie mit der Google Workspace Events API Abos für Google Workspace-Ressourcen.
Im folgenden Beispiel sehen Sie, wie die Google Workspace Events API Ereignisse über ein Abo an eine Google Chat-App sendet:
- Eine Chat-App abonniert einen Chatbereich.
- Der Chatbereich ändert sich. Beispiel: Eine neue Nachricht wird im Gruppenbereich gepostet.
- Der Chat sendet ein Ereignis an ein Thema in
Google Cloud Pub/Sub, das als Benachrichtigungsendpunkt für das Abo dient. Das Ereignis enthält Daten zu den Änderungen. Beispiel: Ein Ereignis zu einer neuen Nachricht enthält Details zur erstellten Ressource
Message
. - Die Chat-App verarbeitet die Google Cloud Pub/Sub-Nachricht, die das Ereignis enthält, und ergreift gegebenenfalls entsprechende Maßnahmen.
Wichtige Terminologie
Im Folgenden finden Sie eine Liste gebräuchlicher Begriffe, die in der Google Workspace Events API verwendet werden:
- Google Workspace-Veranstaltung
Eine Änderung an einer Google Workspace-Ressource. Ereignisse werden mit der Spezifikation CloudEvents formatiert und können entweder ein Aboereignis oder ein Lebenszyklusereignis sein:
- Aboereignis
- Eine Änderung an der Google Workspace-Ressource, die Sie überwachen, z. B. eine neue Nachricht in einem Google Chat-Bereich. Sie können angeben, wie viele Details Sie zu der geänderten Ressource erhalten möchten. Weitere Informationen finden Sie unter Struktur von Google Workspace-Ereignissen.
- Lebenszyklusereignis
- Ein Ereignis zu Ihrem Google Workspace-Abo. Lebenszyklusereignisse informieren Sie über Probleme und den Status Ihres Abos, damit Sie Aboereignisse vermeiden können. Standardmäßig erhält Ihr Abo immer Lebenszyklusereignisse. Weitere Informationen finden Sie unter Lebenszyklusereignisse für Google Workspace-Abos.
- Google Workspace-Abo
Eine benannte Entität, die eine Ressource aus einer Google Workspace-Anwendung überwacht. Ein Abo wird durch eine
Subscription
-Ressource dargestellt. Ein Abo wird durch die folgenden Informationen definiert:- Zielressource
- Die Google Workspace-Ressource, die Sie überwachen möchten.
Diese Ressource wird im Feld
targetResource
des Google Workspace-Abos dargestellt. Jedes Abo kann nur eine Ressource überwachen. Informationen dazu, welche Google Workspace-Ressourcen von der Google Workspace Events API unterstützt werden, finden Sie unter Unterstützte Google Workspace-Ereignisse. - Ereignistypen
- Die Arten von Änderungen, über die Sie für die Zielressource benachrichtigt werden möchten. Wenn Sie beispielsweise einen Google Chat-Bereich abonniert haben, können Sie auswählen, ob Sie Ereignisse zu dem Bereich und seinen untergeordneten Ressourcen erhalten möchten, z. B. Mitgliedschaften und Nachrichten.
- Benachrichtigungsendpunkt
- Der Endpunkt, an dem das Google Workspace-Abo Ereignisse empfängt. Die Google Workspace Events API unterstützt Google Cloud Pub/Sub-Themen als Benachrichtigungsendpunkt. Weitere Informationen zur Verwendung von Google Cloud Pub/Sub finden Sie in der Dokumentation zu Google Cloud Pub/Sub.
- Nutzlastoptionen
- Die Ereignisdaten, die Sie zu geänderten Ressourcen erhalten möchten.
Unterstützte Google Workspace-Ereignisse
Welche Ereignisse Ihre App empfangen kann, hängt von der Zielressource Ihres Abos ab. In der folgenden Tabelle sind die unterstützten Ereignisse für jede mögliche Zielressource aufgeführt.
Zielressource | Format | Unterstützte Ereignisse | Einschränkungen (falls zutreffend) | |
---|---|---|---|---|
Google Chat | ||||
Gruppenbereiche in Google Chat |
So abonnieren Sie einen bestimmten Gruppenbereich:
So abonnieren Sie alle Gruppenbereiche, in denen der Nutzer Mitglied ist:
|
Weitere Informationen finden Sie im Hilfeartikel Google Chat-Ereignisse abonnieren. |
Der Google Chat-Nutzer, der das Abo autorisiert, muss über sein Google Workspace- oder Google-Konto Mitglied des Gruppenbereichs sein. | |
Google Chat-Nutzer | //cloudidentity.googleapis.com/users/USER_ID |
Weitere Informationen finden Sie im Hilfeartikel Google Chat-Ereignisse abonnieren. |
Das Abo erhält nur Ereignisse über den Nutzer, der das Abo autorisiert hat. Ein Nutzer kann kein Abo im Namen anderer Nutzer autorisieren. |
|
Google Meet | ||||
Google Meet-Konferenzräume | //meet.googleapis.com/spaces/SPACE_ID |
Weitere Informationen finden Sie im Hilfeartikel Google Meet-Veranstaltungen abonnieren. |
||
Google Meet-Nutzer | //cloudidentity.googleapis.com/users/USER_ID |
Weitere Informationen finden Sie im Hilfeartikel Google Meet-Veranstaltungen abonnieren. |
Das Abo erhält Ereignisse zu Konferenzräumen, in denen der Nutzer einen der folgenden Status hat:
|
Struktur von Google Workspace-Veranstaltungen
Google Workspace-Ereignisse folgen der CloudEvents-Spezifikation, einer branchenüblichen Beschreibung von Ereignisdaten. Google Workspace-Ereignisse enthalten Folgendes:
- Attribute des CloudEvent.
- Daten zur Google Workspace-Ressource, die sich infolge des Ereignisses geändert haben
Im folgenden Abschnitt wird die Struktur der Attribute und Daten für Google Workspace-Ereignisse erläutert.
CloudEvent-Attribute
Google Workspace-Ereignisse enthalten die folgenden erforderlichen CloudEvents-Attribute:
Attribut | Beschreibung | Beispiel |
---|---|---|
|
Die Art der Daten, die im Ereignis übergeben wurden. |
|
|
Eine Kennung für das CloudEvent. |
|
|
Die Quelle des Ereignisses. Bei Google Workspace-Ereignissen ist dies der vollständige Ressourcenname des Abos. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
Die für dieses Ereignis verwendete CloudEvents-Spezifikationsversion. |
|
|
Die Google Workspace-Ressource, in der das Ereignis aufgetreten ist. |
|
|
Der Zeitstempel des Ereignisses im RFC 3339-Format. |
|
|
Der Typ des Google Workspace-Ereignisses. |
|
Ereignisdaten
Ereignisdaten sind eine Nutzlast, die eine Änderung an der Zielressource Ihres Abos darstellt, einschließlich der untergeordneten Ressourcen der Zielressource. In Ihrem Abo können Sie angeben, ob die Nutzlast Daten über die geänderte Ressource oder nur den Namen der geänderten Ressource enthalten soll.
Wenn Sie beispielsweise ein Abo für einen Chatbereich haben, können Sie Ereignisse zu neuen Nachrichten im Bereich empfangen. Bei Ereignissen zu neuen Nachrichten enthalten die Ereignisdaten eine Nutzlast mit der erstellten Chat-Ressource spaces.message
.
Wenn Sie ein Abo erstellen, können Sie angeben, wie viele Ressourcendaten in die Ereignisse aufgenommen werden sollen, die Ihre App empfängt:
- Ressourcendaten einschließen:Einige oder alle Felder der geänderten Ressource. Wenn Sie Ressourcendaten einschließen, ist die Abodauer auf 4 Stunden begrenzt. Wenn Sie die domainweite Delegierung verwenden, beträgt die 24 Stunden .
- Ressourcendaten ausschließen: Enthält nur den Namen der geänderten Ressource. Die Dauer Ihres Abos beträgt bis zu 7 Tage. Wenn Sie Details zu dem Ereignis abrufen möchten, können Sie die Ressource über den Ressourcennamen abfragen.
Diese Optionen für Ereignisdaten sind im Feld payloadOptions
deines Abos enthalten.
Ereignisse als Google Cloud Pub/Sub-Nachrichten
Die Google Workspace Events API-Abos verwenden Google Cloud Pub/Sub-Themen als Benachrichtigungsendpunkt, der Google Workspace-Ereignisse empfängt. Die Ereignisse werden als Google Cloud Pub/Sub-Nachrichten codiert. Ihre Anwendung kann die Google Cloud Pub/Sub-Nachricht verarbeiten, um Maßnahmen zu ergreifen oder auf das Ereignis zu reagieren.
Das folgende Beispiel zeigt eine Google Cloud Pub/Sub-Nachricht mit einem Ereignis zu einer aktualisierten Nachricht in einem Chatbereich:
{
"message":
{
"attributes":
{
"ce-datacontenttype": "application/json",
"ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
"ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
"ce-specversion": "1.0",
"ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
"ce-time": "2023-09-07T21:37:53.274191Z",
"ce-type": "google.workspace.chat.message.v1.updated"
},
"data": "EVENT_DATA",
"messageId": "PUBSUB_MESSAGE_ID",
"orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
"publishTime": "2023-09-07T21:37:53.713Z"
}
}
Beachten Sie die folgenden Felder:
attributes
: Attribute für das CloudEvent, einschließlich des Ereignistyps. In diesem Fall bezieht sich das Ereignis auf eine aktualisierte Nachricht im Gruppenbereich.data
: Die Ereignisdaten mit Details zur aktualisiertenspaces.message
-Ressource, formatiert als Base64-codierter String.messageId
: Die Kennung für die Google Cloud Pub/Sub-Nachricht.
Weitere Informationen zur Angabe von CloudEvents in Google Cloud Pub/Sub-Nachrichten finden Sie unter Google Cloud Pub/Sub-Protokollbindung für CloudEvents.