将 Chat 应用与其他服务和工具相关联

本页介绍了如何将 Google Chat 应用与 Google Chat 之外的服务或工具相关联。虽然 Chat 应用本身功能强大，但它们通常与其他系统协同工作，并且需要配套应用来关联账号、授权数据访问、显示其他数据或配置用户偏好设置。

如需使用第三方服务或 OAuth 流程对用户进行身份验证，您的 Chat 应用会执行以下步骤：

1. 检测何时需要授权或配置。
2. 返回基本授权卡片，提示用户登录或配置服务。
3. 重定向到完成 URI，以便 Google Chat 在用户完成授权后自动重试原始互动。

前提条件

检测到需要授权

在与 Chat 应用互动时，用户可能因各种原因（例如以下原因）而未获授权访问受保护的资源：

• 用于连接到第三方服务的访问令牌尚未生成或已过期。
• 访问令牌不涵盖所请求的资源。
• 访问令牌不包含请求所需的作用域。

您的 Chat 应用应检测到这些情况，以便用户登录并授权访问您的服务。

如果您在 Apps 脚本中进行构建，可以使用 OAuth2 for Google Apps 脚本库（或 OAuth1 版本），其中的 hasAccess 函数用于检查用户是否已授权访问某项服务。或者，在使用 UrlFetchApp.fetch 请求时，您可以将 muteHttpExceptions 参数设置为 true，以检查返回的 HttpResponse 对象中的响应代码和内容。

使用基本授权卡提示用户

当 Chat 应用检测到需要授权或配置时，请返回 AuthorizationError 响应，以向用户显示私密的基本授权卡片。

下图展示了 Google 的基本授权卡的示例：

如需向用户显示基本授权卡片，请返回 AuthorizationError 对象：

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

替换以下内容：

• AUTHORIZATION_URL：用于处理身份验证、授权或配置的 Web 应用的 HTTPS 网址。
• RESOURCE_DISPLAY_NAME：受保护的资源或服务的显示名称。此名称会显示在授权提示中。例如，如果您的 RESOURCE_DISPLAY_NAME 为 Example Account，则提示会说明应用需要获得批准才能访问您的 Example Account。

完成配置请求

在 Chat 中，用户可以完成授权流程，然后 Chat 会自动重试原始互动，而无需手动刷新。如果触发器是消息、添加到聊天室或应用命令，Chat 支持自动重试。

对于这些触发器，您的 Chat 应用会在事件载荷中收到完成重定向 URI (configCompleteRedirectUri / completeRedirectUri)：

• 消息：chat.messagePayload.configCompleteRedirectUri
• 已添加到聊天室：chat.addedToSpacePayload.configCompleteRedirectUri
• 应用命令：chat.appCommandPayload.configCompleteRedirectUri

您必须在 <var>AUTHORIZATION_URL</var> 中对相应重定向 URI 进行编码，并在授权流程完成后将用户的浏览器重定向到该 URI。重定向到此网址会向 Google Chat 表明授权或配置请求已完成。

当用户成功重定向到原始事件载荷中提供的完成重定向 URI 时，Google Chat 会执行以下步骤：

1. 清除向发起用户显示的私密授权提示。
2. 将原始消息转换为公开消息，使聊天室的其他成员能够看到该消息。
3. 第二次将原始事件对象发送到您的 Chat 应用。

如果您不重定向到完成重定向 URI，用户仍然可以完成授权流程，但 Google Chat 不会自动重试之前的执行，用户必须手动再次调用您的 Chat 应用。

访问完成重定向 URI 只会影响单次用户互动。如果用户多次向 Chat 应用发送消息并收到多个提示，则完成一个提示的身份验证和配置流程只会重试该特定互动。

在 Chat 之外对 Chat 用户进行身份验证

当链接到 Chat 之外的网址（例如 OAuth 网络回调）时，您通常需要将外部网络会话与 Chat 中的用户身份相关联。建议您使用 Google 登录来保护目标 Web 应用。

使用登录期间签发的身份令牌获取用户 ID。sub 声明包含用户的唯一 Google ID，并且可以与 Google Chat 中的用户资源名称 (chat.user.name) 相关联。

如需将 sub 声明与 Google Chat users/{user} 资源名称相关联，请在 sub 声明值前面添加 users/。例如，sub 声明值 123 对应于发送到 Chat 应用的事件对象中的 users/123。

代码示例

以下代码示例演示了 Chat 应用如何使用基本授权卡片请求离线 OAuth2 凭据、将其存储在数据库中、重定向到完成 URI，以及通过用户身份验证进行 API 调用：

相关主题

• 接收和回应用户互动
• 对 Google Chat 应用和 Google Chat API 请求进行身份验证和授权
• 将 Google Workspace 插件与第三方服务相关联

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}