构建 Google Workspace 插件

如果您想构建新的 Google Workspace 插件,请按照以下常规步骤操作:

  1. 设置插件的项目,并选择所有者和协作者。
  2. 设计插件的外观和行为。
  3. 配置插件的项目清单或部署资源。
  4. 编写代码来定义插件的外观和行为。
  5. 验证插件的 OAuth 范围。
  6. 在其扩展的主机应用中测试该插件。
  7. 发布该插件。

设置插件的项目,并选择所有者和协作者

如果您使用 Apps 脚本构建插件,则需要同时创建 Apps 脚本项目和 Google Cloud 项目。如果您使用 Apps 脚本以外的语言构建插件,只需创建 Google Cloud 项目即可。

在开始开发插件之前,请选择一个用户帐号以拥有项目,并决定哪些其他帐号是协作者。项目的所有者可以创建和管理项目文件和关联设置,而协作者可帮助编码和测试。

Apps 脚本项目

您可以在共享云端硬盘中构建插件的 Apps 脚本项目文件,以免单个帐号具有唯一所有权。将插件脚本文件放置在共享云端硬盘中,可确保多个协作者有权访问脚本项目。

发布插件时,发布方使用单个用户帐号。发布帐号必须具有脚本项目的修改权限,但不必是所有者。

如要创建 Apps 脚本项目,请参阅脚本项目

Google Cloud 项目

我们建议您向该插件的 Cloud 项目添加协作者。这有助于确保您的团队中有人始终可以访问该插件的 Cloud 设置。

如需创建 Google Cloud 项目,请参阅创建 Google Cloud 项目

设计插件的外观和行为

在开始构建插件之前,确定插件的外观及其行为。考虑插件应尝试为哪些用例提供解决方案。先从简单的设计开始,然后再添加更多优化。

如需了解如何设计插件用户体验,请参阅 Google Workspace 插件样式指南

配置插件项目清单

在 Apps 脚本项目中,项目清单是一个特殊的 JSON 文件。它指定了有关项目的各种详细信息,例如其库依赖项。对于 Google Workspace 插件,清单还提供了主机应用正确显示插件所需的基本信息。

如需详细了解如何在 Apps 脚本中配置插件的清单,请参阅清单

在向插件添加代码和功能时,请根据需要修改清单,以生成所需的插件外观和行为。

编写插件代码

您必须为该插件实现基于卡片的界面。使用 Apps 脚本的 Card 服务,或者如果您使用另一种代码语言编写,则返回格式正确的 JSON,以便接口呈现为卡片。

此外,您还必须实现插件清单中指定的任何触发器函数。如果您的插件使用 OAuth 连接到第三方非 Google 服务,您还必须为该服务配置 OAuth

构建卡片

您可以通过创建 Card 对象并使用 widget 填充它们来定义插件界面。清单中指定的触发函数必须返回单个 Card 对象或一组 Card 对象(代表插件接口的不同“页面”)。您的插件还可以创建和显示新卡片来响应用户操作。

在 Apps 脚本中,您可以使用 CardBuilder 类创建卡片。每张卡片都需要一个 CardHeader 以及一个或多个 CardSections。您应该使用构成插件界面的各个 widget 填充每个卡片部分。互动 widget 通常与操作相关联,用于定义其互动行为。

通过卡片的 CardBuilder 将所有部分和 widget 添加到卡片后,必须调用 CardBuilder.build() 以创建相应的 Card 对象。

您可以使用其他内置 Apps 脚本服务(如 CalendarApp)检索信息,以便在您构建的插件卡片中显示。您可以使用从非 Google 服务提取的数据。

如果您的 Google Workspace 插件需要访问需要 OAuth 的非 Google API,您必须配置并连接到该服务。如需了解详情,请参阅“连接到非 Google 服务”指南

施工订单

构建卡片时,您必须自上而下构建。也就是说,您必须使用以下构建顺序:

  1. 构建 widget。
  2. 将微件添加到卡片部分。
  3. 重复上述步骤,直到卡片部分包含其所有微件。
  4. 在卡片中添加卡片部分。

这是必需的,因为当您向卡片或卡片部分添加 widget 时,实际上是添加该 widget 的副本。您在添加 widget 对象后对其进行的任何更改都不会反映在最终的卡片中。

通用操作

您可以使用通用操作提供与上下文无关的功能。通用操作是指在插件界面中可用的菜单项(无论显示什么卡片)。所有定义的通用操作始终显示在插件的卡片菜单中。

如需了解详情,请参阅通用操作

验证插件的 OAuth 范围

范围定义了允许插件代表用户执行的操作。对于插件而言,最佳实践是只对功能正常运行所必需的操作提供作用域。

在插件项目中,请明确设置插件范围,以确保插件尽可能使用一组最小权限的范围。您可以在插件清单中定义插件使用的范围。

如需了解详情,请参阅范围

测试插件

您可以先安装未发布的插件,以便测试未发布的插件。安装并授权后,您可以在您的帐号中使用该插件,并在它所扩展的宿主应用中测试其外观和行为。您应验证插件在上下文和用户操作方面的行为是否符合预期。

如需了解详情,请参阅测试 Google Workspace 插件

发布插件

发布插件后,其他人(包括公众或您网域中的用户)均可使用该插件。在开始发布流程之前,请务必查看发布内容概览。发布是一个复杂的过程,需要准备和完成。

Google Workspace 插件已发布到 Google Workspace Marketplace。公开发布的插件必须先完成应用审核,然后才能发布。

如需了解详情,请参阅发布 Google Workspace 插件