Podobnie jak w przypadku prostych aktywatorów, aktywatory instalacyjne pozwalają Apps Script uruchamiać funkcję automatycznie po wystąpieniu określonego zdarzenia, takiego jak otwarcie dokumentu. Aktywatory do zainstalowania są jednak bardziej elastyczne niż proste – mogą wywoływać usługi wymagające autoryzacji, a także kilka dodatkowych typów zdarzeń, m.in. reguły oparte na czasie (zegara). Można nimi sterować automatycznie. Zarówno w przypadku aktywatorów prostych, jak i możliwych do zainstalowania, Apps Script przekazuje aktywowanej funkcji obiekt zdarzenia zawierający informacje o kontekście, w którym wystąpiło zdarzenie.
Ograniczenia
Reguły do zainstalowania są bardziej elastyczne niż proste, ale nadal podlegają kilku ograniczeniom:
- Nie działają, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlania lub komentowania). W przypadku samodzielnych skryptów użytkownicy muszą mieć co najmniej uprawnienia do wyświetlania pliku skryptu, aby umożliwić prawidłowe działanie aktywatorów.
Wykonanie skryptów i żądania interfejsu API nie powodują uruchamiania aktywatorów. Na przykład wywołanie
FormResponse.submit()w celu przesłania nowej odpowiedzi z formularza nie powoduje uruchomienia reguły przesyłania formularza.Aktywatory do zainstalowania są zawsze uruchamiane na koncie osoby, która je utworzyła. Jeśli na przykład utworzysz instalowany aktywator otwarcia, będzie on uruchamiany, gdy Twój współpracownik otworzy dokument (jeśli Twój współpracownik ma uprawnienia do edycji), ale będzie uruchamiany na Twoim koncie. Oznacza to, że jeśli utworzysz regułę wysyłania e-maila po otwarciu dokumentu, będzie on zawsze wysyłany z Twojego konta, niekoniecznie z konta, za pomocą którego dokument został otwarty. Można jednak utworzyć dla każdego konta regułę możliwą do zainstalowania, co spowoduje wysłanie jednego e-maila z każdego konta.
Dane konto nie ma dostępu do reguł zainstalowanych z drugiego konta, chociaż może je aktywować na pierwszym koncie.
Te aktywatory podlegają limitom aktywatorów Apps Script.
Reguły działające na podstawie czasu
Aktywator zależny od czasu (nazywany też wyzwalaczem zegara) jest podobny do zadania cron w systemie Unix. Czynniki oparte na czasie pozwalają na wykonywanie skryptów o określonej godzinie lub cyklicznie – tak często, jak co minutę lub rzadziej niż raz w miesiącu. Pamiętaj, że dodatek może korzystać maksymalnie raz na godzinę z reguły zależnej od czasu. Czas może być nieco losowy. Jeśli na przykład utworzysz cykliczną regułę dotyczącą godziny 9:00, Apps Script wybiera godzinę między 9:00 a 10:00 i zachowuje tę samą godzinę z dnia na dzień, tak aby upływały 24 godziny przed ponownym uruchomieniem reguły.
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 = '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),
});
}
Reguły oparte na zdarzeniach
Zainstalowane aktywatory oparte na zdarzeniach są koncepcyjnie podobne do prostych aktywatorów, np. onOpen(), ale mogą reagować na dodatkowe zdarzenia i zachowują się inaczej.
Na przykład instalowany wyzwalacz otwarcia w Arkuszach Google aktywuje się za każdym razem, gdy użytkownik otworzy arkusz kalkulacyjny przez użytkownika z uprawnieniami do edycji, tak samo jak w przypadku prostej reguły onOpen(). Wersja do zainstalowania może jednak wywoływać usługi, które wymagają autoryzacji. Wersja do zainstalowania jest uruchamiana z autoryzacją użytkownika, który utworzył aktywator, nawet wtedy, gdy inny użytkownik z uprawnieniami do edycji otworzy arkusz kalkulacyjny.
Jest kilka aktywatorów do zainstalowania dla aplikacjiGoogle Workspace :
- Instalowany aktywator otwarcia jest uruchamiany, gdy użytkownik otworzy arkusz kalkulacyjny, dokument lub formularz, dla których ma uprawnienia do edycji.
- Zainstalowany aktywator edycji jest uruchamiany, gdy użytkownik zmienia wartość w arkuszu kalkulacyjnym.
- Zainstalowany aktywator zmiany jest uruchamiany, gdy użytkownik modyfikuje strukturę arkusza kalkulacyjnego, np. dodając nowy arkusz lub usuwając kolumnę.
- Zainstalowana reguła przesłania formularza uruchamia się, gdy użytkownik odpowiada na formularz. Istnieją 2 wersje reguły przesyłania formularza: jedna dla Formularzy Google i jedna dla Arkuszy, jeśli formularz jest przesyłany do arkusza kalkulacyjnego.
- Instalowany aktywator wydarzenia w kalendarzu jest uruchamiany, gdy wydarzenia w kalendarzu użytkownika zostaną zaktualizowane – utworzone, edytowane lub usunięte.
Tych aktywatorów można używać w skryptach samodzielnych i powiązanych. Na przykład samodzielny skrypt może automatycznie utworzyć możliwy do zainstalowania aktywator dla dowolnego pliku Arkuszy Google. W tym celu wywołaj metodę TriggerBuilder.forSpreadsheet(key) i przekażesz 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:
- Otwórz projekt Apps Script.
- Po lewej stronie kliknij Reguły .
- W prawym dolnym rogu kliknij Dodaj regułę.
- Wybierz i skonfiguruj typ aktywatora, który chcesz utworzyć.
- Kliknij Zapisz.
Automatyczne zarządzanie aktywatorami
Aktywatory możesz też tworzyć i usuwać automatycznie za pomocą usługi skryptu. Zacznij od wywołania ScriptApp.newTrigger(functionName), które zwraca wartość TriggerBuilder.
Z przykładu poniżej dowiesz się, jak utworzyć 2 reguły zależne od czasu: jeden uruchamiany co 6 godzin, a drugi w każdy poniedziałek o 9:00 rano (w strefie czasowej ustawionej dla Twojego skryptu).
Następny przykład pokazuje, jak utworzyć możliwy do zainstalowania aktywator otwarty dla arkusza kalkulacyjnego. Pamiętaj, że w przeciwieństwie do prostego wyzwalacza onOpen() skrypt nie musi być powiązany z arkuszem kalkulacyjnym. Aby utworzyć ten aktywator na podstawie samodzielnego skryptu, po prostu zastąp SpreadsheetApp.getActive() wywołaniem do SpreadsheetApp.openById(id).
Aby programowo zmodyfikować istniejący aktywator z możliwością zainstalowania, musisz go usunąć i utworzyć nowy. Jeśli identyfikator aktywatora był wcześniej zapisany, możesz go usunąć, przekazując go jako argument do funkcji poniżej.
Błędy w aktywatorach
Gdy uruchamia się aktywator możliwy do zainstalowania, ale funkcja zgłosi wyjątek lub w przeciwnym razie nie zadziała, na ekranie nie pojawi się komunikat o błędzie. W końcu, gdy uruchomi się reguła zależna od czasu lub inny użytkownik aktywuje regułę przesyłania formularza, możesz nie być nawet przy komputerze.
Zamiast tego Apps Script wysyła e-maile podobne 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 umożliwiający zdezaktywowanie lub zmianę 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 aktywatora lub edytowanie skryptu w celu naprawienia błędu.
Aby sprawdzić wszystkie reguły powiązane z Twoim kontem Google i dezaktywować te, których już nie potrzebujesz, wykonaj te czynności:
- Wejdź na stronę
script.google.com. - Po lewej stronie kliknij Moje reguły.
Aby usunąć regułę, po jej prawej stronie kliknij Więcej > Usuń regułę.
Aktywatory do zainstalowania w dodatkach
Więcej informacji o używaniu w dodatkach aktywatorów do zainstalowania znajdziesz w artykule Reguły dodatków.