Aktywatory do zainstalowania

Podobnie jak proste reguły, reguły z możliwością zainstalowania umożliwiają Google Apps Script automatyczne uruchamianie funkcji, gdy wystąpi określone zdarzenie, np. otwarcie dokumentu. Aktywatory z możliwością zainstalowania są jednak bardziej elastyczne niż proste aktywatory: mogą wywoływać usługi wymagające autoryzacji, oferują kilka dodatkowych typów zdarzeń, w tym aktywatory oparte na czasie (zegarowe), i można nimi sterować programowo. W przypadku wyzwalaczy prostych i z możliwością zainstalowania Apps Script przekazuje do wywołanej funkcji obiekt zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Więcej informacji o tym, jak używać wyzwalaczy w dodatkach, znajdziesz w artykule Wyzwalacze w dodatkach do Google Workspace.

Ograniczenia

Mimo że wywoływacze instalowane są bardziej elastyczne niż wywoływacze proste, podlegają one pewnym ograniczeniom:

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

  • Wykonania skryptów i żądania API nie powodują uruchamiania aktywatorów. Na przykład wywołanie FormResponse.submit() w celu przesłania nowej odpowiedzi na formularz nie spowoduje uruchomienia wyzwalacza przesyłania formularza.

    Wyjątkiem od tego ograniczenia jest Form.submitGrades(). Jeśli Twój kod używa wyzwalacza onFormSubmit, wywołanie Form.submitGrades() powoduje wywołanie warunku onFormSubmit i powstanie nieskończonej pętli. Aby zapobiec nieskończonej pętli, dodaj kod, który sprawdza, czy oceny już istnieją, zanim wywołasz funkcję submitGrades().

  • Triggery instalowane zawsze działają na koncie osoby, która je utworzyła. Jeśli na przykład utworzysz instalowany otwarty wyzwalacz, zostanie on uruchomiony, 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 wyzwalacz, który będzie wysyłać e-maila po otwarciu dokumentu, e-mail będzie zawsze wysyłany z Twojego konta, a niekoniecznie z konta, z którego otwarto dokument. Możesz jednak utworzyć wywoływacz instalowany na każdym koncie, co spowoduje wysłanie 1 e-maila z każdego konta.

  • Dane konto nie może wyświetlać wyzwalaczy zainstalowanych z drugiego konta, chociaż może je aktywować.

  • Triggery instalowane podlegają limitom triggerów Apps Script.

Aktywatory oparte na czasie

Wywoływacz oparty na czasie (nazywany też wywoływaczem zegarowym) jest podobny do zadania cron w systemie Unix. Triggery oparte na czasie umożliwiają wykonywanie skryptów o określonej godzinie lub w powtarzających się odstępach czasu, nawet co minutę lub raz w miesiącu. (Dodatek może używać wyzwalacza opartego na czasie maksymalnie raz na godzinę). Czas może być nieco losowy – na przykład jeśli utworzysz cykliczny wyzwalacz o godzinie 9:00, Apps Script wybierze godzinę między 9:00 a 10:00, a potem będzie utrzymywać ten sam czas z dnia na dzień, tak aby przed ponownym uruchomieniem wyzwalacza upłynęły 24 godziny.

Aktywatory oparte na zdarzeniach

Aktywatory instalowane oparte na zdarzeniach są podobne do aktywatorów prostych, takich jak onOpen(), ale mogą reagować na dodatkowe zdarzenia i zachowują się inaczej.

Na przykład aktywator otwierania z możliwością zainstalowania w Arkuszach Google uruchamia się za każdym razem, gdy arkusz kalkulacyjny zostanie otwarty przez dowolnego użytkownika z uprawnieniami do edytowania, podobnie jak prosty aktywator onOpen(). Wersja z możliwością zainstalowania może jednak wywoływać usługi, które wymagają autoryzacji. Wersja instalowana działa z autoryzacją użytkownika, który utworzył wyzwalacz, nawet jeśli arkusz kalkulacyjny otworzy inny użytkownik z uprawnieniami do edycji.

W przypadku aplikacji Google Workspace dostępnych jest kilka wywołań, które można zainstalować:

  • Instalowany wyzwalacz open uruchamia się, gdy użytkownik otworzy arkusz kalkulacyjny, dokument lub formularz, który może edytować.
  • Aktywator edycji, który można zainstalować, uruchamia się, gdy użytkownik zmodyfikuje wartość w arkuszu kalkulacyjnym.
  • Wywoływacz zmiany, który można zainstalować, uruchamia się, gdy użytkownik modyfikuje strukturę samego arkusza kalkulacyjnego, np. dodaje nowy arkusz lub usuwa kolumnę.
  • Aktywator przesłania formularza, który można zainstalować, uruchamia się, gdy użytkownik odpowiada na formularz. Istnieją 2 wersje wyzwalacza przesłania formularza: jedna dla samych Formularzy Google i jedna dla Arkuszy, jeśli formularz przesyła dane do arkusza kalkulacyjnego.
  • Instalowany wyzwalacz wydarzenia w kalendarzu uruchamia się, gdy wydarzenia w kalendarzu użytkownika zostaną zaktualizowane – utworzone, zmodyfikowane lub usunięte.

Triggery instalowane są dostępne w skryptach samodzielnych i powiązanych. Na przykład samodzielny skrypt może programowo utworzyć instalowany wyzwalacz 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ć w edytorze skryptów regułę, którą można zainstalować, wykonaj te czynności:

  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 wyzwalacza, który chcesz utworzyć.
  5. Kliknij Zapisz.

Programowe zarządzanie aktywatorami

Twórz i usuwaj reguły programowo za pomocą usługi Script. Zacznij od wywołania funkcji ScriptApp.newTrigger(functionName), która zwraca TriggerBuilder.

W przykładzie poniżej pokazujemy, jak utworzyć 2 aktywatory oparte na czasie – jeden uruchamiany co 6 godzin, a drugi – w każdy poniedziałek o 9:00 (w strefie czasowej, w której ustawiony jest 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();
}

W tym przykładzie pokazujemy, jak utworzyć instalowany wyzwalacz otwierania arkusza kalkulacyjnego. W przeciwieństwie do prostego aktywatora onOpen() skrypt aktywatora z możliwością zainstalowania nie musi być powiązany z arkuszem kalkulacyjnym. Aby utworzyć ten aktywator z pojedynczego skryptu, zastąp SpreadsheetApp.getActive() wywołaniem 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 programowo zmodyfikować istniejący wyzwalacz instalowany, musisz go usunąć i utworzyć nowy. Jeśli identyfikator aktywatora został wcześniej zapisany, usuń go, przekazując go jako argument do tej funkcji.

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

Zanim utworzysz wyzwalacz, sprawdź, czy powiązana z nim funkcja ma wszystkie niezbędne uprawnienia OAuth.

Błędy w regułach

Gdy wywoływany jest wyzwalacz, który można zainstalować, ale funkcja zgłasza wyjątek lub w inny sposób nie działa prawidłowo, na ekranie nie pojawia się komunikat o błędzie. W końcu, gdy uruchomi się reguła oparta na czasie lub inny użytkownik aktywuje regułę przesyłania formularza, 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 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 ponownej konfiguracji wyzwalacza. 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ą dezaktywację aktywatora lub edytowanie skryptu w celu naprawienia błędu.

Aby rozwiązać problemy ze skryptem, kliknij link w e-mailu z powiadomieniem, aby otworzyć projekt skryptu. Po otwarciu projektu wyświetl logi wykonywania, klikając Wykonania w panelu użytkownika po lewej stronie. Dzienniki pokazują, które wykonania się nie powiodły, i zawierają komunikaty o błędach, które pomagają zdiagnozować i rozwiązać problem.

Triggery instalowane tworzone przez dodatki nie wysyłają użytkownikom tych powiadomień e-mail.

Aby sprawdzić wszystkie wyzwalacze 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ąć wyzwalacz, po prawej stronie wyzwalacza kliknij Więcej > Usuń wyzwalacz.

Jeśli wyłączysz wyzwalacz, wyłączone zostaną też powiązane z nim powiadomienia o błędach. Powiadomienia o błędach są nieodłączną częścią aktywnego wyzwalacza. Aby przestać otrzymywać wszystkie powiadomienia o błędach dotyczące konkretnego wyzwalacza, wyłącz lub usuń sam wyzwalacz. Gdy wyzwalacz jest aktywny, możesz tylko dostosować częstotliwość tych powiadomień.

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

Aktywatory w dodatkach

Oprócz wywołań, które można zainstalować, używaj w dodatkach wywołań z pliku manifestu. Więcej informacji znajdziesz w artykule Triggery w dodatkach do Google Workspace.