将互动式 Google Chat 应用转换为 Google Workspace 插件

如果您已构建并发布使用 Google Chat API 互动事件的 Google Chat 应用（例如基于 Google Chat 应用快速入门构建的应用），本页将介绍如何将其转换为可扩展 Google Chat 的 Google Workspace 插件。

通过转换，您的 Google Chat 应用可以使用 Google Workspace 插件框架，从而在 Google Chat 和整个 Google Workspace 中实现新的集成和功能。例如，您可以通过 Google Workspace Marketplace 分发单个 Google Workspace 插件，该插件可扩展 Chat 应用以及其他 Google Workspace 宿主应用（如 Gmail、日历和 Google 文档），而无需像以前那样分发两个制品（一个 Google Chat 应用和一个 Google Workspace 插件）。

限制

在开始转换之前，请查看扩展 Google Chat 的 Google Workspace 加购项的限制，确保您的 Google Chat 应用可以顺利转换，而不会丢失基本功能。

第 1 步：复制现有的 Google Chat 应用代码

转换过程需要更改代码。为避免影响正在运行的 Google Chat 应用，请创建并处理代码副本。

Apps 脚本

  1. 打开现有的 Google Chat 应用 Google Apps 脚本项目。
  2. 点击左侧的概览图标 。
  3. 点击右侧的制作副本图标 。
  4. 点击左侧的项目设置 。
  5. 在 Google Cloud 项目下，点击更改项目。
  6. 输入与现有 Google Chat 应用项目关联的同一项目编号。
  7. 点击设置项目。

HTTP

创建现有代码库的分支或副本，并将其部署为与正式版 Google Chat 应用分开的新服务。

如果您的应用部署在 Google Cloud 上，并且依赖于与 Google Cloud 项目相关联的功能（例如默认 App Engine 身份），则应将新代码部署到与现有 Google Chat 应用项目关联的服务上。

第 2 步：修改复制的代码

与使用 Chat API 互动事件构建的 Google Chat 应用相比，扩展 Google Chat 的 Google Workspace 插件使用不同的请求和响应结构。您需要更新代码，以使用 Google Workspace 加载项 EventObject 而不是 Google Chat API 的 Event 来处理请求和响应。使用代码转换指南修改代码。

第 3 步：为测试用户启用 Google Workspace 插件配置

使用 Google Cloud 控制台为 Google Chat 应用配置 Google Workspace 插件设置：

  1. 前往 Google Cloud 控制台中的 Google Chat API 配置页面。

    前往 Google Chat API 配置页面

  2. 在互动功能下，点击转换为插件。

  3. 启用开启插件配置设置。

  4. 在可见性部分，添加测试用户的电子邮件地址。

  5. 如有必要，请使用您在第 2 步中复制并修改的 Google Chat 应用代码的部署端点网址或 Apps 脚本部署 ID 来更新连接设置。

  6. 点击保存并测试。

第 4 步：测试转换后的应用

使用第 3 步中配置的测试用户账号，全面测试 Google Workspace 加载项功能。验证所有功能和互动。

第 5 步：为所有用户完成转换

验证转换后的 Google Workspace 加载项可正常运行后，您可以向所有用户提供该加载项。

  1. 前往 Google Cloud 控制台中的 Google Chat API 配置页面。

    前往 Google Chat API 配置页面

  2. 在互动功能下，点击转换为插件。系统会打开一个侧边栏。

  3. 在侧边栏中，点击转换为插件。

  4. 输入项目 ID，然后点击转换。

您的 Google Chat 应用现在是一个 Google Workspace 插件，可扩展 Google Chat。

可选：清理或释放未使用的 Google Cloud 资源

（可选）将 Google Chat 应用转换为 Google Workspace 加载项后，为避免系统因 Google Chat 应用使用的不再使用的资源而向您的 Google Cloud 账号收取费用，请考虑关闭这些资源。

代码转换指南

本部分详细介绍了 Google Chat API 互动 Event 格式与 Google Workspace 加载项 EventObject 格式之间的映射关系。

请求映射

下表显示了 Google Chat API Event 中的字段与 Google Workspace 加载项 EventObject 中相应字段的对应关系。

Google Chat API 交互 Event 字段 Google Workspace 加购项 EventObject 字段 备注
action.actionMethodName 不适用 对于卡片互动，方法名称可以作为参数在 commonEventObject.parameters 中传递。请参阅打开初始对话框。
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 根据事件类型，在不同的载荷中提供。
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 根据事件类型，在不同的载荷中提供。
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 根据事件类型，在不同的载荷中提供。
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 根据事件类型，在不同的载荷中提供。
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 根据事件类型，在不同的载荷中提供。
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 根据事件类型，在不同的载荷中提供。
token 不适用 验证处理方式有所不同，请参阅 HTTP 应用的请求验证。
type 不适用 可以从 trigger 中推断出事件类型。
user chat.user

按使用情形划分的请求映射

下表显示了使用 Chat API 交互事件构建的 Google Chat 应用与扩展 Google Chat 的 Google Workspace 加载项在常见用例的请求载荷方面的差异。

使用场景 Chat API 交互 Event Payload Google Workspace 加购项 EventObject 载荷
已将应用添加到聊天室 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
从聊天室中移除应用 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
用户使用“@”提及应用 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
用户通过 @ 提及应用将其添加到聊天室 您需要处理来自 Google Chat 的一项请求：
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 您必须处理来自 Google Chat 的两项请求。

第一项请求：
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

第二个请求：
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
斜杠命令 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
用于将应用添加到聊天室的斜杠命令 您需要处理来自 Google Chat 的一项请求：
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 您必须处理来自 Google Chat 的两项请求。

第一项请求：
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

第二个请求：
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
用户点击卡片或对话框上的按钮 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

对于对话框事件，common.formInputs 包含 widget 值。Google Apps 脚本示例：

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

对于对话框事件，commonEventObject.formInputs 包含 widget 值。Google Apps 脚本示例：

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
用户在应用首页卡片中提交信息 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
用户使用快捷命令调用应用命令 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
链接预览 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
用户在卡片消息或对话框中更新了 widget 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

按使用情形划分的响应映射

扩展 Google Chat 的 Google Workspace 插件会返回操作，而不是 Message 对象。下表列出了 Google Chat API Message 响应类型与其 Google Workspace 插件操作等效项之间的对应关系。

使用场景 Google Chat API Message 响应 Google Workspace 加载项 Chat 操作响应
在调用的聊天室中创建消息 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse 为可选项。如需了解详情，请参阅回复斜杠命令。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

如需了解详情，请参阅发送消息。
更新消息 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

如需了解详情，请参阅更新消息 (Chat)。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

如需了解详情，请参阅更新消息（插件）。
链接预览 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

如需了解详情，请参阅预览链接 (Chat)。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

如需了解详情，请参阅预览链接（插件）。
打开初始对话框 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

如需了解详情，请参阅打开对话框 (Chat)。

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
您推送的卡片可以包含具有 onClick 操作的 widget。对于 HTTP Google Workspace 插件，请配置以下操作以调用函数端点：
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

如需了解详情，请参阅打开对话框（插件）。
关闭对话框 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

如需了解详情，请参阅关闭对话框（聊天）。

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

如需了解详情，请参阅关闭对话框（插件）。
连接到外部系统（请求配置） 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

如需了解详情，请参阅连接到外部系统。

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

如需了解详情，请参阅将 Google Workspace 插件与第三方服务相关联。
互动微件上的自动补全项 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

如需了解详情，请参阅添加多选菜单。

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

如需了解详情，请参阅收集和处理 Google Chat 用户的信息。

处理转化前创建的消息中的卡片互动

将 HTTP Google Chat 应用转换为 Google Workspace 插件时，对于在转换之前创建的消息，卡片互动需要特殊处理。Google Workspace 插件使用卡片的 action.function 的完整 HTTP 网址，而使用 Google Chat API 互动事件构建的 Google Chat 扩展应用则使用函数名称。下表总结了这些差异。

使用 Google Chat API 互动事件构建的 Google Chat 应用 可扩展 Google Chat 的 Google Workspace 加载项
配置 您可以在 Google Cloud 控制台中为所有事件配置单个端点。在实现卡片互动时，卡片的 action 仅包含要执行的函数的名称。系统会针对卡片点击事件调用通用 HTTP 端点。

如需了解详情，请参阅打开对话框 (Chat)。



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 您可以选择在 Google Cloud 控制台中配置每个事件的端点，但这不包括卡片点击事件。在实现卡片互动时，卡片的 action 必须包含要调用的 HTTP 端点的完整网址。您可以为每个按钮设置唯一的 HTTP 端点，也可以使用通用端点并在 action.parameters 中传递操作作为参数。

如需了解详情，请参阅打开对话框（插件）。



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

为确保卡片互动功能适用于转化前创建的消息，请在 Google Chat API 配置页面上配置卡片互动网址。

此网址仅用于在您转换应用之前创建的消息中的互动。当用户与其中一条消息互动时，系统会将原始 action.function 值作为名为 __action_method_name__ 的参数传递。

示例：卡片点击

如果您将卡片互动网址配置为 https://.../card-interaction-handler，并且用户点击了历史消息中的卡片，则会发生以下操作：

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

系统会以以下格式将事件传递到您配置的卡片互动网址：

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

示例：多选菜单

如果用户与具有外部数据源的多选菜单互动，则：

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

系统会以以下格式将事件传递到您配置的卡片互动网址：

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

如果您为 HTTP 触发器开启了为所有触发器使用通用 HTTP 端点网址，则通用网址也会用于点击按钮事件。

验证扩展 Chat 的 HTTP Google Workspace 加载项的请求

对于基于 HTTP 的 Google Chat 应用，在转换为 Google Workspace 插件时，需要更新用于验证请求是否来自 Google 的逻辑。

请求验证方面的主要区别在于：

应用类型 支持的受众群体 服务账号电子邮件地址
使用 Google Chat API 互动事件构建的 Google Chat 应用 项目编号 chat@system.gserviceaccount.com
扩展 Google Chat 的 Google Workspace 加载项 仅限 HTTP 端点 项目级服务账号电子邮件地址

您可以在 Google Cloud 控制台的 Google Chat API 配置页面上的转换为 Google Workspace 插件部分中找到 Google Workspace 插件的唯一服务账号电子邮件地址。

如需在升级后的 Google Workspace 加购项中验证请求，请执行以下操作：

  1. 如果使用 Cloud Run functions 函数，请将 roles/cloudfunctions.invoker 角色授予每个插件的服务账号。请参阅使用 IAM 授予访问权限。
  2. 更新令牌验证代码，以使用 Google Workspace 加购项服务账号电子邮件地址来验证不记名令牌的签名。请参阅验证来自 Google 的请求。