订阅 Google Chat 活动

本页面介绍了 Google Chat 应用可以使用 Google Workspace Events API 订阅的 Google Chat 事件。确定需要哪些类型的事件后，创建订阅即可开始接收 Google Chat 发送的事件。

除了订阅事件之外，您还可以通过调用 Chat API 来查询事件。通过调用 Chat API，您可以定期检索事件，也可以在订阅因中断而导致错过事件时及时跟进。如需了解接收和响应 Chat 事件的方式，请参阅 Chat 文档中的处理 Google Chat 中的事件。

支持的 Chat 事件

通过 Google Workspace 订阅，您可以接收有关 Chat 中以下类型更改的事件：

  • 聊天室中新增、更新或删除的消息。
  • 消息的新增或移除回应。
  • 聊天室中新增、更新或移除的成员。
  • 您订阅的聊天室发生更改，例如聊天室名称或说明更新。

您可以监控哪些资源中的事件

如需接收事件，您需要指定要监控的 Chat 资源，该资源称为订阅的目标资源。

Google Workspace Events API 支持以下 Chat 目标资源：

目标资源 格式 限制
空格

//chat.googleapis.com/spaces/SPACE

其中，SPACE 是 Chat API space 资源的 资源名称中的 ID。 您可以从会议室的网址中获取 ID，也可以使用 spaces.list() 方法获取 ID。

 授权订阅的 Chat 用户或 Chat 应用必须通过其 Google Workspace 账号或 Google 账号成为相应聊天室的成员。支持：
用户的所有空间

//chat.googleapis.com/spaces/-

 订阅仅接收用户通过其 Google Workspace 或 Google 账号成为成员的聊天室的事件。仅支持用户身份验证。
用户

//cloudidentity.googleapis.com/users/USER

其中，USER 是 Chat API user 资源的 资源名称中的 ID。 如需了解详情，请参阅识别并指定 Google Chat 用户。

订阅仅接收有关授权订阅的用户的事件。用户无法代表其他用户授权订阅。仅支持用户身份验证。

用于创建订阅的事件类型

创建订阅时，您可以使用 eventTypes[] 字段指定要接收的事件类型。事件类型按照 CloudEvents 规范进行格式设置，例如 google.workspace.APPLICATION.RESOURCE.VERSION.ACTION。

例如，如需接收有关用户加入 Chat 聊天室的事件，您需要将聊天室指定为目标资源，并将事件类型指定为 google.workspace.chat.membership.v1.created。如需接收有关指定用户加入任何空间的事件，您需要将该用户指定为目标资源，并将事件类型指定为 google.workspace.chat.membership.v1.created。如需详细了解事件的工作方式，请参阅 Google Workspace 事件的结构。

下表显示了哪些事件类型支持订阅聊天室和订阅用户。如需了解有关触发事件的例外情况，请参阅限制。

Event type 格式 资源数据
聊天室订阅  
发布消息。

google.workspace.chat.message.v1.created

space.message
系统会更新消息。

google.workspace.chat.message.v1.updated

space.message
消息已删除。

google.workspace.chat.message.v1.deleted

space.message
创建了反应。

google.workspace.chat.reaction.v1.created

space.message.reaction
已删除回应。

google.workspace.chat.reaction.v1.deleted

space.message.reaction
有成员加入聊天室。

google.workspace.chat.membership.v1.created

space.membership
更新了聊天室中的成员。

google.workspace.chat.membership.v1.updated

space.membership
成员从聊天室中移除。

google.workspace.chat.membership.v1.deleted

space.membership
聊天室已更新。

google.workspace.chat.space.v1.updated

space
聊天室已被删除。

google.workspace.chat.space.v1.deleted

space
用户订阅  
用户成为聊天室的成员。

并非所有新会员都会触发事件。如需了解详情，请参阅限制

google.workspace.chat.membership.v1.created

space.membership
更新了用户在聊天室中的成员身份。

google.workspace.chat.membership.v1.updated

space.membership
相应用户已从聊天室的直接成员中移除。

google.workspace.chat.membership.v1.deleted

space.membership

批次事件类型（仅限输出）

除了接收您订阅的事件类型外，Chat 应用还可能会接收批量事件。批处理事件是指在短时间内发生的多项同类事件。批量事件的载荷包含所有已更改资源的列表。

例如，如果用户同时向聊天室添加了 20 位用户，您的 Chat 应用可能会收到批量事件 (google.workspace.chat.membership.v1.batchCreated)。该事件载荷包含一个列表，其中列出了用户向聊天室添加成员时创建的所有新 Membership 资源。

您会收到所订阅的任何事件类型的批处理事件，因此在创建订阅时无需指定批处理事件。例如，如果您订阅了新表情符号 (google.workspace.chat.reaction.v1.created)，聊天应用会自动配置为接收批量表情符号事件 (google.workspace.chat.reaction.v1.batchCreated)。

下表显示了订阅可能发生的批次事件：

批量事件类型 格式
发布多条消息。

google.workspace.chat.message.v1.batchCreated
多条消息已更新。

google.workspace.chat.message.v1.batchUpdated
多条消息已删除。

google.workspace.chat.message.v1.batchDeleted
创建多个反应。

google.workspace.chat.reaction.v1.batchCreated
多个回应被删除。

google.workspace.chat.reaction.v1.batchDeleted
订阅的聊天室中添加了多位成员，或者订阅的用户已添加到多个聊天室中。

google.workspace.chat.membership.v1.batchCreated
在订阅空间中或针对订阅用户更新了多个会员资格。

google.workspace.chat.membership.v1.batchUpdated
多位成员已从订阅的聊天室中移除，或者订阅用户已从多个聊天室中移除。

google.workspace.chat.membership.v1.batchDeleted
聊天室有多个更新。

google.workspace.chat.space.v1.batchUpdated

事件数据

本部分介绍了 Chat 中事件的事件数据和有效负载示例。

当您的 Google Workspace 订阅收到来自 Chat 的事件时，data 字段会包含相应事件的载荷。此载荷包含有关发生更改的 Google Workspace 资源的信息。例如，如果您已订阅某个聊天室中的会员事件，则这些事件的载荷会包含有关发生更改的 spaces.membership 资源的信息。

事件载荷中的资源数据

创建订阅时，您可以指定希望载荷包含资源详细信息还是仅包含资源名称。例如，如果您想接收有关聊天室中成员的事件，可以指定要在事件载荷中接收哪些成员资源字段。

下表提供了针对 Chat 群组 spaces/AAAABBBBBB 的订阅的 JSON 载荷示例。对于订阅收到的每个事件，载荷都会显示在事件的 data 字段中：

示例 Event type JSON 载荷

用户在聊天室中发布了一条“Hello world”消息。

google.workspace.chat.message.v1.created

包含资源数据：

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

排除资源数据：

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
用户成为聊天室管理员。

google.workspace.chat.membership.v1.updated

包含资源数据：

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

排除资源数据：

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
用户将聊天室的说明更新为“Cymbal Labs 的销售团队”。 google.workspace.chat.space.v1.updated

包含资源数据：

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

排除资源数据：

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
两名 Chat 用户同时被添加到了聊天室中。 google.workspace.chat.membership.v1.batchCreated

包含资源数据：

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

排除资源数据：

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
用户使用 😊 表情符号回复消息。 google.workspace.chat.reaction.v1.created

包含资源数据：

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

排除资源数据：

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
用户使用 😊 表情符号和 😸 表情符号回复消息。 google.workspace.chat.reaction.v1.batchCreated

包含资源数据：

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

排除资源数据：

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}

限制
  • 对于用户订阅，有关私信或未命名群聊中新成员的事件 (google.workspace.chat.membership.v1.created) 仅在发布第一条消息后触发。
  • 如需接收成员资格事件，用户或 Chat 应用必须是相应聊天室的直接成员。如果成员是通过 Google 群组间接添加到聊天室、在聊天室中更新或从聊天室中移除的，订阅不会收到这些成员资格事件。如需了解 Google 群组成员资格的运作方式，请参阅向聊天室添加 Google 群组。