Aktywatory do zainstalowania

Podobnie jak proste aktywatory, aktywatory instalacyjne pozwalają Apps Script automatycznie uruchamiać funkcję po wystąpieniu określonego zdarzenia, na przykład otwarcia dokumentu. Aktywatory instalacyjne zapewniają jednak większą elastyczność niż proste reguły: mogą wywoływać usługi, które wymagają autoryzacji. Oferują też kilka dodatkowych typów zdarzeń, w tym aktywatory czasowe (zegarowe), którymi można sterować automatycznie. Zarówno w przypadku aktywatorów prostych, jak i instalacyjnych Apps Script przekazuje uruchamianą funkcję obiekt zdarzenia zawierający informacje o kontekście, w którym wystąpiło zdarzenie.

Uwaga: więcej informacji o używaniu reguł w dodatkach znajdziesz w artykule Wyzwalacze dla dodatków do Google Workspace.

Ograniczenia

Mimo że aktywatory możliwe do zainstalowania zapewniają większą elastyczność niż proste reguły, nadal podlegają kilku ograniczeniom:

• Nie działają, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). Aby aktywatory działały prawidłowo, użytkownicy muszą mieć co najmniej uprawnienia do wyświetlania pliku skryptu w przypadku samodzielnych skryptów.

• Wykonanie skryptu i żądanie interfejsu API nie powoduje uruchomienia aktywatorów. Na przykład wywołanie metody FormResponse.submit() w celu przesłania nowej odpowiedzi formularza nie powoduje uruchomienia reguły przesłania formularza.

  Uwaga: wyjątkiem od tego ograniczenia jest Form.submitGrades(). Jeśli w Twoim kodzie używany jest wyzwalacz onFormSubmit, wywołanie Form.submitGrades() wywoła warunek onFormSubmit i zapętli nieskończoną pętlę. Aby zapobiec nieskończonej pętli, dodaj kod, który sprawdza, czy oceny już istnieją, przed wywołaniem funkcji submitGrades().

• Aktywatory instalacyjne zawsze działają na koncie osoby, która je utworzyła. Jeśli na przykład utworzysz otwarty aktywator z możliwością zainstalowania, będzie się on uruchamiał, gdy współpracownik otworzy dokument (jeśli ma uprawnienia do edycji), ale będzie działać jako Twoje konto. Oznacza to, że jeśli utworzysz regułę wysyłania e-maila po otwarciu dokumentu, będzie on zawsze wysyłany z Twojego konta, a niekoniecznie z konta, z którego został otwarty dokument. Dla każdego konta można jednak utworzyć aktywator możliwy do zainstalowania, co spowoduje wysłanie 1 e-maila z każdego konta.

• Na danym koncie nie widać aktywatorów zainstalowanych z drugiego konta, nawet jeśli pierwsze konto nadal może je aktywować.

• Aktywatory możliwe do zainstalowania podlegają limitom reguł Apps Script.

Aktywatory czasowe

Aktywator czasowy (nazywany też aktywatorem zegara) jest podobny do zadania cron w systemie Unix. Reguły oparte na czasie umożliwiają wykonywanie skryptów o określonym czasie lub w regularnych odstępach czasu, co minutę lub rzadziej, co raz w miesiącu. (Pamiętaj, że dodatek może korzystać z reguły opartej na czasie maksymalnie raz na godzinę). Ten czas może być nieco przypadkowy – jeśli np. utworzysz cykliczny wyzwalacz o 9:00, Apps Script wybierze godzinę z godziny od 9:00 do 10:00, a następnie stosuje tę samą częstotliwość co 24 godziny, zanim reguła zostanie ponownie uruchomiona po 24 godzinach.

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

// 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 = '[e-mail]';

// 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

Zainstalowane aktywatory oparte na zdarzeniach są koncepcyjnie podobne do prostych aktywatorów, takich jak onOpen(), ale mogą reagować na dodatkowe zdarzenia i działają inaczej.

Na przykład instalowalna reguła otwarta w Arkuszach Google aktywuje się za każdym razem, gdy użytkownik otworzy arkusz kalkulacyjny z uprawnieniami do edycji, tak jak w przypadku prostej reguły onOpen(). Wersja do zainstalowania może jednak wywoływać usługi, które wymagają autoryzacji. Wersja do zainstalowania działa z autoryzacją użytkownika, który utworzył regułę, nawet wtedy, gdy inny użytkownik z uprawnieniami do edycji otworzy arkusz kalkulacyjny.

Istnieje kilka instalowanych aktywatorówGoogle Workspace aplikacji:

• Możliwa do zainstalowania reguła otwarta uruchamia się, gdy użytkownik otwiera arkusz kalkulacyjny, dokument lub formularz, do którego edycji ma uprawnienia do edycji.
• Instalowalny aktywator edycji jest uruchamiany, gdy użytkownik modyfikuje wartość w arkuszu kalkulacyjnym.
• Możliwa do zainstalowania aktywator zmiany jest uruchamiana, gdy użytkownik zmieni strukturę arkusza kalkulacyjnego, na przykład dodając nowy arkusz lub usuwając kolumnę.
• Możliwa do zainstalowania reguła przesłania formularza uruchamia się, gdy użytkownik odpowie na formularz. Istnieją 2 wersje reguły przesłania formularza: jedna dla samych Formularzy Google i druga dla Arkuszy, jeśli formularz jest przesyłany do arkusza kalkulacyjnego.
• Możliwy do zainstalowania aktywator wydarzeń w kalendarzu jest uruchamiany, gdy wydarzenia w kalendarzu użytkownika zostaną zaktualizowane, utworzone, edytowane lub usunięte.

Aktywatorów możliwych do zainstalowania możesz używać w samodzielnych i powiązanych skryptach. Na przykład samodzielny skrypt może automatycznie utworzyć możliwy do zainstalowania aktywator dla dowolnego pliku Arkuszy Google, wywołując metodę TriggerBuilder.forSpreadsheet(key) i podając identyfikator arkusza kalkulacyjnego.

Ręczne zarządzanie aktywatorami

Aby ręcznie utworzyć w edytorze skryptów aktywator możliwy do zainstalowania, wykonaj te czynności:

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

Automatyczne zarządzanie aktywatorami

Możesz też tworzyć i usuwać aktywatory automatycznie, korzystając z usługi skryptów. Zacznij od wywołania ScriptApp.newTrigger(functionName), które zwraca TriggerBuilder.

W przykładzie poniżej pokazujemy, jak utworzyć 2 reguły oparte na czasie: jeden uruchamiający się co 6 godzin, a drugi uruchamiany co poniedziałek o 9 rano (w strefie czasowej ustawionej w Twoim skrypcie).

triggers/triggers.gs

Wyświetl w GitHubie

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

W następnym przykładzie pokazujemy, jak utworzyć otwartą aktywator mobilny z możliwością zainstalowania dla arkusza kalkulacyjnego. Pamiętaj, że w przeciwieństwie do prostej reguły onOpen(), skrypt reguły możliwej do zainstalowania nie musi być powiązany z arkuszem kalkulacyjnym. Aby utworzyć ten aktywator z poziomu samodzielnego skryptu, zastąp SpreadsheetApp.getActive() wywołaniem SpreadsheetApp.openById(id).

triggers/triggers.gs

Wyświetl w GitHubie

/**
 * 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 automatycznie zmodyfikować istniejący aktywator możliwy do zainstalowania, musisz go usunąć i utworzyć nowy. Jeśli masz już zapisany identyfikator aktywatora, możesz go usunąć, przekazując go jako argument do poniższej funkcji.

triggers/triggers.gs

Wyświetl w GitHubie

/**
 * 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 aktywatorach

Gdy aktywator możliwy do zainstalowania uruchomi się, ale funkcja zgłosi wyjątek lub jeśli w innym przypadku nie uda się uruchomić, na ekranie nie pojawi się komunikat o błędzie. W końcu, gdy włączy się reguła oparta na czasie lub inny użytkownik aktywuje tę regułę, możesz nawet nie być przy komputerze.

Zamiast tego Apps Script wyśle Ci e-maila podobnego do tego:

From: [e-mail]
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 umożliwiający dezaktywację lub ponowne skonfigurowanie aktywatora. 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 edycję skryptu w celu naprawienia błędu.

Uwaga: instalacyjne aktywatory utworzone przez dodatki nie wysyłają użytkownikom takich e-maili.

Aby sprawdzić wszystkie reguły powiązane z Twoim kontem Google i dezaktywować te, których już nie potrzebujesz, wykonaj te czynności:

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

3. Aby usunąć aktywator, po jego prawej stronie kliknij Więcej > Usuń aktywator.

   Uwaga: na tej stronie nie można dezaktywować prostych aktywatorów, takich jak onOpen(). Zamiast tego musisz edytować odpowiedni skrypt i usunąć funkcję onOpen() lub zmienić jej nazwę.

Aktywatory w dodatkach

Oprócz aktywatorów możliwych do zainstalowania możesz używać w dodatkach aktywatorów w pliku manifestu. Więcej informacji znajdziesz w artykule Wyzwalacze dodatków do Google Workspace.