Aktywatory do zainstalowania

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

Uwaga: więcej informacji o używaniu 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 do interfejsu API nie powodują uruchamiania aktywatorów. Na przykład wywołanie funkcji FormResponse.submit() w celu przesłania nowej odpowiedzi w formularzu nie spowoduje uruchomienia wyzwalacza przesyłania formularza.

  Uwaga: wyjątkiem od tego ograniczenia jest Form.submitGrades(). Jeśli Twój kod używa wyzwalacza onFormSubmit, wywołanie Form.submitGrades() triggers spowoduje spełnienie warunku onFormSubmit i utworzenie 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 współpracownik otworzy dokument (jeśli ma do niego dostęp 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.

• Konto nie widzi reguł zainstalowanych z drugiego konta, mimo że 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. (Pamiętaj, że dodatek może używać wywoływacza opartego na czasie maksymalnie raz na godzinę). Godzina może być nieco losowa – na przykład jeśli utworzysz wyzwalacz cykliczny o godzinie 9:00, Apps Script wybierze godzinę między 9:00 a 10:00, a potem będzie utrzymywać tę godzinę z dnia na dzień, tak aby przed ponownym uruchomieniem wyzwalacza upłynęły 24 godziny.

Aktywatory oparte na zdarzeniach

Aktywatory z możliwością zainstalowania wywoływane przez zdarzenia są podobne do prostych aktywatorów, np. onOpen(), ale mogą reagować na dodatkowe zdarzenia i działają inaczej.

Na przykład instalowany otwarty wyzwalacz w Arkuszach Google aktywuje się za każdym razem, gdy arkusz kalkulacyjny zostanie otwarty przez dowolnego użytkownika, który ma do niego dostęp do edycji, podobnie jak prosty wyzwalacz onOpen(). Wersja instalacyjna 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.

Istnieje kilka wywołań, które można zainstalować w Google Workspace aplikacjach:

• 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 możesz stosować 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 TriggerBuilder.forSpreadsheet(key) i przekazując identyfikator arkusza kalkulacyjnego.

Ręczne zarządzanie regułami

Aby ręcznie utworzyć wywoływacz instalowany w edytorze skryptów, 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

Wyzwalacze możesz też tworzyć i usuwać programistycznie za pomocą usługi skryptów. 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

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 tym przykładzie pokazujemy, jak utworzyć instalowany otwarty wyzwalacz do arkusza kalkulacyjnego. Pamiętaj, że w przeciwieństwie do prostego wyzwalacza onOpen() skrypt wyzwalacza instalowanego nie musi być powiązany z arkuszem kalkulacyjnym. Aby utworzyć ten wyzwalacz z pojedynczego skryptu, po prostu 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 programowo zmodyfikować istniejący wywoływacz instalowany, musisz go usunąć i utworzyć nowy. Jeśli identyfikator aktywatora został wcześniej zapisany, 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;
    }
  }
}

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: [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 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.

Uwaga: instalowane wyzwalacze utworzone przez dodatki nie wysyłają użytkownikom tych powiadomień e-mail.

Aby sprawdzić wszystkie wyzwalacze powiązane z Twoim kontem Google i wyłączyć 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.

   Uwaga: prostych reguł, takich jak onOpen(), nie można dezaktywować na tej stronie. Zamiast tego musisz edytować odpowiedni skrypt i usunąć lub zmienić nazwę funkcji onOpen().

Aktywatory w dodatkach

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