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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Откройте проект скрипта приложений.
  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();
}

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

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

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

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

  1. Перейдите на script.google.com .
  2. Слева нажмите Мои триггеры .
  3. Чтобы удалить триггер, справа от триггера нажмите Еще > Удалить триггер .

Устанавливаемые триггеры в надстройках

Дополнительные сведения об использовании устанавливаемых триггеров в надстройках см. в разделе Триггеры надстроек.