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

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

Для получения дополнительной информации о том, как использовать триггеры в надстройках, см. раздел «Триггеры для надстроек Google Workspace» .

Ограничения

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

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

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

    Исключением из этого ограничения является Form.submitGrades() . Если ваш код использует триггер onFormSubmit , вызов Form.submitGrades() запускает условие onFormSubmit и приводит к бесконечному циклу. Чтобы предотвратить бесконечный цикл, добавьте код, который проверяет, существуют ли оценки уже, прежде чем вызывать submitGrades() .

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

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

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

Триггеры, срабатывающие по времени

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

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

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

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

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

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

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

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

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

  1. Откройте свой проект Apps Script.
  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();
}

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

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

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

Для устранения ошибок в вашем скрипте перейдите по ссылке в электронном письме с уведомлением, чтобы открыть проект скрипта. После открытия проекта просмотрите журналы выполнения, щелкнув « Выполнения на левой панели навигации. В журналах отображаются сбои выполнения и сообщения об ошибках, которые помогут вам диагностировать и устранить проблему.

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

Чтобы просмотреть все триггеры, связанные с вашей учетной записью 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» .