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

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

Ограничения

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

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

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

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

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

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

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

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

Ниже приведен пример приложения Google Chat , которое каждую минуту отправляет сообщение во все места, где находится приложение:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

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

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

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

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

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

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

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

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

  1. Откройте проект Apps Script.
  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: noreply-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. Чтобы удалить триггер, справа от него нажмите Еще > Удалить триггер .

Триггеры в дополнениях

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