Google Chat-Ereignisse abonnieren

Auf dieser Seite werden die Google Chat-Ereignisse beschrieben, die eine Google Chat-App über die Google Workspace Events API abonnieren kann. Nachdem Sie sich entschieden haben, welche Ereignistypen Sie benötigen, erstellen Sie ein Abo, um Ereignisse von Google Chat zu erhalten.

Sie können nicht nur Ereignisse abonnieren, sondern auch die Chat API aufrufen, um Ereignisse abzufragen. Wenn Sie die Chat API aufrufen, können Sie Ereignisse in regelmäßigen Abständen abrufen oder sich über Ereignisse informieren, die Sie aufgrund eines Ausfalls möglicherweise von einem Abo verpasst haben. Informationen dazu, wie Sie Chat-Ereignisse empfangen und beantworten können, finden Sie in der Chat-Dokumentation unter Mit Ereignissen aus Google Chat arbeiten.

Unterstützte Chat-Zielressourcen

Die Google Workspace Events API unterstützt folgende Abos:

  • Gruppenbereiche, dargestellt als space-Ressourcen
  • Nutzer, dargestellt als user-Ressourcen der Cloud Identity API

Unterstützte Chat-Ereignisse

Mit Google Workspace-Abos können Sie Ereignisse zu den folgenden Änderungen in Google Chat erhalten:

  • Neue, aktualisierte oder gelöschte Nachrichten im Gruppenbereich.
  • Neue oder entfernte Reaktionen auf eine Nachricht.
  • Neue, aktualisierte oder entfernte Mitglieder im Gruppenbereich.
  • Änderungen des von Ihnen abonnierten Gruppenbereichs, z. B. ein aktualisierter Name oder eine aktualisierte Beschreibung des Gruppenbereichs

Ereignistypen zum Erstellen von Abos

Wenn du ein Abo erstellst, gibst du im Feld eventTypes[] an, welche Ereignistypen du erhalten möchtest. Ereignistypen werden gemäß der CloudEvents-Spezifikation formatiert, z. B. google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Wenn Sie beispielsweise Ereignisse zu Nutzern erhalten möchten, die einem Chatbereich beitreten, geben Sie den Bereich als Zielressource und den Ereignistyp als google.workspace.chat.membership.v1.created an. Um Ereignisse über einen bestimmten Nutzer zu erhalten, der einen beliebigen Bereich betritt, geben Sie den Nutzer als Zielressource und den Ereignistyp als google.workspace.chat.membership.v1.created an. Weitere Informationen zur Funktionsweise von Ereignissen finden Sie unter Struktur von Google Workspace-Ereignissen.

In der folgenden Tabelle sehen Sie, welche Ereignistypen für Abos von Gruppenbereichen und Abos von Nutzern unterstützt werden. Informationen zu Ausnahmen beim Auslösen eines Ereignisses finden Sie unter Einschränkungen.

Ereignistyp Format Ressourcendaten
Abos für Gruppenbereiche  
Eine Nachricht wird gepostet.

google.workspace.chat.message.v1.created

space.message
Eine Nachricht wird aktualisiert.

google.workspace.chat.message.v1.updated

space.message
Eine Nachricht wird gelöscht.

google.workspace.chat.message.v1.deleted

space.message
Eine Reaktion wird erstellt.

google.workspace.chat.reaction.v1.created

space.message.reaction
Eine Reaktion wurde gelöscht.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Ein Mitglied wird dem Gruppenbereich hinzugefügt.

google.workspace.chat.membership.v1.created

space.membership
Ein Mitglied wird im Gruppenbereich aktualisiert.

google.workspace.chat.membership.v1.updated

space.membership
Ein Mitglied wird aus dem Gruppenbereich entfernt.

google.workspace.chat.membership.v1.deleted

space.membership
Der Gruppenbereich wird aktualisiert.

google.workspace.chat.space.v1.updated

space
Der Gruppenbereich wird gelöscht.

google.workspace.chat.space.v1.deleted

space
Abos für Nutzer  
Der Nutzer wird Mitglied eines Gruppenbereichs.

Nicht alle neuen Mitglieder lösen Ereignisse aus. Weitere Informationen finden Sie unter Einschränkungen.

google.workspace.chat.membership.v1.created

space.membership
Die Mitgliedschaft des Nutzers in einem Gruppenbereich wird aktualisiert.

google.workspace.chat.membership.v1.updated

space.membership
Der Nutzer wird als direktes Mitglied eines Gruppenbereichs entfernt.

google.workspace.chat.membership.v1.deleted

space.membership

Batchereignistypen (nur Ausgabe)

Ihre Chat-App empfängt nicht nur die von Ihnen abonnierten Ereignistypen, sondern auch Batch-Ereignisse. Ein Batchereignis ist ein Ereignis, das viele Ereignisse desselben Typs darstellt, die in einem kurzen Zeitraum auftreten. Die Nutzlast eines Batchereignisses enthält eine Liste aller geänderten Ressourcen.

Wenn ein Nutzer beispielsweise einem Bereich 20 Nutzer gleichzeitig hinzufügt, erhält Ihre Chat-App möglicherweise ein Batch-Ereignis (google.workspace.chat.membership.v1.batchCreated). Die Ereignisnutzlast enthält eine Liste aller neuen Membership-Ressourcen, die erstellt wurden, als der Nutzer dem Bereich die Mitglieder hinzugefügt hat.

Sie erhalten für jeden abonnierten Ereignistyp ein Batchereignis. Daher müssen Sie beim Erstellen eines Abos keine Batchereignisse angeben. Wenn Sie beispielsweise neue Reaktionen abonnieren (google.workspace.chat.reaction.v1.created), wird Ihre Chat-App automatisch so konfiguriert, dass sie Batch-Reaktionsereignisse empfängt (google.workspace.chat.reaction.v1.batchCreated).

In der folgenden Tabelle sind die möglichen Batchereignisse für ein Abo aufgeführt:

Batch-Ereignistyp Format
Es wurden mehrere Nachrichten gepostet.

google.workspace.chat.message.v1.batchCreated
Es werden mehrere Nachrichten aktualisiert.

google.workspace.chat.message.v1.batchUpdated
Mehrere Nachrichten werden gelöscht.

google.workspace.chat.message.v1.batchDeleted
Es werden mehrere Reaktionen erstellt.

google.workspace.chat.reaction.v1.batchCreated
Mehrere Reaktionen werden gelöscht.

google.workspace.chat.reaction.v1.batchDeleted
Dem Gruppenbereich mit Abo werden mehrere Mitglieder hinzugefügt oder der Abonnent wurde mehreren Gruppenbereichen hinzugefügt.

google.workspace.chat.membership.v1.batchCreated
Mehrere Mitgliedschaften werden im abonnierten Gruppenbereich oder für den abonnierten Nutzer aktualisiert.

google.workspace.chat.membership.v1.batchUpdated
Mehrere Mitglieder werden aus dem Gruppenbereich mit Abo entfernt oder der Abonnent wurde aus mehreren Gruppenbereichen entfernt.

google.workspace.chat.membership.v1.batchDeleted
Für den Gruppenbereich gibt es mehrere Updates.

google.workspace.chat.space.v1.batchUpdated

Ereignisdaten

In diesem Abschnitt werden Ereignisdaten und Beispielnutzlasten für Ereignisse in Google Chat beschrieben.

Wenn Ihr Google Workspace-Abo ein Ereignis aus Chat empfängt, enthält das Feld data die Nutzlast für das Ereignis. Diese Nutzlast enthält Informationen zur geänderten Google Workspace-Ressource. Wenn Sie beispielsweise Mitgliedschaftsereignisse in einem Gruppenbereich abonniert haben, enthält die Nutzlast für diese Ereignisse Informationen zur geänderten Ressource spaces.membership.

Ressourcendaten in der Ereignisnutzlast

Wenn Sie ein Abo erstellen, können Sie angeben, ob die Nutzlast Details zur Ressource oder nur den Namen der Ressource enthalten soll. Wenn Sie beispielsweise Ereignisse zu Mitgliedern in einem Chatbereich erhalten möchten, können Sie angeben, welche Felder einer Mitgliedschaftsressource Sie in der Ereignisnutzlast empfangen möchten.

Die folgende Tabelle enthält Beispiele für JSON-Nutzlasten für ein Abo des Chatbereichs spaces/AAAABBBBBB. Für jedes Ereignis, das das Abo empfängt, wird die Nutzlast im Feld data des Ereignisses angezeigt:

Beispiel Ereignistyp JSON-Nutzlast

Ein Nutzer postet im Gruppenbereich die Nachricht „Hallo Welt“.

google.workspace.chat.message.v1.created

Enthält Ressourcendaten
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
        "sender":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
        },
        "space":
        {
            "name": "spaces/AAAABBBBBB"
        },
        "argumentText": "Hello world"
    }
}
Ohne Ressourcendaten
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
Ein Nutzer wird zum Administrator des Gruppenbereichs.

google.workspace.chat.membership.v1.updated

Enthält Ressourcendaten
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321",
        "state": "JOINED",
        "member":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
Ohne Ressourcendaten
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
Ein Nutzer aktualisiert die Beschreibung des Gruppenbereichs zu „Vertriebsteam für Cymbal Labs“. google.workspace.chat.space.v1.updated
Enthält Ressourcendaten
{
    "space":
    {
        "name": "spaces/AAAABBBBBB",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
Ohne Ressourcendaten
{
    "space":
    {
        "name": "spaces/AAAABBBBBB"
    }
}
Dem Gruppenbereich wurden zwei Chat-Nutzer gleichzeitig hinzugefügt. google.workspace.chat.membership.v1.batchCreated
Enthält Ressourcendaten
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321",
            "state": "JOINED",
            "member":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/987654321234567890",
            "state": "JOINED",
            "member":
            {
                "name": "users/987654321234567890",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
Ohne Ressourcendaten
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/98765432123456789019"
          }
        }
    ]
}
Ein Nutzer reagiert auf eine Nachricht mit dem Emoji 😊. google.workspace.chat.reaction.v1.created
Enthält Ressourcendaten
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
        "user":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
Omits-Ressourcendaten
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
    }
}
Nutzer reagieren auf eine Nachricht mit den Emojis 😊 und ####. google.workspace.chat.reaction.v1.batchCreated
Enthält Ressourcendaten
{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
            "user":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
            "user":
            {
                "name": "users/98765431234564321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
Omits-Ressourcendaten
{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
        },
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
        }
      }
    ]
}

Beschränkungen
  • Bei Abos für Nutzer werden Ereignisse zu neuen Mitgliedern in Direktnachrichten oder unbenannten Gruppenchats (google.workspace.chat.membership.v1.created) erst ausgelöst, nachdem die erste Nachricht gepostet wurde.
  • Änderungen am Verlauf für Gruppenbereiche lösen keine aktualisierten Gruppenbereiche aus (Ereignistyp: google.workspace.chat.spaces.v1.updated).
  • Damit der Nutzer Mitgliedschaftsereignisse erhalten kann, muss er ein direktes Mitglied des Gruppenbereichs sein. Wenn ein Nutzer über eine Google-Gruppe indirekt einem Gruppenbereich hinzugefügt, aktualisiert oder entfernt wurde, erhält das Abo diese Mitgliedschaftsereignisse nicht. Informationen zur Funktionsweise von Google Groups-Mitgliedschaften finden Sie unter Google-Gruppen zu einem Gruppenbereich hinzufügen.