Устанавливаемые триггеры

Как и простые триггеры , устанавливаемые триггеры позволяют Apps Script автоматически запускать функцию при наступлении определённого события, например, открытия документа. Однако устанавливаемые триггеры предлагают большую гибкость, чем простые: они могут вызывать службы , требующие авторизации , предлагают несколько дополнительных типов событий, включая триггеры, управляемые по времени (часам), и ими можно управлять программно. Как для простых, так и для устанавливаемых триггеров Apps Script передаёт вызываемой функции объект события , содержащий информацию о контексте, в котором произошло событие.

Ограничения

Несмотря на то, что устанавливаемые триггеры обеспечивают большую гибкость, чем простые триггеры, они все равно имеют ряд ограничений:

  • Они не запускаются, если файл открыт в режиме только для чтения (просмотра или комментирования). Для корректной работы автономных скриптов пользователям требуется как минимум право просмотра файла скрипта.

  • Выполнение скриптов и запросы API не приводят к срабатыванию триггеров. Например, вызов FormResponse.submit() для отправки нового ответа формы не приводит к срабатыванию триггера отправки формы.

  • Устанавливаемые триггеры всегда запускаются под учётной записью того пользователя, который их создал. Например, если вы создаёте устанавливаемый триггер открытия, он срабатывает, когда ваш коллега открывает документ (если у него есть права на редактирование), но запускается от имени вашей учётной записи. Это означает, что если вы создаёте триггер для отправки электронного письма при открытии документа, письмо всегда будет отправлено с вашей учётной записи, а не обязательно с той, которая открыла документ. Однако вы можете создать устанавливаемый триггер для каждой учётной записи, что приведёт к отправке одного электронного письма с каждой учётной записи.

  • Данная учетная запись не может видеть триггеры, установленные из второй учетной записи, даже если первая учетная запись по-прежнему может активировать эти триггеры.

  • Устанавливаемые триггеры подчиняются ограничениям квоты триггеров Apps Script.

Триггеры, управляемые временем

Триггер, управляемый временем (также называемый триггером часов), аналогичен заданию cron в Unix. Триггеры, управляемые временем, позволяют скриптам выполняться в определённое время или с повторяющимся интервалом, например, каждую минуту или не чаще, чем раз в месяц. (Обратите внимание, что надстройка может использовать триггер, управляемый временем, не чаще одного раза в час.) Время может быть слегка случайным — например, если вы создаёте повторяющийся триггер на 9 утра, Apps Script выбирает время между 9 и 10 утра, а затем поддерживает это время постоянным изо дня в день, чтобы до следующего срабатывания триггера прошло 24 часа.

Триггеры, управляемые событиями

Устанавливаемые событийно-управляемые триггеры концептуально похожи на простые триггеры , такие как onOpen() , но они могут реагировать на дополнительные события и ведут себя по-другому.

Например, устанавливаемый триггер открытия для Google Таблиц активируется при каждом открытии таблицы любым пользователем с правами на редактирование, как и простой триггер onOpen() . Однако устанавливаемая версия может вызывать службы , требующие авторизации . Устанавливаемая версия запускается с авторизацией пользователя, создавшего триггер, даже если другой пользователь с правами на редактирование открывает таблицу.

Существует несколько устанавливаемых триггеров дляGoogle Workspace приложения:

  • Устанавливаемый триггер открытия запускается, когда пользователь открывает электронную таблицу, документ или форму, на редактирование которых у него есть разрешение.
  • Устанавливаемый триггер редактирования срабатывает, когда пользователь изменяет значение в электронной таблице.
  • Устанавливаемый триггер изменений срабатывает, когда пользователь изменяет структуру самой электронной таблицы, например, добавляя новый лист или удаляя столбец.
  • Устанавливаемый триггер отправки формы срабатывает, когда пользователь заполняет форму. Существует две версии триггера отправки формы: одна для самих Google Форм, а другая для Таблиц, если форма отправляется в электронную таблицу .
  • Устанавливаемый триггер событий календаря срабатывает при обновлении событий календаря пользователя — их создании, редактировании или удалении.

Устанавливаемые триггеры можно использовать в автономных и связанных скриптах. Например, автономный скрипт может программно создать устанавливаемый триггер для произвольного файла Google Таблиц, вызвав TriggerBuilder.forSpreadsheet(key) и передав идентификатор таблицы.

Управляйте триггерами вручную

Чтобы вручную создать устанавливаемый триггер в редакторе скриптов, выполните следующие действия:

  1. Откройте проект Apps Script.
  2. Слева нажмите тревоги ».
  3. В правом нижнем углу нажмите «Добавить триггер» .
  4. Выберите и настройте тип триггера, который вы хотите создать.
  5. Нажмите «Сохранить» .

Программное управление триггерами

Вы также можете создавать и удалять триггеры программно с помощью сервиса Script . Начните с вызова ScriptApp.newTrigger(functionName) , который возвращает TriggerBuilder .

В следующем примере показано, как создать два триггера, управляемых по времени: один, который срабатывает каждые 6 часов, и один, который срабатывает каждый понедельник в 9 утра (в часовом поясе, на который настроен ваш скрипт).

триггеры/триггеры.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) .

триггеры/триггеры.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(); }

Чтобы программно изменить существующий устанавливаемый триггер, необходимо удалить его и создать новый. Если вы ранее сохранили идентификатор триггера, вы можете удалить его, передав его в качестве аргумента функции ниже.

триггеры/триггеры.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 Script отправит вам электронное письмо следующего содержания:

From: [email protected] 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 Sheets, Docs или Forms, в письме также содержится ссылка на этот файл. Эти ссылки позволяют деактивировать триггер или отредактировать скрипт, чтобы исправить ошибку.

Чтобы просмотреть все триггеры, связанные с вашей учетной записью Google, и отключить те триггеры, которые вам больше не нужны, выполните следующие действия:

  1. Перейдите на script.google.com .
  2. Слева нажмите Мои триггеры .

  3. Чтобы удалить триггер, справа от триггера нажмите Дополнительно > Удалить триггер .

Триггеры в дополнениях

Помимо устанавливаемых триггеров, в дополнениях можно использовать манифестные триггеры. Подробнее см. в статье Триггеры для дополнений Google Workspace .