订阅 Google Chat 活动

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

除了订阅事件之外，您还可以通过调用 Google Chat API 查询事件。调用 Chat API 可让您定期检索事件，或补全因服务中断而可能错过的订阅事件。如需了解接收和响应 Chat 事件的方式，请参阅 Chat 文档中的 使用 Chat 事件。

支持的 Chat 事件

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

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

您可以监控事件的资源

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

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

目标资源 格式 限制
聊天室

//chat.googleapis.com/spaces/SPACE

其中，SPACE 是 Chat API space 资源的资源名称中的 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 事件的结构。

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

事件类型 格式 资源数据
聊天室订阅  
发布了消息。

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)，您的 Chat 应用会自动配置为接收批量回应事件 (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 聊天室中成员的事件，请指定要在事件载荷中接收的成员资格资源的字段。

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

示例 事件类型 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 网上论坛群组。