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 können Sie mit der API Ereignisse in Google Workspace abonnieren.

Google Workspace-Ereignisse stellen Änderungen an Google Workspace-Ressourcen dar. z. B. wann Ressourcen erstellt, aktualisiert oder gelöscht werden. Deine App kann Abos abschließen an eine Google Workspace-Ressource senden, damit Sie relevante Termine an denen Sie interessiert sind.

So empfängt Ihre App Ereignisse

Damit Ihre App Google Workspace-Ereignisse empfangen kann, verwenden Sie die Google Workspace Events API, um Abos für Google Workspace zu erstellen Ressourcen.

Abbildung, wie Ereignisse über die Google Workspace Events API bereitgestellt werden
Abbildung 1. Beispiel dafür, wie die Über die Google Workspace Events API werden Ereignisse an Chat-App

Im folgenden Beispiel sehen Sie, wie die Google Workspace Events API Ereignisse über ein Abo an eine Google Chat-App senden:

  1. Eine Chat-App abonniert einen Chatbereich.
  2. Der Chatbereich ändert sich. Wenn z. B. eine neue Nachricht in diesem Bereich.
  3. Über den Chat wird ein Ereignis an ein Thema in gesendet. Google Cloud Pub/Sub der als Benachrichtigungsendpunkt für das Abo dient. Das Ereignis enthält Daten darüber, was geändert wurde. Für ein Ereignis zu einem neuen enthält, enthält der Termin Details zur Ressource Message, die gerade erstellt.
  4. Die Chat-App verarbeitet die Google Cloud Pub/Sub-Nachricht, die das Ereignis enthält, und gegebenenfalls Maßnahmen ergreift.

Wichtige Terminologie

Im Folgenden finden Sie eine Liste mit allgemeinen Begriffen, die in den Google Workspace Events API:

Google Workspace-Veranstaltung

Eine Änderung an einer Google Workspace-Ressource. Ereignisse werden mithilfe der CloudEvents Spezifikation und kann entweder ein Abo-Ereignis oder ein Lebenszyklusereignis:

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 viel Details, die Sie über die geänderte Ressource erhalten möchten. Weitere Informationen finden Sie unter Struktur von Google Workspace-Terminen.
Lebenszyklusereignis
Ein Ereignis zu Ihrem Google Workspace-Abo. Lebenszyklusereignisse werden Sie über Probleme und den Status Ihres Abos benachrichtigt, damit Sie verhindern, dass Aboereignisse verpasst werden. Standardmäßig ist Ihr Abo immer Lebenszyklus-Ereignisse empfängt. Weitere Informationen Siehe Lebenszyklus-Ereignisse für Google Workspace-Abos
Google Workspace-Abo

Eine benannte Entität, die eine Ressource in einem Google Workspace überwacht . Ein Abo wird durch ein Subscription . Ein Abo wird durch die folgenden Informationen definiert:

Zielressource
Die Google Workspace-Ressource, die Sie überwachen möchten. Diese Ressource wird im Feld targetResource der Google Workspace-Abo. Jedes Abo kann nur eine Ressource überwachen. Um zu sehen, welche Google Workspace-Ressourcen Unterstützung für die Google Workspace Events API, siehe Unterstützte Google Workspace-Ereignisse.
Ereignistypen
Die Arten von Änderungen, über die Sie benachrichtigt werden möchten um die Zielressource zu erreichen. Wenn Sie beispielsweise ein Google Chat-Bereich können Sie auswählen, ob Sie Ereignisse zu den Gruppenbereich und seine untergeordneten Ressourcen wie Mitgliedschaften und Nachrichten.
Benachrichtigungsendpunkt
Der Endpunkt, an dem der Das Google Workspace-Abo empfängt Ereignisse. Die Die Google Workspace Events API unterstützt Google Cloud Pub/Sub-Themen als einen Benachrichtigungsendpunkt. Weitere Informationen zur Verwendung von Google Cloud Pub/Sub sieh dir die 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 der Ihr Abo abzuschließen. In der folgenden Tabelle sind die unterstützten Ereignisse für jedes mögliche Zielressource.

Zielressource Unterstützte Ereignisse
Gruppenbereiche in Google Chat
  • Nachrichten
  • Mitgliedschaften
  • Reaktionen
  • Leerzeichen
Google Chat-Nutzer
  • Mitgliedschaften
Google Meet-Konferenzräume
  • Konferenzen
  • Sitzungen der Teilnehmer
  • Aufnahmen
  • Transkripte
Google Meet-Nutzer
  • Konferenzen
  • Sitzungen der Teilnehmer
  • Aufnahmen
  • Transkripte

Weitere Informationen finden Sie in den folgenden Leitfäden:

Struktur von Google Workspace-Veranstaltungen

Google Workspace-Ereignisse folgen den CloudEvents Spezifikation, eine branchenübliche Methode zur Beschreibung von Ereignisdaten. Google Workspace Ereignisse enthalten Folgendes:

  • Attribute des CloudEvent.
  • Daten über die Google Workspace-Ressource, die sich infolge des der Termin

Im folgenden Abschnitt wird die Struktur der Attribute und Daten für Google Workspace-Termine.

CloudEvent-Attribute

Google Workspace-Ereignisse enthalten die folgenden erforderlichen Informationen CloudEvents-Attribute:

Attribut Beschreibung Beispiel

datacontenttype

Die Art der Daten, die im Ereignis übergeben wurden.

application/json

id

Eine Kennung für das CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

Die Quelle des Ereignisses. Für Google Workspace-Termine Dies ist der vollständige Ressourcenname des Abos. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

Die für dieses Ereignis verwendete CloudEvents-Spezifikationsversion.

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 am Ziel Ihres Abos darstellt Ressource, einschließlich der untergeordneten Ressourcen der Zielressource. In der können Sie angeben, ob die Nutzlast Daten die geänderte Ressource oder nur den Namen der geänderten Ressource.

Wenn Sie beispielsweise ein Abo für einen Chatbereich haben, kann Termine zu neuen Nachrichten im Gruppenbereich empfangen. Für Veranstaltungen zu Nachrichten enthalten, enthalten die Ereignisdaten eine Nutzlast mit dem spaces.message erstellte Ressource.

Beim Erstellen eines Abos 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 . Wenn Sie Ressourcendaten einschließen, Die Dauer ist auf 4 Stunden begrenzt bzw. auf 24 Stunden, wenn Sie domainweit Delegierung.
  • Ressourcendaten ausschließen: Enthält nur den Namen der geänderten Ressource. . Die Dauer Ihres Abos beträgt bis zu 7 Tage. Um Details zu das Ereignis enthält, können Sie die Ressource über den Ressourcennamen abfragen.

Diese Optionen für Ereignisdaten sind in der payloadOptions zu finden Ihres Abonnements.

Ereignisse als Google Cloud Pub/Sub-Nachrichten

Die Google Workspace Events API-Abos verwenden Google Cloud Pub/Sub Themen als Benachrichtigungsendpunkt, der Google Workspace empfängt Ereignisse. 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 über den Termin.

Das folgende Beispiel zeigt eine Google Cloud Pub/Sub-Nachricht mit einen Termin 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, darunter: den Ereignistyp. In diesem Fall geht es bei dem Termin um eine aktualisierte Nachricht im Leerzeichen.
  • 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 angegeben werden Siehe Google Cloud Pub/Sub-Protokollbindung für CloudEvents.