Триггеры для надстроек редактора

Триггеры Apps Script заставляют выполняться указанную функцию скрипта ( функцию-триггер ) всякий раз, когда происходит указанное событие. Триггеры могут срабатывать только при определенных событиях, и каждое приложение Google Workspace поддерживает свой собственный набор событий.

При срабатывании триггера создается объект события . Эта JSON-структура содержит подробную информацию о произошедшем событии. Информация в структуре объекта события организована по-разному в зависимости от типа триггера.

После создания объекта события Apps Script передает его в качестве параметра функции-триггеру. Функция-триггер — это функция обратного вызова, которую вы должны реализовать самостоятельно, чтобы предпринять соответствующие действия в ответ на событие. Например, в надстройке редактора триггер используется для создания пунктов меню надстройки при открытии документа. В этом случае вы реализуете функцию-триггер onOpen(e) , чтобы создать необходимые надстройке пункты меню, возможно, используя данные из объекта события.

На этой странице представлены рекомендации по использованию триггеров в проектах дополнений для редактора.

Типы триггеров дополнений редактора

В дополнениях редактора можно использовать большинство стандартных типов триггеров, доступных для проектов Google Apps Script, включая простые триггеры и большинство устанавливаемых триггеров . Точный набор доступных типов триггеров зависит от расширяемого приложения.

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

В таблице ниже показаны типы простых и устанавливаемых триггеров, которые могут использоваться дополнениями редактора, а также приведены ссылки на соответствующие объекты событий:

Событие	Объект события	Простые триггеры	Устанавливаемые триггеры
Открыть Открывается файл редактора.	Документация по объекту события onOpen Объект события onOpen форм Объект события Sheets onOpen Объект события Slides onOpen	Документы Формы* Листы Слайды function onOpen(e)	Документы Формы Листы
Установить Дополнение установлено.	объект события onInstall	Документы Формы Листы Слайды function onInstall(e)
Редактировать Содержимое ячеек электронной таблицы изменено.	Объект события onEdit в Sheets	Листы function onEdit(e)	Листы
Изменять Содержимое таблицы редактируется или форматируется.	Объект события onChange в Sheets		Листы
Отправить форму Форма Google отправлена.	Объект события отправки формы Объект события отправки формы в Sheets		Формы Листы
Часы (управляемые временем) Затвор срабатывает в заданное время или с заданным интервалом.	Объект события, зависящего от времени	Документы Формы Листы Слайды

* Событие открытия формы в Google Forms происходит не тогда, когда пользователь открывает форму для ответа, а когда редактор открывает форму для ее изменения.

Простые триггеры в дополнениях

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

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

• Функция onOpen выполняется, когда пользователь открывает документ, электронную таблицу или презентацию. onOpen также может выполняться при открытии формы в редакторе (но не при ответе на форму). Она выполняется только в том случае, если у пользователя есть разрешение на редактирование соответствующего файла, и чаще всего используется для создания пунктов меню .
• onInstall выполняется, когда пользователь устанавливает дополнение. Обычно onInstall используется только для вызова onOpen ; это гарантирует, что меню дополнения появятся сразу после установки, без необходимости обновления страницы пользователем.
• onEdit срабатывает, когда пользователь изменяет значение ячейки в электронной таблице. Этот триггер не срабатывает в ответ на перемещение ячеек, форматирование или другие изменения, которые не затрагивают значения ячеек.

Ограничения

На простые триггеры в дополнениях распространяются те же ограничения , что и на простые триггеры в других типах проектов Apps Script. При разработке дополнений следует учитывать эти ограничения:

• Простые триггеры не срабатывают, если файл открыт в режиме только для чтения (просмотр или комментирование). Такое поведение препятствует заполнению меню ваших дополнений.
• В определенных случаях дополнения Editor запускают свои простые триггеры onOpen и onEdit в режиме без авторизации. Этот режим создает сложности, как описано в модели авторизации дополнений .
• Простые триггеры не могут использовать сервисы или выполнять другие действия, требующие авторизации , за исключением случаев, описанных в модели авторизации дополнительных модулей .
• Простые триггеры не могут работать дольше 30 секунд. Минимизируйте объем обработки, выполняемой в функции простого триггера.
• На простые триггеры распространяются ограничения по квоте триггеров в Apps Script.

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

Дополнения могут программно создавать и изменять устанавливаемые триггеры с помощью службы Script Apps Script. Устанавливаемые триггеры дополнений нельзя создать вручную. В отличие от простых триггеров, устанавливаемые триггеры могут использовать службы, требующие авторизации.

Устанавливаемые триггеры в дополнениях не отправляют пользователю электронные письма с ошибками, поскольку в большинстве случаев пользователь не может решить проблему самостоятельно. Поэтому следует разрабатывать дополнения таким образом, чтобы они по возможности корректно обрабатывали ошибки от имени пользователя.

Дополнения могут использовать следующие устанавливаемые триггеры:

• Триггеры, запускаемые при открытии файлов, срабатывают, когда пользователь открывает документ, электронную таблицу или форму в редакторе (но не при заполнении формы).
• Устанавливаемые триггеры срабатывают, когда пользователь изменяет значение ячейки в электронной таблице. Этот триггер не срабатывает в ответ на форматирование или другие изменения, которые не влияют на значения ячеек.
• Триггеры Change, устанавливаемые системой, срабатывают, когда пользователь вносит какие-либо изменения в электронную таблицу, включая форматирование и модификацию самой таблицы (например, добавление строки).

• Устанавливаемые триггеры Form-submit срабатывают при отправке ответа из формы Google Forms.

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

• Триггеры, срабатывающие по времени (также называемые тактовыми триггерами), запускаются в определенное время или повторяются через регулярные промежутки времени.

Авторизация устанавливаемых триггеров

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

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

В отличие от триггеров в обычных проектах Apps Script, триггеры в дополнениях продолжают срабатывать, даже если требуется повторная авторизация. Однако скрипт всё равно завершится с ошибкой, если он обнаружит строку кода, требующую авторизации, которой у него нет. Чтобы избежать этого, используйте ScriptApp.getAuthorizationInfo для ограничения доступа к частям кода, которые изменились между версиями дополнения.

Следующие примеры демонстрируют рекомендуемую структуру для использования в функциях-триггерах, чтобы избежать проблем с авторизацией. Пример функции-триггера реагирует на событие отправки формы в надстройке Google Sheets и, если требуется повторная авторизация, отправляет пользователю надстройки уведомление по электронной почте, используя шаблонный HTML-код.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = "My Add-on Title";
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (
    authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.REQUIRED
  ) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty("lastAuthEmailDate");
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile("AuthorizationEmail");
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(
          Session.getEffectiveUser().getEmail(),
          "Authorization Required",
          message.getContent(),
          {
            name: addonTitle,
            htmlBody: message.getContent(),
          },
        );
      }
      props.setProperty("lastAuthEmailDate", today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Ограничения

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

Помимо этих ограничений, к устанавливаемым триггерам в дополнениях применяются и другие ограничения:

• Каждое дополнение может иметь только один триггер каждого типа для каждого пользователя и для каждого документа. Например, в данной электронной таблице у данного пользователя может быть только один триггер редактирования, хотя у него также может быть триггер отправки формы или триггер, зависящий от времени, в той же электронной таблице. Другой пользователь, имеющий доступ к той же электронной таблице, может иметь свой собственный набор триггеров.
• Дополнения могут создавать триггеры только для того файла, в котором они используются. То есть, дополнение, используемое в документе Google Docs A, не может создать триггер для отслеживания момента открытия документа Google Docs B.
• Запуск триггеров по расписанию не может происходить чаще, чем раз в час.
• Дополнения не отправляют пользователю электронное письмо автоматически, когда код, выполняемый триггером установки, вызывает исключение. Разработчик должен самостоятельно проверять и корректно обрабатывать случаи сбоев.
• Дополнительные триггеры перестают срабатывать в любой из следующих ситуаций:
  • Если пользователь удалит дополнение,
  • Если надстройка отключена в документе (при повторном включении триггер снова становится работоспособным), или
  • Если разработчик удалит дополнение из публикации или отправит в магазин дополнений неработающую версию.
• Функции-триггеры дополнений выполняются до тех пор, пока не достигнут кода, использующего неавторизованную службу, после чего они останавливаются. Это справедливо только в том случае, если дополнение опубликовано; тот же триггер в обычном проекте Apps Script или в неопубликованном дополнении вообще не будет выполняться, если какая-либо часть скрипта требует авторизации.
• На устанавливаемые триггеры распространяются ограничения по квоте триггеров Apps Script.