构建 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 脚本的卡片服务；如果您使用其他代码语言编写，请返回格式正确的 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 插件。