对 Chat 应用和 Google Chat API 请求进行身份验证和授权

身份验证和授权分别用于验证身份和访问资源的机制。本文档简要介绍了 Chat 应用和 Chat API 请求的身份验证和授权机制。

流程概览

下图简要展示了 Google Chat 的身份验证和授权步骤:

Google Chat 身份验证和授权的简要步骤
图 1. Google Chat 身份验证和授权的简要步骤。

  1. 配置 Google Cloud 项目、启用 Chat API 并配置 Chat 应用:在开发过程中,您需要创建一个 Google Cloud 项目。在 Google Cloud 项目中,您将启用 Chat API、配置 Chat 应用并设置身份验证。如需了解详情,请参阅在 Google Workspace 上开发应用构建 Chat 应用

  2. 调用 Chat API:当应用调用 Chat API 时,会向 Chat API 发送身份验证凭据。如果您的应用使用服务帐号进行身份验证,凭据将作为应用代码的一部分发送。如果您的应用需要使用尚未获得授权的用户身份验证方法调用 Chat API,则系统会提示用户登录。

  3. 请求资源:您的应用使用您在设置身份验证时指定的范围请求访问权限。

  4. 征求用户同意:如果您的应用以用户身份进行身份验证,Google 会显示一个 OAuth 同意屏幕,以便用户决定是否授予您的应用访问所请求数据的权限。使用服务帐号进行身份验证不需要用户同意。

  5. 发送已获批准的资源请求:如果用户同意授权范围,您的应用会将凭据和用户批准的范围捆绑到请求中。该请求会发送至 Google 授权服务器,以获取访问令牌。

  6. Google 返回一个访问令牌:该访问令牌包含已授予范围的列表。如果返回的范围列表比请求的范围限制更严格,您的应用会关闭受该令牌限制的所有功能。

  7. 访问所请求的资源:您的应用使用 Google 提供的访问令牌来调用 Chat API 并访问 Chat API 资源。

  8. 获取刷新令牌(可选):如果您的应用必须访问 Google Chat API,且访问时间超出了单个访问令牌的生命周期,则可以获取刷新令牌。如需了解详情,请参阅使用 OAuth 2.0 访问 Google API

  9. 请求更多资源:如果您的应用需要更多访问权限,则会要求用户授予新的范围,因此会发出获取访问令牌的新请求(第 3-6 步)。

哪些 Chat 应用需要进行身份验证时

聊天应用可以发送消息来响应用户互动,也可以异步发送消息。他们还可以代表用户完成任务,例如创建 Chat 聊天室或获取 Chat 聊天室成员列表。

聊天应用无需进行身份验证即可响应用户互动,除非 Chat 应用在处理响应时调用 Chat API 或其他 Google API。

为了发送异步消息或代表用户执行任务,Chat 应用会向 Chat API 发出 RESTful 请求,这些请求需要进行身份验证和授权。

在响应用户互动时无需进行身份验证

Google Chat 应用无需以用户或 Chat 应用的身份进行身份验证即可接收互动事件并同步响应。

每当用户交互或调用 Chat 应用时,Google Chat 应用都会收到互动事件,包括:

  • 用户向 Chat 应用发送消息。
  • 用户用“@”提及一款 Chat 应用。
  • 用户调用 Chat 应用的其中一个斜杠命令

下图显示了 Chat 用户和 Chat 应用之间的请求响应序列:

Chat 应用互动事件无需授权
图 2. Chat 应用互动事件不需要进行身份验证。

  1. 用户向 Google Chat 中的 Chat 应用发送消息。
  2. Google Chat 会将消息转发给应用。
  3. 应用接收消息、对其进行处理,并将响应返回给 Google Chat。
  4. Google Chat 会向用户显示回复,或在聊天室中呈现回复。

此顺序会对每个 Chat 应用互动事件重复。

异步消息需要进行身份验证

当 Chat 应用向 Chat API 发出请求时,会发生异步消息,这需要身份验证和授权。

通过调用 Chat API,Chat 应用可以代表用户向 Google Chat 发布消息或完成任务并访问数据。例如,在检测到服务器中断后,Chat 应用可以调用 Chat API 来执行以下操作:

  • 创建一个专用于调查和解决服务中断情况的 Chat 聊天室。
  • 向 Chat 聊天室添加用户。
  • 在 Chat 聊天室中发布消息,提供有关服务中断的详细信息。

下图显示了 Chat 应用与 Chat 聊天室之间的异步消息序列:

异步消息需要进行身份验证
图 3. 异步消息需要进行身份验证。

  1. Chat 应用通过使用 spaces.messages.create 方法调用 Chat API 来创建消息,并在 HTTP 请求中包含用户凭据。
  2. Google Chat 使用服务帐号或用户凭据对 Chat 应用进行身份验证。
  3. Google Chat 会将应用的消息呈现到指定的 Chat 聊天室中。

Chat API 范围

配置 OAuth 同意屏幕并选择范围,以定义向用户显示的信息和应用审核者,并注册您的应用,以便日后发布。

如需定义授予应用的访问权限级别,您需要确定并声明授权范围。授权范围是一个 OAuth 2.0 URI 字符串,其中包含 Google Workspace 应用名称、所访问的数据类型以及访问权限级别。

非敏感范围

范围代码 说明
https://www.googleapis.com/auth/chat.bot

chat.bot 范围仅支持服务帐号。您无法使用用户凭据或使用此范围的全网域授权进行身份验证。

允许 Chat 应用查看聊天对话和发送消息。授权使用 Chat 应用提供的所有功能。

敏感范围

范围代码 说明
https://www.googleapis.com/auth/chat.spaces 在 Chat 中创建对话和聊天室,以及查看或更新元数据(包括聊天记录设置)。
https://www.googleapis.com/auth/chat.spaces.create 在 Chat 中创建新对话。
https://www.googleapis.com/auth/chat.spaces.readonly 在 Chat 中查看聊天和聊天室。
https://www.googleapis.com/auth/chat.memberships 在 Chat 的对话中查看、添加和移除成员。
https://www.googleapis.com/auth/chat.memberships.app 在 Google Chat 对话中添加和移除自己。
https://www.googleapis.com/auth/chat.memberships.readonly 查看 Chat 对话中的成员。
https://www.googleapis.com/auth/chat.messages.create 在 Chat 中撰写和发送消息。
https://www.googleapis.com/auth/chat.messages.reactions 在 Chat 中查看、添加和删除对消息的回应。
https://www.googleapis.com/auth/chat.messages.reactions.create 在 Chat 中添加对消息的回应。
https://www.googleapis.com/auth/chat.messages.reactions.readonly 在 Chat 中查看对消息的回应。
https://www.googleapis.com/auth/chat.users.readstate 查看和修改 Chat 对话的上次读取时间。
https://www.googleapis.com/auth/chat.users.readstate.readonly 查看 Chat 对话的上次读取时间。

受限范围

范围代码 说明
https://www.googleapis.com/auth/chat.delete 在 Chat 中删除对话和聊天室,并移除对关联文件的访问权限。
https://www.googleapis.com/auth/chat.import 将聊天室、消息和成员资格导入到 Chat。如需了解详情,请参阅授权 Chat 应用导入数据
https://www.googleapis.com/auth/chat.messages 查看、撰写、发送、更新和删除消息,以及添加、查看和删除对消息的回应。
https://www.googleapis.com/auth/chat.messages.readonly 在 Chat 中查看消息和回应。

根据以下定义,上表中的范围指明了它们的敏感性:

如果您的应用需要访问任何其他 Google API,您也可以添加这些范围。如需详细了解 Google API 范围,请参阅使用 OAuth 2.0 访问 Google API

如需详细了解 Google Workspace API 的范围,请参阅配置 OAuth 权限请求页面并选择范围

所需身份验证的类型

Chat 应用可以通过两种方法使用 Chat API 进行身份验证和授权:用户凭据或服务帐号。

通过用户凭据授权,Chat 应用可以代表用户访问用户数据并完成操作。OAuth 范围指定授权数据和操作。

借助应用授权,Chat 应用可以使用服务帐号凭据将 API 作为应用访问。应用授权始终使用 chat.bot 授权范围。

在决定为特定 API 请求使用哪种类型的凭据时,请注意某些 API 方法仅支持特定类型的凭据。如果某个 API 方法同时支持这两种凭据,则调用中使用的凭据类型会影响返回的结果:

  • 使用应用授权时,这些方法仅返回应用可以访问的资源。
  • 获得用户授权后,这些方法将仅返回用户可以在 Chat 界面中访问的资源。

例如,使用应用授权调用 ListSpaces 方法会返回应用所属的聊天室列表。使用用户授权调用 ListSpaces 时,系统会返回用户所属的聊天室列表。在实际操作中,您的应用在调用 Chat API 时可能会使用这两种授权,具体取决于您所需的功能。

对于异步 Chat API 调用

下表列出了 Chat API 方法及其支持的授权范围:

方法 支持用户身份验证 支持应用身份验证 支持的授权范围
聊天室  
创建聊天室 启用用户身份验证后:
  • chat.spaces.create
  • chat.spaces
  • chat.import
设置聊天室 启用用户身份验证后:
  • chat.spaces.create
  • chat.spaces
创建聊天室 启用用户身份验证后:
  • chat.spaces.readonly
  • chat.spaces
使用应用身份验证时:
  • chat.bot
列出聊天室 启用用户身份验证后:
  • chat.spaces.readonly
  • chat.spaces
使用应用身份验证时:
  • chat.bot
更新聊天室 启用用户身份验证后:
  • chat.spaces
  • chat.import
删除聊天室 启用用户身份验证后:
  • chat.delete
  • chat.import
完成聊天室的导入流程 启用用户身份验证后:
  • chat.import
查找私信 启用用户身份验证后:
  • chat.spaces.readonly
  • chat.spaces
使用应用身份验证时:
  • chat.bot
成员  
创建成员 启用用户身份验证后:
  • chat.memberships
  • chat.memberships.app
  • chat.import
获取成员 启用用户身份验证后:
  • chat.memberships.readonly
  • chat.memberships
使用应用身份验证时:
  • chat.bot
列表成员 启用用户身份验证后:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
使用应用身份验证时:
  • chat.bot
删除成员 启用用户身份验证后:
  • chat.memberships
  • chat.memberships.app
  • chat.import
信息  
创建消息 启用用户身份验证后:
  • chat.messages.create
  • chat.messages
  • chat.import
使用应用身份验证时:
  • chat.bot
接收消息 启用用户身份验证后:
  • chat.messages.readonly
  • chat.messages
使用应用身份验证时:
  • chat.bot
列出消息 启用用户身份验证后:
  • chat.messages.readonly
  • chat.messages
  • chat.import
更新消息 启用用户身份验证后:
  • chat.messages
  • chat.import
使用应用身份验证时:
  • chat.bot
删除消息 启用用户身份验证后:
  • chat.messages
  • chat.import
使用应用身份验证时:
  • chat.bot
回应  
创建回应 启用用户身份验证后:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
列出回应 启用用户身份验证后:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
删除回应 启用用户身份验证后:
  • chat.messages.reactions
  • chat.messages
  • chat.import
媒体和附件  
将媒体内容作为文件附件上传 启用用户身份验证后:
  • chat.messages.create
  • chat.messages
  • chat.import
下载媒体内容 启用用户身份验证后:
  • chat.messages.readonly
  • chat.messages
使用应用身份验证时:
  • chat.bot
获取邮件附件 使用应用身份验证时:
  • chat.bot
用户读取状态
获取用户的聊天室读取状态 启用用户身份验证后:
  • chat.users.readstate
  • chat.users.readstate.readonly
更新用户聊天室的读取状态 启用用户身份验证后:
  • chat.users.readstate
获取用户的线程读取状态 启用用户身份验证后:
  • chat.users.readstate
  • chat.users.readstate.readonly
聊天室活动
获取聊天室活动 启用用户身份验证后:
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
列出聊天室活动 启用用户身份验证后:
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly

对于 Chat 应用互动事件

下表列出了用户与 Chat 应用互动的常见方式,以及是否需要或支持身份验证:

场景 无需身份验证 支持用户身份验证 支持应用身份验证
接收来自以下地址的消息:
Chat 应用互动事件
Apps 脚本回调
Google Cloud Pub/Sub
回复消息:
同步(使用 Chat 应用互动事件
同步,使用 Apps 脚本回调返回值
发送新消息:
使用传入的网络钩子