与简单触发器一样,可安装触发器可让 Apps 脚本在发生特定事件(如打开文档)时自动运行函数。但是,可安装的触发器比简单的触发器更灵活:它们可以调用需要授权的服务,它们提供多种其他类型的事件,包括时间驱动(时钟)触发器,并且可通过程序化方式进行控制。对于简单触发器和可安装的触发器,Apps 脚本都会向已触发的函数传递事件对象,该对象包含有关事件发生的上下文的信息。
限制
虽然可安装触发器比简单触发器更具灵活性,但它们仍然会受到一些限制:
- 如果文件以只读(查看或评论)模式打开,则不会运行。对于独立脚本,用户至少需要脚本文件的查看权限,才能让触发器正常运行。
脚本执行和 API 请求不会导致触发器运行。例如,调用
FormResponse.submit()
提交新的表单回复不会导致表单的提交触发器运行。可安装触发器始终在创建者的帐号下运行。例如,如果您创建一个可安装的打开触发器,该触发器会在同事打开文档(如果同事具有编辑权限)时运行,但会作为您的帐号运行。这意味着,如果您创建一个触发器来在有文档打开时发送电子邮件,那么电子邮件将始终从您的帐号发送,而不一定是打开文档的帐号。但是,您可以为每个帐号创建一个可安装的触发器,这样就会从每个帐号发送一封电子邮件。
给定帐号无法查看通过第二个帐号安装的触发器,即使第一个帐号仍然可以激活这些触发器也是如此。
可安装触发器需遵循 Apps 脚本触发器配额限制。
时间驱动的触发器
时间驱动的触发器(也称为时钟触发器)与 Unix 中的 Cron 作业类似。时间驱动型触发器允许脚本在特定时间或周期性间隔执行,频率最高可达每分钟一次,也可以每月执行一次。(请注意,插件每小时最多可以使用一次时间驱动型触发器。)这个时间可能稍有随机化。例如,如果您创建一个周期性的上午 9 点触发器,Apps 脚本会选择上午 9 点到上午 10 点之间的某个时间,然后每天保持一致的这个时间,以便在触发器再次触发之前经过 24 小时。
以下是 Google Chat 应用的示例,该应用每分钟都会向应用所在的每个聊天室发布一条消息:
// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
// https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.
// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
PropertiesService.getScriptProperties()
.setProperty(e.space.name, '');
return {
'text': 'Hi! I\'ll post a message here every minute. ' +
'Please remove me after testing or I\'ll keep spamming you!'
};
}
// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
PropertiesService.getScriptProperties()
.deleteProperty(e.space.name);
}
// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
var spaceIds = PropertiesService.getScriptProperties()
.getKeys();
var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
for (var i = 0; i < spaceIds.length; ++i) {
postMessage(spaceIds[i], message);
}
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';
// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
var service = OAuth2.createService('chat')
.setTokenUrl('https://accounts.google.com/o/oauth2/token')
.setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
.setClientId(SERVICE_ACCOUNT_EMAIL)
.setPropertyStore(PropertiesService.getUserProperties())
.setScope(SCOPE);
if (!service.hasAccess()) {
Logger.log('Authentication error: %s', service.getLastError());
return;
}
var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
UrlFetchApp.fetch(url, {
method: 'post',
headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
contentType: 'application/json',
payload: JSON.stringify(message),
});
}
事件驱动型触发器
可安装的事件驱动型触发器在概念上与 onOpen()
等简单触发器类似,但它们可以响应其他事件,并且行为方式不同。
例如,只要任何拥有编辑权限的用户打开电子表格,Google 表格的可安装打开触发器就会激活,就像简单的 onOpen()
触发器一样。不过,可安装版本可以调用需要授权的服务。可安装版本会在创建触发器的用户授权下运行,即使另一个具有修改权限的用户打开电子表格也是如此。
有多个适用于Google Workspace 应用的可安装触发器:
- 可安装的 open 触发器会在用户打开他们有权编辑的电子表格、文档或表单时运行。
- 当用户修改电子表格中的值时,系统会运行可安装的修改触发器。
- 当用户修改电子表格本身的结构(例如,添加新工作表或移除列)时,系统会运行可安装的更改触发器。
- 可安装的表单提交触发器会在用户响应表单时运行。表单提交触发器有两种版本,一个用于 Google 表单本身,另一个用于 Google 表格(如果表单提交到电子表格)。
- 可安装的日历活动触发器会在用户的日历活动更新(创建、修改或删除)时运行。
您可以在独立脚本和绑定脚本中使用可安装的触发器。例如,独立脚本可以通过调用 TriggerBuilder.forSpreadsheet(key)
并传入电子表格的 ID,以编程方式为任意 Google 表格文件创建可安装的触发器。
手动管理触发器
如需在脚本编辑器中手动创建可安装的触发器,请按以下步骤操作:
- 打开您的 Apps 脚本项目。
- 点击左侧的触发器图标 。
- 点击右下角的添加触发器。
- 选择并配置要创建的触发器类型。
- 点击保存。
以编程方式管理触发器
您还可以使用脚本服务以编程方式创建和删除触发器。首先,调用 ScriptApp.newTrigger(functionName)
,该方法会返回 TriggerBuilder
。
以下示例展示了如何创建两个时间驱动的触发器:一个每 6 小时触发一次,另一个在每周一早上 9 点(在脚本设置的时区)触发。
接下来这个示例展示了如何为电子表格创建可安装的开放式触发器。请注意,与简单的 onOpen()
触发器不同,可安装触发器的脚本不需要绑定到电子表格。如需通过独立脚本创建此触发器,只需将 SpreadsheetApp.getActive()
替换为对 SpreadsheetApp.openById(id)
的调用即可。
如需以程序化方式修改现有的可安装触发器,您必须将其删除,然后创建新的触发器。如果您之前存储了触发器的 ID,则可以通过将 ID 作为参数传递给以下函数来将其删除。
触发器中的错误
如果可安装的触发器触发,但函数抛出异常或因其他原因而无法成功运行,您屏幕上就不会显示错误消息。毕竟,当时间驱动的触发器运行或者其他用户激活您的表单提交触发器时,您甚至不在计算机旁。
不过,Apps 脚本会向您发送如下电子邮件:
From: noreply-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 帐号相关联的所有触发器并停用不再需要的触发器,请按以下步骤操作:
- 前往
script.google.com
。 - 点击左侧的我的触发器。
如需删除触发器,请在触发器右侧依次点击“更多”图标
> 删除触发器。
插件中的可安装触发器
如需详细了解如何在插件中使用可安装的触发器,请参阅插件触发器。