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

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

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

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

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

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

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

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

Событие Объект события Простые триггеры Устанавливаемые триггеры
Открыть
Открывается файл редактора.		 Объект события Docs onOpen
Объект события Forms onOpen
Объект события Sheets onOpen
Объект события Slides onOpen 		Документы
Формы*
Листы
Слайды

function onOpen(e)

Документы
Формы
Листы
Установить
Дополнение установлено.		 объект события onInstall Документы
Формы
Листы
Слайды

function onInstall(e)

Редактировать
Содержимое ячейки электронной таблицы изменено.		 Объект события Sheets onEdit Листы

function onEdit(e)

Листы
Изменять
Содержимое листа редактируется или форматируется.		 Объект события Sheets onChange Листы
Форма-отправить
Отправляется Google-форма.		 Объект события отправки формы Forms
Объект события отправки формы в таблицах 		Формы
Листы
Управляемый временем (часы)
Триггер срабатывает в указанное время или с заданным интервалом.		 Объект события, управляемого временем Документы
Формы
Листы
Слайды

* Событие открытия для 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 . Устанавливаемые триггеры дополнений нельзя создать вручную. В отличие от простых триггеров, устанавливаемые триггеры могут использовать службы, требующие авторизации.

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

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

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

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

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

Разрешение на установку триггеров

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

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

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

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

Код.gs

триггеры/форма/Code.gs
/**
 * 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.
  }
}

authorizationemail.html

триггеры/форма/AuthorizationEmail.html
<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.