Aktywatory do zainstalowania

Podobnie jak proste reguły, reguły instalowane umożliwiają skryptom Apps Script automatyczne wykonywanie funkcji po wystąpieniu określonego zdarzenia, na przykład otwarcia dokumentu. Jednak wyzwalacze do zainstalowania zapewniają większą elastyczność niż proste wyzwalacze: mogą wywoływać usługi, które wymagają autoryzacji, oferują kilka dodatkowych typów zdarzeń, w tym wyzwalacze czasowe (zegarowe), i można nimi sterować programowo. Zarówno w przypadku prostych, jak i instalowalnych wyzwalaczy skrypt Google przekazuje wywoływanej funkcji obiekt zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Ograniczenia

Chociaż uruchamiane przez instalację wyzwalacze zapewniają większą elastyczność niż proste wyzwalacze, podlegają one kilku ograniczeniom:

  • Nie są one wykonywane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). Aby skrypty samodzielne działały prawidłowo, użytkownicy muszą mieć co najmniej uprawnienia do wyświetlania pliku skryptu.

  • Wykonania skryptu i żądania interfejsu API nie powodują uruchamiania aktywatorów. Na przykład wywołanie funkcji FormResponse.submit() do przesłania nowej odpowiedzi na formularz nie powoduje uruchomienia reguły przesłania formularza.

  • Instalowalne wyzwalacze zawsze działają na koncie osoby, która je utworzyła. Jeśli na przykład utworzysz instalowalny, uruchamiany po otwarciu element, będzie on uruchamiany, gdy Twój współpracownik otworzy dokument (jeśli ma uprawnienia do edycji), ale będzie działać na Twoim koncie. Oznacza to, że jeśli utworzysz regułę, która ma wysyłać e-maila po otwarciu dokumentu, e-mail będzie zawsze wysyłany z Twojego konta, a niekoniecznie z konta, które otworzyło dokument. Możesz jednak utworzyć instalowalny wyzwalacz dla każdego konta, co spowoduje wysłanie 1 e-maila z każdego konta.

  • Na danym koncie nie można wyświetlać reguł zainstalowanych z drugiego konta, mimo że pierwsze konto może je nadal aktywować.

  • Wyzwalacze do zainstalowania podlegają limitom limitom kvoty w Apps Script.

Aktywatory oparte na czasie

Wyzwalacz czasowy (zwany też zegarowym) działa podobnie do zadania cron w systemie Unix. Dzięki nim skrypty są wykonywane o określonym czasie lub w określonych odstępach czasu, np. co minutę lub raz w miesiącu. (pamiętaj, że dodatek może używać wyzwalacza czasowego maksymalnie raz na godzinę). Czas może być nieco losowy. Jeśli np. utworzysz powtarzający się przełącznik o godz. 9:00, Google Apps Script wybierze czas między 9:00 a 10:00, a potem będzie konsekwentnie używać tej godziny, tak aby 24 godziny po jej uruchomieniu kończyła się ponownie.

Oto przykład aplikacji Google Chat, która co minutę publikuje wiadomość w każdym pokoju, w którym się znajduje:

// 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),
  });
}

Aktywatory oparte na zdarzeniach

Aktywatory z możliwością zainstalowania oparte na zdarzeniach są podobne pod względem koncepcji do prostych aktywatorów, takich jak onOpen(), ale mogą reagować na dodatkowe zdarzenia i działają inaczej.

Na przykład instalowany wyzwalacz otwarcia w Arkuszach Google aktywuje się, gdy arkusz zostanie otwarty przez dowolnego użytkownika, który ma uprawnienia do edycji, podobnie jak prosty wyzwalacz onOpen(). Wersja instalowana może jednak wywoływać usługi, które wymagają autoryzacji. Wersja instalowalna działa z autoryzacją użytkownika, który utworzył regułę, nawet jeśli inny użytkownik z uprawnieniami do edycji otworzy arkusz.

W przypadku aplikacjiGoogle Workspace jest kilka instalowanych wyzwalaczy:

  • Instalowalny otwarcie reguły działa, gdy użytkownik otworzy arkusz kalkulacyjny, dokument lub formularz, do których ma uprawnienia do edycji.
  • Instalowalny edytowany aktywator działa, gdy użytkownik zmienia wartość w arkuszu kalkulacyjnym.
  • Instalowalny trigger zmiany jest uruchamiany, gdy użytkownik modyfikuje strukturę arkusza kalkulacyjnego, np. dodając nowy arkusz lub usuwając kolumnę.
  • Instalowalny aktywator przesłania formularza działa, gdy użytkownik odpowie na formularz. Istnieją 2 wersje reguły przesyłania formularza: jedna dla samych Formularzy Google i jedna dla Arkuszy Google, jeśli formularz jest przesyłany do arkusza kalkulacyjnego.
  • Instalowalny wyzwalacz zdarzenia w kalendarzu działa, gdy wydarzenia w kalendarzu użytkownika są aktualizowane (tworzone, edytowane lub usuwane).

Instalowalne wyzwalacze możesz używać w samodzielnych i powiązanych skryptach. Na przykład samodzielny skrypt może programowo utworzyć instalowalny przełącznik dla dowolnego pliku Arkuszy Google, wywołując funkcję TriggerBuilder.forSpreadsheet(key) i przekazując identyfikator arkusza kalkulacyjnego.

Ręczne zarządzanie regułami

Aby ręcznie utworzyć instalowalny przełącznik w edytorze skryptu:

  1. Otwórz projekt Apps Script.
  2. Po lewej stronie kliknij Reguły .
  3. W prawym dolnym rogu kliknij Dodaj wyzwalacz.
  4. Wybierz i skonfiguruj typ reguły, którą chcesz utworzyć.
  5. Kliknij Zapisz.

Zarządzanie aktywatorami za pomocą kodu

Możesz też tworzyć i usuwać wyzwalacze programowo za pomocą usługi skryptu. Zacznij od wywołania funkcji ScriptApp.newTrigger(functionName), która zwraca wartość TriggerBuilder.

W tym przykładzie pokazujemy, jak utworzyć 2 aktywacze czasowe: jeden, który działa co 6 godzin, i drugi, który działa co poniedziałek o 9:00 (w strefie czasowej, w której działa skrypt).

triggers/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();
}

Ten przykład pokazuje, jak utworzyć instalowalny regułę otwarcia dla arkusza kalkulacyjnego. Pamiętaj, że w odróżnieniu od prostego onOpen()skryptu, skrypt instalowanego wyzwalacza nie musi być powiązany z arkuszu kalkulacyjnym. Aby utworzyć ten mutator z osobnego skryptu, po prostu zastąp SpreadsheetApp.getActive() wywołaniem funkcji SpreadsheetApp.openById(id).

triggers/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();
}

Aby zmodyfikować istniejący instalowalny wyzwalacz za pomocą kodu, musisz go usunąć i utworzyć nowy. Jeśli identyfikator został już wcześniej zapisany, możesz go usunąć, przekazując go jako argument do funkcji podanej poniżej.

triggers/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;
    }
  }
}

Błędy w regułach

Gdy instalowany przez użytkownika wyzwalacz zostanie uruchomiony, ale funkcja wyrzuci wyjątek lub nie zostanie wykonana, nie zobaczysz komunikatu o błędzie na ekranie. W końcu, gdy reguła czasowa jest wykonywana lub inny użytkownik aktywuje regułę dotyczącą przesyłania formularzy, możesz nawet nie być przy komputerze.

Zamiast tego Apps Script wysyła e-maila podobnego do tego:

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.

E-mail zawiera link do dezaktywacji lub zmiany konfiguracji reguły. Jeśli skrypt jest powiązany z plikiem Arkuszy, Dokumentów lub Formularzy Google, e-mail zawiera też link do tego pliku. Te linki umożliwiają dezaktywowanie reguły lub edytowanie skryptu w celu naprawienia błędu.

Aby sprawdzić wszystkie wyzwalacze powiązane z Twoim kontem Google i dezaktywować te, których już nie potrzebujesz:

  1. Wejdź na stronę script.google.com.
  2. Po lewej stronie kliknij Moje reguły.

  3. Aby usunąć regułę, po jej prawej stronie kliknij Więcej  > Usuń regułę.

Aktywatory w dodatkach

Oprócz reguł instalowanych możesz używać reguł w pliku manifestu w dodatkach. Więcej informacji znajdziesz w artykule Wyzwalacze dla dodatków Google Workspace.