对 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. Call Chat API:当应用调用 Chat API,它会将身份验证凭据发送到 Chat API。如果 应用使用服务账号进行身份验证时,凭据会作为 部分。如果您的应用需要调用 Chat API 使用尚未授予的用户身份验证,它会提示 用户即可登录。

  3. 请求资源:您的应用请求获取以下资源: 范围

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

  5. 发送已批准的资源请求:如果用户同意 授权范围,您的 app 将凭据和用户批准的应用捆绑在一起 请求的范围系统会将请求发送到 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 API, 需要进行身份验证和授权

响应用户互动不需要进行身份验证

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

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

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

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

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

  1. 用户在以下时间后向 Chat 应用发送消息: Google 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 聊天室:

异步消息需要进行身份验证
图 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 扩展应用查看聊天内容和发送消息。

此范围仅支持使用服务账号进行应用身份验证。您 无法使用用户凭据进行身份验证, 全网域授权

敏感范围

范围代码 说明
https://www.googleapis.com/auth/chat.spaces 创建对话和聊天室,以及查看或修改元数据(包括 聊天记录设置和访问权限设置)。
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.admin.spaces.readonly 在 Chat 中查看管理员网域拥有的聊天和聊天室。
https://www.googleapis.com/auth/chat.admin.spaces 在 Chat 中查看或修改管理员网域拥有的聊天和聊天室。
https://www.googleapis.com/auth/chat.admin.memberships.readonly 在 Chat 中查看管理员网域拥有的对话中的成员和管理员。
https://www.googleapis.com/auth/chat.admin.memberships 在 Chat 中查看、添加、更新和移除管理员网域拥有的对话中的成员和管理员。
https://www.googleapis.com/auth/chat.app.spaces

创建对话和聊天室,以及查看或更新元数据(包括 聊天记录设置和访问权限设置)。需要管理员批准

此范围仅支持使用服务账号进行应用身份验证。您无法使用此范围通过用户凭据或全网域授权进行身份验证。

https://www.googleapis.com/auth/chat.app.spaces.create

在 Chat 中创建新对话和聊天室。要求 管理员批准

此范围仅支持使用服务账号进行应用身份验证。您无法使用此范围通过用户凭据或全网域授权进行身份验证。

https://www.googleapis.com/auth/chat.app.memberships

在 Chat 的对话和聊天室中查看、添加、更新和移除成员。 需要管理员批准

此范围仅支持使用服务账号进行应用身份验证。您 无法使用用户凭据进行身份验证, 全网域授权

https://www.googleapis.com/auth/chat.customemojis 在 Chat 中查看、创建和删除自定义表情符号。

受限范围

范围代码 说明
https://www.googleapis.com/auth/chat.delete 删除对话和聊天室,并移除对关联文件的访问权限 。
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 中查看消息和回应。
https://www.googleapis.com/auth/chat.admin.delete 删除管理员网域拥有的对话和聊天室,并移除对关联文件的访问权限 。
https://www.googleapis.com/auth/chat.app.delete

删除 Chat 中的话题和聊天室,并撤消对关联文件的访问权限。 需要管理员批准

此范围仅支持使用服务账号进行应用身份验证。您无法使用此范围通过用户凭据或全网域授权进行身份验证。

根据 以下定义:

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

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

所需身份验证的类型

Chat 应用可通过两种方式进行身份验证和授权: Chat API:

用户身份验证
用户身份验证可让 Chat 应用访问用户数据并代表用户执行操作。OAuth 范围用于指定已获授权的数据和操作。除非 Chat 应用 由管理员安装 或给予 全网域授权 Chat 应用首次对 必须由用户代表用户向 Chat 扩展应用授权 使用 OAuth 同意屏幕
应用身份验证

借助应用身份验证,Chat 应用可以使用服务账号凭据,并以自己的身份访问数据和执行操作。由于 Chat 应用使用自己的凭据访问和处理资源,因此最终用户无需批准 Chat 应用的 API 调用,并且您无法向 OAuth 意见征求屏幕添加支持应用授权的 OAuth 授权范围。

两种类型的 OAuth 授权范围支持应用身份验证:

  • https://www.googleapis.com/auth/chat.bot: 您的 Chat 应用可以调用 Google Chat API 方法来创建、更新、获取 列出或删除它有权访问的资源,例如聊天室中的消息 供最终用户添加您的 Chat 应用。 您的 Chat 应用可以自行授予此授权范围, 无需管理员或最终用户授权。
  • https://www.googleapis.com/auth/chat.app.*开发者预览版): 使用这些范围需要获得一次性管理员批准。接收者 获得管理员批准, 准备 Chat 应用的服务账号以接受管理员批准 创建与 Google Workspace Marketplace 兼容的 OAuth 客户端,并 在 Google Workspace Marketplace SDK 中配置应用。这些范围 允许您的 Chat 应用调用特定的 Google Chat API 方法。例如,chat.app.spaces.create 允许应用创建 Chat 聊天室。

如果某个方法同时支持用户身份验证或应用身份验证,则使用 Chat API 会根据您使用的身份验证类型返回不同的结果:

  • 对于应用身份验证,这些方法仅返回 Chat 应用可以使用。
  • 使用用户身份验证时,这些方法仅返回用户 可以访问。

例如,使用应用授权调用 spaces.list() 方法会返回 Chat 应用所属的聊天室的列表。 使用用户授权调用 spaces.list() 会返回用户所属聊天室的列表。在实践中,您在调用 Chat API 时可能会使用这两种身份验证,具体取决于 Chat 应用的设计和功能。

对于异步 Chat API 调用

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

方法 支持用户身份验证 支持应用身份验证 支持的授权范围
聊天室  
创建聊天室 使用用户身份验证时:
  • chat.spaces.create
  • chat.spaces
  • chat.import
需要应用身份验证管理员批准开发者预览版中提供):
  • chat.app.spaces.create
  • chat.app.spaces
设置聊天室 使用用户身份验证时:
  • chat.spaces.create
  • chat.spaces
获取聊天室 使用用户身份验证时:
  • chat.spaces.readonly
  • chat.spaces
使用管理员权限进行用户身份验证
  • chat.admin.spaces.readonly
使用应用身份验证时:
  • chat.bot
通过应用身份验证管理员批准(适用于开发者预览版):
  • chat.app.spaces
列出聊天室 使用用户身份验证时:
  • chat.spaces.readonly
  • chat.spaces
使用应用身份验证时:
  • chat.bot
搜索聊天室 使用管理员权限进行用户身份验证
  • chat.admin.spaces.readonly
更新聊天室 使用用户身份验证时:
  • chat.spaces
  • chat.import
使用管理员权限进行用户身份验证
  • chat.admin.spaces
通过应用身份验证管理员批准(适用于开发者预览版):
  • chat.app.spaces
删除聊天室 使用用户身份验证时:
  • chat.delete
  • chat.import
使用管理员权限进行用户身份验证
  • chat.admin.delete
需要应用身份验证管理员批准开发者预览版中提供):
  • chat.app.delete
完成聊天室的导入流程 使用用户身份验证时:
  • chat.import
查找私信 使用用户身份验证时:
  • chat.spaces.readonly
  • chat.spaces
使用应用身份验证时:
  • chat.bot
成员  
创建成员 使用用户身份验证时:
  • chat.memberships
  • chat.memberships.app
  • chat.import
使用管理员权限进行用户身份验证
  • chat.admin.memberships
需要应用身份验证管理员批准开发者预览版中提供):
  • chat.app.memberships
获取成员 使用用户身份验证时:
  • chat.memberships.readonly
  • chat.memberships
使用应用身份验证时:
  • chat.bot
使用管理员权限进行用户身份验证
  • chat.admin.memberships.readonly
列表成员 使用用户身份验证
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
使用应用身份验证时:
  • chat.bot
使用管理员权限进行用户身份验证
  • chat.admin.memberships.readonly
删除成员 使用用户身份验证时:
  • chat.memberships
  • chat.memberships.app
  • chat.import
使用管理员权限进行用户身份验证
  • chat.admin.memberships
采用应用身份验证管理员批准(在开发者预览版中提供):
  • chat.app.memberships
更新成员 使用用户身份验证
  • chat.memberships
  • chat.import
使用管理员权限进行用户身份验证
  • chat.admin.memberships
通过应用身份验证管理员批准(适用于开发者预览版):
  • chat.app.memberships
信息  
创建消息 使用用户身份验证
  • 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.customemojis
删除自定义表情符号 使用用户身份验证时:
  • chat.customemojis
获取自定义表情符号 使用用户身份验证时:
  • chat.customemojis
列出自定义表情符号 使用用户身份验证时:
  • chat.customemojis
媒体和附件  
以文件附件的形式上传媒体内容 使用用户身份验证
  • 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.messages
    • chat.messages.readonly
  • 对于与会员身份相关的事件:
    • chat.memberships
    • chat.memberships.readonly
  • 对于聊天室相关活动:
    • chat.spaces
    • chat.spaces.readonly
列出聊天室事件 借助用户身份验证, 您必须为每个请求使用一个范围 事件类型
  • 对于与消息相关的事件:
    • chat.messages
    • chat.messages.readonly
  • 对于与回应相关的事件:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • 对于与会员身份相关的事件:
    • chat.memberships
    • chat.memberships.readonly
  • 对于聊天室相关活动:
    • chat.spaces
    • chat.spaces.readonly

对于 Chat 应用互动事件

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

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