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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

Ниже приведен пример рекомендуемой структуры для использования в триггерных функциях, чтобы избежать ошибок авторизации. Пример триггерной функции реагирует на событие отправки формы в надстройке Google Таблиц и, если требуется повторная авторизация, отправляет пользователю надстройки электронное письмо с предупреждением, используя шаблонный 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 Doc A, не может создать триггер для отслеживания открытия Google Doc B.
• Триггеры, управляемые временем, не могут запускаться чаще одного раза в час.
• Надстройки не отправляют пользователю электронное письмо автоматически, когда код, запускаемый устанавливаемым триггером, выдает исключение. Разработчик должен правильно проверять и обрабатывать случаи сбоев.
• Триггеры надстроек перестают срабатывать в любой из следующих ситуаций:
  • Если надстройка удалена пользователем,
  • Если надстройка отключена в документе (при повторном включении триггер снова становится работоспособным), или
  • Если разработчик отменяет публикацию дополнения или отправляет неработающую версию в магазин дополнений.
• Дополнительные триггерные функции выполняются до тех пор, пока не достигнут кода, использующего неавторизованную службу, после чего они останавливаются. Это верно только в том случае, если надстройка опубликована; тот же триггер в обычном проекте Apps Script или неопубликованной надстройке вообще не выполняется, если какая-либо часть сценария требует авторизации.
• На устанавливаемые триггеры распространяются ограничения квоты триггеров Apps Script.