可安装触发器

与简单触发器类似，可安装触发器可让 Google Apps 脚本在发生特定事件（ 例如打开文档）时自动运行函数。不过，可安装触发器比简单触发器更 灵活：它们可以调用 需要授权的 服务，提供多种其他类型的事件（包括基于时间的触发器），并且可以 通过编程方式进行控制。对于简单触发器和可安装触发器， Apps 脚本都会向触发的函数传递一个 事件对象，其中包含有关事件发生时上下文的 信息。

如需详细了解如何在插件中使用触发器，请参阅 Google Workspace 插件的触发器。

限制

虽然可安装触发器比简单触发器更灵活，但仍受到以下几项限制：

  • 如果文件以只读（查看或评论）模式打开，则触发器不会运行。对于独立脚本，用户至少需要对脚本文件拥有查看权限，触发器才能正常运行。

  • 脚本执行和 API 请求不会导致触发器运行。例如， 调用 FormResponse.submit() 以提交新的表单回复不会导致表单的提交触发器运行。

    此限制的例外情况是 Form.submitGrades()。如果您的代码使用 onFormSubmit 触发器，则调用 Form.submitGrades() 会触发 onFormSubmit 条件并导致无限循环。如需防止无限循环，请在调用 submitGrades() 之前添加用于检查成绩是否已存在的代码。

  • 可安装触发器始终在创建者的账号下运行。例如，如果您创建了一个可安装的打开触发器，当您的同事打开文档时（如果您的同事拥有编辑权限），该触发器会运行，但它会以您的账号运行。这意味着，如果您创建了一个触发器，以便在文档打开时发送电子邮件，则电子邮件始终会从您的账号发送，而不一定是打开文档的账号。不过，您可以为每个账号创建一个可安装的触发器，这样每个账号都会发送一封电子邮件。

  • 给定账号无法看到从第二个账号安装的触发器，即使第一个账号仍然可以激活这些触发器也是如此。

  • 可安装触发器受 Apps 脚本触发器 配额限制的约束。

基于时间的触发器

基于时间的触发器（也称为“时钟触发器”）类似于 Unix 中的 cron 作业。基于时间的触发器可让脚本在特定时间或按重复间隔执行，频率可以高达每分钟一次，也可以低至每月一次。（插件最多可以每小时使用一次基于时间的触发器。） 时间可能会略有随机性，例如，如果您创建了一个重复的上午 9 点触发器，Apps 脚本会选择上午 9 点到上午 10 点之间的时间，然后每天保持该时间一致，以便在触发器再次触发之前经过 24 小时。

事件驱动型触发器

可安装的事件驱动型触发器在概念上与 简单触发器类似 onOpen()，但它们可以响应其他事件，并且行为方式 不同。

例如，每当任何拥有编辑权限的用户打开 Google 表格时，可安装的打开触发器都会激活，就像简单的 onOpen() 触发器一样。不过，可安装的版本可以调用 需要 授权的服务。可安装的版本会使用创建触发器的用户的授权运行，即使另一个拥有编辑权限的用户打开了该电子表格也是如此。

Google Workspace 应用有多个可安装的触发器：

  • 当用户打开他们有权修改的电子表格、文档或表单时，可安装的打开 触发器会运行。
  • 当用户修改电子表格中的值时，可安装的修改 触发器会运行。
  • 当用户修改电子表格本身的结构时（例如，添加新工作表或移除列），可安装的更改 触发器会运行。
  • 当用户响应表单时，可安装的表单提交 触发器会运行。表单提交触发器有两个版本， 一个用于 Google 表单本身 以及 一个用于表单提交到电子表格时。
  • 当用户的日历活动更新（创建、修改或删除）时，可安装的日历活动 触发器会运行。

可安装触发器在独立脚本和绑定脚本中均可用。例如，独立脚本可以通过调用TriggerBuilder.forSpreadsheet(key)并传入表格的 ID，以编程方式为任意 Google 表格文件创建可安装的触发器。

手动管理触发器

如需在脚本编辑器中手动创建可安装的触发器，请按以下步骤操作：

  1. 打开您的 Apps 脚本项目。
  2. 点击左侧的触发器 。
  3. 点击右下方的添加触发器 。
  4. 选择并配置要创建的触发器类型。
  5. 点击保存 。

以编程方式管理触发器

使用 Script 服务以编程方式创建和删除触发器。首先调用 ScriptApp.newTrigger(functionName)， 该函数会返回一个 TriggerBuilder。

以下示例展示了如何创建两个基于时间的触发器：一个每 6 小时触发一次，另一个每周一上午 9 点（在脚本设置的时区中）触发一次。

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

下一个示例展示了如何为电子表格创建可安装的打开触发器。与简单的 onOpen() 触发器不同，可安装触发器的脚本不需要绑定到电子表格。如需从独立脚本创建 此触发器，请将 SpreadsheetApp.getActive() 替换为 对 SpreadsheetApp.openById(id)的调用。

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

如需以编程方式修改现有的可安装触发器，您必须将其删除并创建一个新的触发器。如果您之前存储了触发器的 ID，请将该 ID 作为参数传递给以下函数，以将其删除。

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

在创建触发器之前，请验证关联的函数是否拥有所有 必需的 OAuth 权限。

触发器中的错误

当可安装触发器触发但函数抛出异常或未能成功运行时，屏幕上不会显示任何错误消息。毕竟，当基于时间的触发器运行时，或者另一个用户激活了您的表单提交触发器时，您可能甚至不在电脑旁。

相反，Apps 脚本会发送如下电子邮件：

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

该电子邮件包含一个用于停用或重新配置触发器的链接。如果 脚本 绑定 到 Google 表格、文档或表单 文件，则电子邮件还会包含指向该文件的链接。您可以使用这些链接停用触发器或修改脚本以修复 bug。

如需排查脚本中的错误，请点击通知电子邮件中的链接以打开脚本项目。项目打开后，查看执行日志 点击 执行 在 左侧导航面板。日志会显示哪些执行失败，并包含错误消息，以帮助您诊断和修复问题。

由插件创建的可安装触发器不会向用户发送这些电子邮件通知。

如需查看与您的 Google 账号关联的所有触发器并停用不再需要的触发器，请按以下步骤操作：

  1. 前往 script.google.com。
  2. 点击左侧的我的触发器 。
  3. 如需删除触发器，请点击触发器右侧的“更多”图标 > 删除触发器。

如果触发器被停用，其对应的失败通知也会被停用。失败通知是有效触发器的固有组成部分。 因此，如需停止接收特定触发器的所有失败通知，请停用或删除触发器本身。在触发器处于有效状态时，您只能调整这些通知的频率。

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

插件中的触发器

除了可安装触发器之外，您还可以在插件中使用清单触发器。如需了解详情，请参阅 Google Workspace 插件的触发器。