Reguły do zainstalowania

Podobnie jak proste aktywatory, które można zainstalować, pozwalają aplikacji automatycznie uruchamiać funkcję po wystąpieniu określonego zdarzenia, takiego jak otwarcie dokumentu. Reguły, które można zainstalować, zapewniają jednak większą elastyczność niż proste aktywatory: mogą wywoływać usługi, które wymagają autoryzacji, udostępniają kilka dodatkowych typów zdarzeń, w tym aktywatory czasowe (zegary), które można sterować automatycznie. W przypadku prostych i łatwych do zainstalowania aktywatorów Apps Script przekazuje aktywowaną funkcję obiektu zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Uwaga: informacje o używaniu aktywatorów możliwych do zainstalowania w projektach dodatków znajdziesz w artykule Wyzwalacze dodatków.

Ograniczenia

Reguły, które można zainstalować, są bardziej elastyczne niż proste aktywatory, ale podlegają pewnym ograniczeniom:

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

• Wykonywanie skryptów i żądania interfejsu API nie powodują uruchomienia aktywatorów. Na przykład wywołanie FormResponse.submit() w celu przesłania nowej odpowiedzi nie powoduje uruchomienia reguły przesyłania formularza.

  Uwaga: wyjątek tego ograniczenia to Form.submitGrades(). Jeśli Twój kod wykorzystuje regułę onFormSubmit, wywołanie metody Form.submitGrades() wywołuje warunek onFormSubmit i powoduje nieskończoną pętlę. Aby uniknąć nieskończonej pętli, przed wywołaniem metody submitGrades() dodaj kod, który sprawdza, czy oceny już istnieją.

• Reguły, które można zainstalować, są zawsze uruchamiane na koncie osoby, która je utworzyła. Jeśli na przykład utworzysz aktywator, który można zainstalować, zostanie on uruchomiony, 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 aktywator wysyłania e-maili po otwarciu dokumentu, wiadomość ta będzie zawsze wysyłana z Twojego konta, a nie z konta, na którym został otwarty. Dla każdego konta możesz jednak utworzyć aktywator do zainstalowania, co spowoduje wysłanie jednego e-maila z każdego z nich.

• Na tym koncie nie można zobaczyć reguł zainstalowanych z drugiego konta, mimo że pierwsze konto nadal może je aktywować.

• Reguły, które można zainstalować, podlegają limitom limitów aktywatorów Apps Script.

Reguły oparte na czasie

Aktywator działający na podstawie czasu (nazywany też aktywatorem zegara) jest podobny do zadania cron w systemie Unix. Reguły oparte na czasie umożliwiają skryptom wykonywanie skryptów w określonym czasie lub cyklicznie, z taką częstotliwością jak minuta lub nie częściej niż raz na miesiąc. (Pamiętaj, że dodatek może używać aktywatora opartego na czasie maksymalnie raz na godzinę). Godzina może być nieco losowa – jeśli np. utworzysz cykliczną regułę o 9:00, Google Apps Script ustawi godzinę między 9:00 a 10:00, a następnie zadbaj o to, aby czas między nimi był codziennie utrzymywany tak, aby 24 godziny pozostało bez zmian.

Reguły oparte na zdarzeniach

Reguły możliwe do zainstalowania na podstawie zdarzeń są podobne do prostych reguł takich jak onOpen(), ale mogą reagować na dodatkowe zdarzenia, ale działają inaczej.

Na przykład reguła otwierająca dla Arkuszy Google, którą można zainstalować, jest uruchamiana za każdym razem, gdy arkusz kalkulacyjny jest otwierany przez dowolnego użytkownika z uprawnieniami do edycji – tak jak prostą regułę onOpen(). Wersja do zainstalowania może jednak wywoływać usługi, które wymagają autoryzacji. Możliwa do zainstalowania wersja jest uruchamiana za zgodą użytkownika, który utworzył regułę, nawet jeśli inny użytkownik z uprawnieniami do edycji otworzy arkusz kalkulacyjny.

Istnieje kilka możliwych do zainstalowania aktywatorów dla Google Workspace aplikacji:

• Możliwa do zainstalowania reguła otwarcia jest uruchamiana, gdy użytkownik otwiera arkusz kalkulacyjny, dokument lub formularz, do którego ma uprawnienia do edycji.
• Możliwa do zainstalowania reguła edit (edytuj), która jest uruchamiana, gdy użytkownik modyfikuje wartość w arkuszu kalkulacyjnym.
• Możliwa do zainstalowania reguła change uruchamia się, gdy użytkownik modyfikuje strukturę arkusza kalkulacyjnego, np. poprzez dodanie nowego arkusza lub usunięcie kolumny.
• Możliwa do zainstalowania reguła przesłania formularza uruchamiana, gdy użytkownik odpowiada na formularz. Dostępne są 2 wersje reguły przesyłania formularza: jedna dla Formularzy Google i jedna dla Arkuszy, jeśli formularz przesyła arkusz kalkulacyjny.
• możliwy do zainstalowania aktywator wydarzenia w kalendarzu, który jest aktualizowany, tworzony, edytowany lub usuwany;

Reguł możliwych do zainstalowania możesz używać w skryptach niezależnych i powiązanych. Na przykład samodzielny skrypt może automatycznie tworzyć możliwą do zainstalowania regułę dla dowolnego pliku Arkuszy Google przez wywołanie metody TriggerBuilder.forSpreadsheet(key) i przekazanie identyfikatora arkusza kalkulacyjnego.

Ręczne zarządzanie aktywatorami

Aby ręcznie utworzyć aktywator, który można zainstalować, wykonaj te czynności w edytorze skryptów:

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 reguły, którą chcesz utworzyć.
5. Kliknij Zapisz.

Automatyczne zarządzanie aktywatorami

Możesz też tworzyć i usuwać aktywatory automatycznie za pomocą usługi skryptu. Zacznij od wywoływania ScriptApp.newTrigger(functionName), która zwraca TriggerBuilder.

Poniższy przykład pokazuje, jak utworzyć 2 reguły oparte na czasie: jedna uruchamia się co 6 godzin, a drugie uruchamia się w każdy poniedziałek o 9:00 (w strefie czasowej, w której masz ustawiony skrypt).

aktywatory/reguły.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();
}

Kolejny przykład pokazuje, jak utworzyć aktywator arkusza kalkulacyjnego, który można zainstalować. Pamiętaj, że w przeciwieństwie do prostej reguły onOpen() skrypt skryptu, który można zainstalować, nie musi być powiązany z arkuszem kalkulacyjnym. Aby utworzyć ten aktywator do wykorzystania w samodzielnym skrypcie, po prostu zastąp SpreadsheetApp.getActive() wywołaniem funkcji SpreadsheetApp.openById(id).

aktywatory/reguły.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 zmienić istniejący aktywator, który można zainstalować, musisz go usunąć i utworzyć nowy. Jeśli zapis aktywatora był wcześniej zapisany, możesz go usunąć, przekazując go jako argument do funkcji poniżej.

aktywatory/reguły.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

Jeśli reguła, którą można zainstalować, uruchamia się, ale funkcja powoduje wysłanie wyjątku lub w innym przypadku nie działa, nie zobaczysz komunikatu o błędzie na ekranie. W końcu po aktywowaniu reguły opartej na czasie lub aktywacji innego formularza przez innego użytkownika możesz nawet nie mieć dostępu do komputera.

Zamiast tego otrzymasz e-maila z Apps Script:

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 ponownego skonfigurowania aktywatora. Jeśli skrypt jest powiązany z plikiem Arkuszy, Dokumentów lub Formularzy Google, e-mail zawiera też link do pliku. Dzięki nim możesz dezaktywować aktywator lub edytować skrypt, aby naprawić błąd.

Uwaga: aktywatory utworzone przez dodatki nie wysyłają tych powiadomień e-mail.

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

1. Otwórz stronę script.google.com.
2. Po lewej stronie kliknij Moje reguły.

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

   Uwaga: na tej stronie nie można dezaktywować prostych reguł, takich jak onOpen(). Zamiast tego edytuj odpowiedni skrypt i usuń funkcję onOpen() lub zmień jej nazwę.

Reguły do zainstalowania w dodatkach

Więcej informacji o używaniu reguł możliwych do zainstalowania w dodatkach znajdziesz w artykule Wyzwalacze dodatków.