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 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, müssen Sie mit der Google Workspace Events API Abos für Google Workspace-Ressourcen erstellen.

Darstellung der Bereitstellung von Ereignissen über die Google Workspace Events API

So sendet die Google Workspace Events API Ereignisse über ein Abo an Ihre App:

Ihre Anwendung abonniert eine Ressource in einer Google Workspace-Anwendung, z. B. einem Google Chat-Bereich.
Die Ressource, die Sie abonniert haben, ändert sich.
Die Google Workspace-Anwendung sendet ein Ereignis an ein Thema in Google Cloud Pub/Sub. Dieses dient als Benachrichtigungsendpunkt für Ihr Google Workspace-Abo. Das Ereignis enthält Daten zu den Änderungen an der Ressource.
Ihre Anwendung verarbeitet die Google Cloud Pub/Sub-Nachricht, die das Ereignis enthält, und ergreift gegebenenfalls Maßnahmen.

Wichtige Begriffe

Im Folgenden finden Sie eine Liste häufig verwendeter 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 überwachten Google Workspace-Ressource, z. B. eine neue Nachricht in einem Google Chat-Bereich. Sie können angeben, wie viele Details Sie über die geänderte 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, sodass Sie fehlende 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 von 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 die Google Workspace Events API unterstützt, finden Sie unter Unterstützte Google Workspace-Ereignisse.
Ereignistypen: Die Arten von Änderungen, über die Sie an der Zielressource benachrichtigt werden möchten. Wenn Sie beispielsweise einen Gruppenbereich in Google Chat abonniert haben, können Sie auswählen, ob Sie Ereignisse zu dem Gruppenbereich 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 Google Cloud Pub/Sub-Dokumentation.
Nutzlastoptionen: Die Ereignisdaten, die Sie zu geänderten Ressourcen erhalten möchten.

Unterstützte Google Workspace-Ereignisse

Die Ereignisse, die Ihre App Ereignisse empfangen kann, hängen von der Zielressource Ihres Abos ab. In der folgenden Tabelle sehen Sie die unterstützten Ereignisse für jede mögliche Zielressource.

Zielressource	Format	Unterstützte Ereignisse	Einschränkungen (falls zutreffend)
Google Chat
Google Chat-Gruppenbereiche	`//chat.googleapis.com/spaces/SPACE_ID`	Meldungen Kanalmitgliedschaft Reaktionen Leerzeichen Weitere Informationen finden Sie im Hilfeartikel Google Chat-Termine 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`	Kanalmitgliedschaft Weitere Informationen finden Sie im Hilfeartikel Google Chat-Termine abonnieren.	Das Abo empfängt nur Ereignisse über den Nutzer, der das Abo autorisiert hat. Ein Nutzer kann Abos nicht im Namen anderer Nutzer autorisieren.
Google Meet
Google Meet-Konferenzräume	`//meet.googleapis.com/spaces/SPACE_ID`	Konferenzen Teilnehmersitzungen Aufnahmen Transkripte Weitere Informationen finden Sie unter Google Meet-Termine abonnieren.
Google Meet-Nutzer	`//cloudidentity.googleapis.com/users/USER_ID`	Konferenzen Teilnehmersitzungen Aufnahmen Transkripte Weitere Informationen finden Sie unter Google Meet-Termine abonnieren.	Das Abo empfängt Ereignisse zu Konferenzräumen, bei denen der Nutzer einer der folgenden Personen ist: Der Eigentümer des Konferenzraums. Der Organisator des Google Kalender-Termins, der mit dem Konferenzraum verknüpft ist.

Struktur von Google Workspace-Ereignissen

Google Workspace-Ereignisse folgen der CloudEvents-Spezifikation, einer branchenüblichen Methode zum Beschreiben von Ereignisdaten. Google Workspace-Ereignisse enthalten Folgendes:

Attribute von 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
`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 Version der CloudEvents-Spezifikation, die für dieses Ereignis verwendet wird.	`1.0`
`subject`	Die Google Workspace-Ressource, in 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 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 Gruppenbereich empfangen. Bei Ereignissen zu neuen Nachrichten enthalten die Ereignisdaten eine Nutzlast mit der erstellten Chatressource spaces.message.

Wenn Sie ein Abo erstellen, können Sie angeben, wie viele Ressourcendaten in den Ereignissen enthalten sein sollen, 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 Abodauer auf 4 Stunden oder 24 Stunden, wenn Sie die domainweite Delegierung verwenden, begrenzt.
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 zum Ereignis erhalten möchten, können Sie die Ressource über den Ressourcennamen abfragen.

Diese Optionen für Ereignisdaten werden im Feld payloadOptions deines Abos angezeigt.

Ereignisse als Google Cloud Pub/Sub-Nachrichten

Die Abos der Google Workspace Events API 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 eine Aktion auszuführen oder auf das Ereignis zu antworten.

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, die den Ereignistyp enthalten. In diesem Fall geht es um eine aktualisierte Nachricht im Gruppenbereich.
data: die Ereignisdaten mit Details zur aktualisierten Ressource spaces.message in Form eines Base64-codierten Strings.
messageId: Die ID 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.

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