将互动式 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 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. 在转换为 Google Workspace 插件下，点击 转换为插件。

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

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

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

  7. 点击保存并测试 。

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

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

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

在确认转换后的 Google Workspace 插件正常运行后，您可以将其提供给所有用户。

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

    前往 Google Chat API 配置页面

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

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

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

您的 Google Chat 应用现在是扩展 Google Chat 的 Google Workspace 插件。

可选：清理或释放未使用的 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 不适用 事件类型可以从触发器中推断出来。
user chat.user

按使用场景划分的请求映射

下表显示了使用 Chat API 互动事件构建的 Google Chat 应用与扩展 Google Chat 的 Google Workspace 插件之间常见使用场景的请求载荷差异。

使用场景 Chat API 互动 Event 载荷 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 包含微件值。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 包含微件值。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": { ... }
    }
  }
}
用户更新卡片消息或对话框中的微件 
{
  "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 操作的微件。对于 HTTP Google Workspace 插件，请将这些操作配置为调用函数端点：
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

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

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

 
{
  "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 插件时，需要对转换之前创建的消息中的卡片互动进行特殊处理。插件使用卡片的 action.function 的完整 HTTP 网址，而使用 Google Chat API 互动事件构建的 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 函数，请将 roles/cloudfunctions.invoker 角色授予每个插件的服务账号。请参阅 使用 IAM 授予访问权限。
  2. 更新令牌验证代码，以使用 Google Workspace 插件服务账号电子邮件地址验证不记名令牌的签名。请参阅 验证来自 Google 的请求。