识别并指定 Google Chat 用户

本页介绍了 Google Chat 应用和开发者如何识别和指定 Chat 用户。

如需执行以下任何操作，Chat 应用或开发者必须指定用户：

Chat 如何识别用户

Google Chat API 会为使用 Chat 的每个人和应用生成一个User 资源。User 资源包含以下字段：

  • name：资源名称，格式为 users/{user}，其中 {user} 表示唯一且稳定的标识符。您可以使用 users/app 作为调用 Chat 应用的别名。
  • displayName：仅输出。用户的显示名称。
  • avatarUrl：仅输出。用户的头像图片网址。
  • email：仅输出。用户的电子邮件地址。
  • domainId：用户 Google Workspace 网域的唯一标识符。
  • type：用户类型。该参数用于指明用户是聊天应用 (BOT) 还是真人 (HUMAN)。
  • isAnonymous：仅输出。如果值为 true，则表示用户已被删除或其个人资料不可见。

用户个人资料详情和公开范围规则

使用用户身份验证调用 Messages 和 Memberships API 时，Google Chat API 会使用个人资料详细信息填充 User 资源。该 API 会为内部用户（您的 Google Workspace 组织中的用户）和外部用户（外部组织中的用户或个人 Google 账号）填充 displayName、email 和 avatarUrl。

以下是一些 API 会填充用户个人资料的位置示例：

隐私权和公开范围规则

为了保护用户隐私，Google Chat API 在确定是否填充用户个人资料详细信息时会应用特定的可见性规则：

  • 已填充的个人资料：如果用户已接受聊天室邀请（是聊天室成员）或与调用用户有先前的亲和度（例如私信互动历史记录），则 API 会填充个人资料详细信息（displayName、email 和 avatarUrl 存在，且 isAnonymous 为 false）。
  • 匿名个人资料：如果用户在聊天室中被提及，但不是聊天室成员，并且之前与调用用户没有亲和关系，则其个人资料保持匿名状态。对于匿名用户，isAnonymous 为 true，并且会省略 displayName、email 和 avatarUrl 等详细信息。不过，对于使用应用身份验证发出的 API 请求，displayName 字段始终会填充。

以下 JSON 示例展示了在 API 响应或互动事件中返回的包含已填充个人资料详细信息的 User 资源：

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

以下 JSON 示例展示了一个匿名 User 资源，其中用户个人资料详细信息对调用方不可见：

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

在对 Google Chat API 的调用中指定用户

如需指定用户，请为 {user} 值使用以下值：

  • 对于 Google Workspace 组织中的用户，请使用以下方法之一：

    • Chat API 中 User 资源的 name，例如 users/123456789。
    • People API 中 Person 资源名称的 {person_id}，其中 resourceName 为 people/{person_id} - 例如，Chat API 中的 users/123456789 表示与 People API 中的 people/123456789 同一个人。
    • Directory API 中 User 资源的 id（例如 Chat API 中的 users/123456789）与 Directory API 中的 users/123456789 代表同一人。
    • 对于通过用户身份验证发出的 API 请求，用户的电子邮件地址将作为别名，例如 users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com。

  • 对于外部 Google Workspace 组织中的用户或使用 Google 账号的用户，请使用以下任一方法：

    • 电子邮件别名 - 例如 users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com 或 users/EMAIL_USERNAME@gmail.com。
    • 从之前的 API 调用或互动事件中获得的 User 资源的规范 name（例如 users/12345678901234567890）。

通过 API 响应或互动事件识别用户

您可以通过多种方式识别从 API 调用或传入事件返回的用户：

由于 Google Chat API 在使用用户身份验证时会填充内部用户和外部用户的个人资料，因此开发者无需调用 Directory API 来解析成员和消息发送者的姓名或电子邮件地址。