可安装触发器

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

简单触发器一样,当发生特定事件(例如打开文档)时,可安装触发器让 Apps 脚本自动运行函数。不过,与简单的触发器相比,可安装的触发器可提供更高的灵活性:它们可以调用需要授权服务,它们还可以提供几种其他类型的事件,包括时间驱动型(时钟)触发器,并且可以以编程方式进行控制。对于简单触发器和可安装触发器,Apps 脚本都会向触发的函数传递事件对象,其中包含有关事件的发生环境的信息。

限制

虽然可安装的触发器比简单的触发器更灵活,但仍然受到若干限制:

  • 系统不会以只读(查看或评论)模式打开文件。对于独立脚本,用户至少需要查看脚本文件,触发器才能正常运行。
  • 脚本执行和 API 请求不会导致触发器运行。例如,调用 FormResponse.submit() 以提交新的表单响应不会导致表单的提交触发器运行。

  • 可安装触发器始终使用创建它们的用户帐号运行。例如,如果您创建一个可安装的开放触发器,当同事打开文档时(如果同事拥有编辑权限),则该触发器会运行,但它会以您的帐号的身份运行。这意味着,如果创建触发器以便在文档打开时发送电子邮件,则系统始终会通过您的帐号(不一定是打开了文档的帐号)发送电子邮件。但是,您可以为每个帐号创建一个可安装的触发器,以便每个帐号都发送一封电子邮件。

  • 即使第一个帐号仍可激活这些触发器,给定帐号也无法看到从另一个帐号安装的触发器。

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

时间驱动型触发器

时间驱动型触发器(也称为时钟触发器)类似于 Unix 中的 cron 作业。通过时间驱动型触发器,脚本可以在特定时间或按周期性时间间隔执行,频率为每分钟一次,或每月一次。(请注意,插件每小时最多可以使用一次时间驱动型触发器。)该时间可能会略有随机性 - 例如,如果您创建上午 9 点的周期性触发器,则 Apps 脚本会选择上午 9 点到上午 10 点之间的时间,然后保持该时间在一天内保持一致,以使该触发器在 24 小时后再次触发。

事件驱动型触发器

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

例如,每当有修改权限的用户打开电子表格时,适用于 Google 表格的可安装开放触发器都会激活,就像简单的 onOpen() 触发器一样。不过,安装版可以调用需要授权服务。安装版本会在获得触发器创建者授权的情况下运行,即使拥有修改权限的另一个用户打开电子表格也是如此。

有几个适用于应用的可安装触发器: Google Workspace

  • 当用户打开他们有权编辑的电子表格、文档或表单时,可安装的打开触发器会运行。
  • 当用户修改电子表格中的值时,可安装的 edit 触发器会运行。
  • 当用户修改电子表格本身的结构(例如,添加新工作表或移除列)时,可安装更改触发器会运行。
  • 当用户回复表单时,系统会运行可安装的表单提交触发器。表单提交触发器有两种版本:一种用于 Google 表单本身另一种用于 Google 表格(如果表单提交到电子表格)。
  • 当用户的日历活动更新(创建、修改或删除)时,可安装日历活动触发器会运行。

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

手动管理触发器

如需在脚本编辑器中手动创建安装式触发器,请按以下步骤操作:

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

以编程方式管理触发器

您还可以使用脚本服务以编程方式创建和删除触发器。首先,调用 ScriptApp.newTrigger(functionName) 以返回 TriggerBuilder

以下示例展示了如何创建两个时间驱动型触发器,一个每 6 小时触发一次,另一个在每周一上午 9 点触发(以您的脚本设置为的时区)。

触发器/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.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.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;
    }
  }
}

触发器中的错误

当安装式触发器触发但函数抛出异常或无法成功运行时,屏幕上不会显示错误消息。毕竟,当时间驱动的触发器运行或另一个用户激活您的表单提交触发器时,您甚至可能不在电脑前。

不过,Apps 脚本会向您发送如下电子邮件:

From: apps-scripts-notifications@google.com
Subject: Summary of failures for Google 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. 如需删除触发器,请点击触发器右侧的“更多”图标 > 删除触发器

插件中的可安装触发器

如需详细了解如何在插件中使用安装式触发器,请参阅插件触发器