Diese Seite wurde von der Cloud Translation API übersetzt.

Ereignisse über die Google Workspace Events API abonnieren

Auf dieser Seite erhalten Sie einen Überblick über die Google Workspace Events API und erfahren, wie Sie mit der API Ereignisse in Google Workspace abonnieren können.

Google Workspace-Ereignisse beschreiben Änderungen an Google Workspace-Ressourcen, z. B. wenn Ressourcen erstellt, aktualisiert oder gelöscht werden. Ihre App kann eine Google Workspace-Ressource abonnieren, um über für Sie relevante Ereignisse informiert zu werden.

So empfängt Ihre App Ereignisse

Damit Ihre App Google Workspace-Ereignisse empfangen kann, erstellen Sie mit der Google Workspace Events API Abos für Google Workspace-Ressourcen.

Darstellung der Übermittlung von Ereignissen über die Google Workspace Events API — **Abbildung 1.** Beispiel dafür, wie die Google Workspace Events API Ereignisse an eine Chat-App sendet.

Im folgenden Beispiel wird gezeigt, 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: Es wird eine neue Nachricht 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 dazu, was sich geändert hat. Ein Ereignis zu einer neuen Nachricht enthält beispielsweise Details zur erstellten Message-Ressource.
Die Chat-App verarbeitet die Google Cloud Pub/Sub-Nachricht, die das Ereignis enthält, und ergreift bei Bedarf Maßnahmen.

Wichtige Begriffe

Im Folgenden finden Sie eine Liste gängiger Begriffe, die in der Google Workspace Events API verwendet werden:

Google Workspace-Ereignis

Eine Änderung an einer Google Workspace-Ressource. Ereignisse werden gemäß der CloudEvents formatiert und können entweder ein Aboereignis oder ein Lifecycle-Ereignis sein:

Aboereignis: Eine Änderung an der von Ihnen überwachten Google Workspace-Ressource, 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 im Zusammenhang mit Ihrem Google Workspace-Abo. Lebenszyklusereignisse informieren Sie über Probleme und den Status Ihres Abos, damit Sie keine Aboereignisse verpassen. Standardmäßig werden für Ihr Abo immer Lebenszyklusereignisse empfangen. 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. Mit jedem Abo kann nur eine Ressource überwacht werden. Informationen zu den Google Workspace-Ressourcen, die 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 festlegen, ob Sie Benachrichtigungen zu diesem Bereich und seinen untergeordneten Ressourcen wie Mitgliedschaften und Nachrichten erhalten möchten.
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 zugehörigen Dokumentation.
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	Unterstützte Ereignisse
Google Chat-Gruppenbereiche	Nachrichten Mitgliedschaften Reaktionen Leerzeichen
Google Chat-Nutzer	Mitgliedschaften
Google Meet-Konferenzräume	Konferenzen Teilnehmersitzungen Aufnahmen Transkripte
Google Meet-Nutzer	Konferenzen Teilnehmersitzungen Aufnahmen Transkripte

Weitere Informationen finden Sie in den folgenden Anleitungen:

Struktur von Google Workspace-Ereignissen

Google Workspace-Ereignisse folgen der CloudEvents-Spezifikation, einer branchenweit üblichen Methode zur Beschreibung von Ereignisdaten. Google Workspace-Ereignisse enthalten Folgendes:

Attribute des CloudEvents.
Daten über die Google Workspace-Ressource, die sich aufgrund des Ereignisses geändert hat

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
`datacontenttype`	Der Datentyp, der im Ereignis übergeben wurde.	`application/json`
`id`	Eine Kennung für das CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	Die Quelle des Ereignisses. Bei Google Workspace-Ereignissen ist dies der vollständige Ressourcenname des Abos.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	Die CloudEvents-Spezifikationsversion, die für dieses Ereignis verwendet wird.	`1.0`
`subject`	Die Google Workspace-Ressource, bei der das Ereignis aufgetreten ist.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	Der Zeitstempel des Ereignisses im RFC 3339-Format.	`2023-09-07T21:37:36.260127Z`
`type`	Der Typ des Google Workspace-Ereignisses.	`google.workspace.chat.message.v1.created`

Ereignisdaten

Ereignisdaten sind eine Nutzlast, die eine Änderung an der Zielressource Ihres Abos darstellt, einschließlich untergeordneter Ressourcen der Zielressource. In Ihrem Abo können Sie angeben, ob die Nutzlast Daten zur geänderten Ressource oder nur den Namen der geänderten Ressource enthalten soll.

Wenn Sie beispielsweise einen Gruppenbereich abonniert haben, können Sie Benachrichtigungen zu neuen Nachrichten in diesem Gruppenbereich erhalten. Bei Ereignissen zu neuen Nachrichten enthalten die Ereignisdaten eine Nutzlast mit der erstellten Chatspaces.message-Ressource.

Wenn Sie ein Abo erstellen, können Sie angeben, wie viele Ressourcendaten in den Ereignissen enthalten sind, die Ihre App empfängt:

Ressourcendaten einschließen:Enthält einige oder alle Felder der geänderten Ressource. Wenn Sie Ressourcendaten einschließen, ist die Laufzeit Ihres Abos auf maximal 4 Stunden oder 24 Stunden begrenzt, wenn Sie die domainweite Delegierung verwenden.
Ressourcendaten ausschließen: Enthält nur den Namen der geänderten Ressource. Die Laufzeit des Abos beträgt bis zu 7 Tage. Wenn Sie Details zum Ereignis abrufen möchten, können Sie die Ressource anhand des Ressourcennamens abfragen.

Diese Optionen für Ereignisdaten sind im Feld payloadOptions Ihres Abos zu sehen.

Ereignisse als Google Cloud Pub/Sub-Nachrichten

Bei Google Workspace Events API-Abos werden Google Cloud Pub/Sub-Themen als Benachrichtigungsendpunkt verwendet, über den Google Workspace-Ereignisse empfangen werden. Die Ereignisse werden als Google Cloud Pub/Sub-Nachrichten codiert. Ihre App kann die Google Cloud Pub/Sub-Nachricht verarbeiten, um eine Aktion auszuführen oder auf das Ereignis zu reagieren.

Das folgende Beispiel zeigt eine Google Cloud Pub/Sub-Nachricht, die ein Ereignis zu einer aktualisierten Nachricht in einem Chatbereich enthält:

 {
    "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 aktualisierten spaces.message-Ressource, formatiert als Base64-codierter String.
messageId: Die Kennung für die Google Cloud Pub/Sub-Nachricht.

Weitere Informationen dazu, wie CloudEvents in Google Cloud Pub/Sub-Nachrichten angegeben werden, finden Sie unter Google Cloud Pub/Sub-Protokollbindung für CloudEvents.

Google Chat-Ereignisse abonnieren
Google Meet-Termine abonnieren
Lebenszyklus-Ereignisse für Google Workspace-Abos
Google Workspace Events API-Bereiche auswählen
Google Workspace-Abo erstellen