Podobnie jak proste reguły, reguły instalowane umożliwiają skryptom Apps automatyczne wykonywanie funkcji 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 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
Mimo że aktywatory możliwe do zainstalowania zapewniają większą elastyczność niż proste reguły, nadal podlegają 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 działał, 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. 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ć.
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 w Google Arkusze wyzwalacz otwierania aktywuje się, gdy arkusz kalkulacyjny 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 zmodyfikuje 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ę.
- Możliwa do zainstalowania reguła przesłania formularza uruchamia się, 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).
Możesz używać aktywatorów możliwych do zainstalowania 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:
- Otwórz projekt Apps Script.
- Po lewej stronie kliknij Reguły .
- W prawym dolnym rogu kliknij Dodaj wyzwalacz.
- Wybierz i skonfiguruj typ reguły, którą chcesz utworzyć.
- 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 funkcji ScriptApp.newTrigger(functionName), która zwraca wartość TriggerBuilder.
Z przykładu poniżej dowiesz się, 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).
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 parametr SpreadsheetApp.getActive() wywołaniem funkcji SpreadsheetApp.openById(id).
Aby zmodyfikować istniejący instalowalny wyzwalacz za pomocą kodu, 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.
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 wyśle Ci 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:
- Wejdź na stronę
script.google.com. - Po lewej stronie kliknij Moje reguły.
Aby usunąć aktywator, po jego prawej stronie kliknij Więcej > Usuń aktywator.
Reguły 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 Google Workspace.