Ereignisse über die Google Workspace Events API abonnieren

Auf dieser Seite finden Sie eine Übersicht über die Google Workspace Events API und eine Anleitung dazu, wie Sie die API verwenden, um Ereignisse in Google Workspace zu abonnieren.

Google Workspace-Ereignisse stellen Änderungen an Google Workspace-Ressourcen dar, z. B. wenn Ressourcen erstellt, aktualisiert oder gelöscht werden. Mit der Google Workspace Events API können Sie eine Google Workspace-Ressource abonnieren und relevante Ereignisse erhalten.

Wie Ihre App Ereignisse empfängt

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

Im folgenden Beispiel wird beschrieben, wie die Google Workspace Events API Ereignisse über ein Abo an eine Chat-App liefert:

1. Eine Chat-App abonniert einen Google Chat-Bereich.
2. Der Chat-Bereich wird geändert. Beispielsweise wird eine neue Nachricht im Bereich gepostet.
3. Chat liefert 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. Bei einem Ereignis zu einer neuen Nachricht enthält das Ereignis beispielsweise Details zur erstellten Message-Ressource.
4. Die Chat-App verarbeitet die Google Cloud Pub/Sub-Nachricht, die das Ereignis enthält, und ergreift gegebenenfalls Maßnahmen.

Wichtige Terminologie

Häufig verwendete Begriffe in der Google Workspace Events API:

Google Workspace-Ereignis

Eine Änderung an einer Google Workspace-Ressource. Ereignisse werden mit der CloudEvents-Spezifikation formatiert und können entweder ein Aboereignis oder ein Lifecycle-Event sein:

Aboereignis

Eine Änderung an der Google Workspace-Ressource, die Sie überwachen, z. B. eine neue Nachricht in einem Chat-Bereich. Sie können angeben, wie viele Details Sie zur geänderten Ressource erhalten möchten. Weitere Informationen finden Sie unter Struktur von Google Workspace-Ereignissen.

Lifecycle-Event

Ein Ereignis zu 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. Welche Google Workspace-Ressourcen von der Google Workspace Events API unterstützt werden, erfahren 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 Chat-Bereich abonniert haben, können Sie auswählen, ob Sie Ereignisse zum Bereich und seinen untergeordneten Ressourcen erhalten möchten, z. B. zu 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 Google Cloud Pub/Sub-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.

Weitere Informationen finden Sie in den folgenden Leitfäden:

• Chat-Ereignisse abonnieren
• Drive-Ereignisse abonnieren
• Meet-Ereignisse abonnieren

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 des CloudEvent.
• Daten zur 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:

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 ein Abo für einen Chat-Bereich haben, können Sie Ereignisse zu neuen Nachrichten im Bereich erhalten. Bei Ereignissen zu neuen Nachrichten enthalten die Ereignisdaten eine Nutzlast mit der erstellten spaces.message-Ressource von Chat.

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

Diese Optionen für Ereignisdaten werden im payloadOptions Feld Ihres Abos dargestellt.

Ereignisse als Google Cloud Pub/Sub-Nachrichten

Für die Abos der Google Workspace Events API werden Google Cloud Pub/Sub-Themen als Benachrichtigungsendpunkt verwendet, der Google Workspace-Ereignisse empfängt. Die Ereignisse werden als Google Cloud Pub/Sub-Nachrichten codiert. Ihre App 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, die ein Ereignis zu einer aktualisierten Nachricht in einem Chat-Bereich 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"
    }
}

Dieses Beispiel enthält die folgenden Felder:

• attributes: Attribute für das CloudEvent, einschließlich des Ereignistyps. In diesem Fall geht es um eine aktualisierte Nachricht im Bereich.
• 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.

Weitere Informationen

• Google Workspace Events API-Bereiche auswählen
• Google Workspace-Abo erstellen