Wie bei einfachen Triggern können installierbare Trigger dafür sorgen, dass Apps Script eine Funktion automatisch ausführt, wenn ein bestimmtes Ereignis auftritt, z. B. das Öffnen eines Dokuments. Installierbare Trigger bieten jedoch mehr Flexibilität als einfache Trigger: Sie können Dienste aufrufen, die eine Autorisierung erfordern. Sie bieten mehrere zusätzliche Ereignistypen, darunter zeitgesteuerte Trigger (Uhr), die programmatisch gesteuert werden können. Sowohl für einfache als auch installierbare Trigger übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen über den Kontext enthält, in dem das Ereignis aufgetreten ist.
Einschränkungen
Obwohl installierbare Trigger mehr Flexibilität bieten als einfache Trigger, unterliegen sie einigen Einschränkungen:
- Sie werden nicht ausgeführt, wenn eine Datei im Lese- oder Kommentarmodus geöffnet wird. Bei eigenständigen Skripts benötigen Nutzer mindestens Lesezugriff auf die Skriptdatei, damit Trigger ordnungsgemäß ausgeführt werden.
Skriptausführungen und API-Anfragen führen nicht zum Ausführen von Triggern. Beispielsweise führt ein Aufruf von
FormResponse.submit()zum Senden einer neuen Formularantwort nicht dazu, dass der Sendetrigger des Formulars ausgeführt wird.Installierbare Trigger werden immer unter dem Konto der Person ausgeführt, die sie erstellt hat. Wenn Sie beispielsweise einen installierbaren offenen Trigger erstellen, wird dieser ausgeführt, wenn Ihr Kollege das Dokument öffnet (sofern er Bearbeitungszugriff hat), aber er wird als Ihr Konto ausgeführt. Wenn Sie also einen Trigger erstellen, um beim Öffnen eines Dokuments eine E-Mail zu senden, wird die E-Mail immer von Ihrem Konto gesendet, nicht von dem Konto, über das das Dokument geöffnet wurde. Sie können jedoch für jedes Konto einen installierbaren Trigger erstellen, wodurch von jedem Konto eine E-Mail gesendet wird.
Ein Konto kann keine Trigger sehen, die von einem zweiten Konto installiert wurden, auch wenn das erste Konto diese Trigger noch aktivieren kann.
Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.
Zeitgesteuerte Trigger
Ein zeitgesteuerter Trigger (auch als Uhrtrigger bezeichnet) ähnelt einem Cronjob in Unix. Zeitgesteuerte Trigger lassen zu, dass Skripts zu einer bestimmten Zeit oder in einem wiederkehrenden Intervall ausgeführt werden, d. h. jede Minute oder so selten wie einmal pro Monat. Ein Add-on kann höchstens einmal pro Stunde einen zeitgesteuerten Trigger verwenden. Die Zeit kann leicht zufällig sein. Wenn Sie beispielsweise einen wiederkehrenden Trigger für 9:00 Uhr erstellen, wählt Apps Script eine Zeit zwischen 9:00 und 10:00 Uhr aus und sorgt dann dafür, dass dieser Zeitpunkt von Tag zu Tag konsistent ist, sodass 24 Stunden vergehen, bevor der Trigger wieder ausgelöst wird.
Das folgende Beispiel zeigt eine Google Chat-App, die jede Minute eine Nachricht in jedem Bereich postet, in dem sich die App befindet:
// 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),
});
}
Ereignisgesteuerte Trigger
Installierbare ereignisgesteuerte Trigger ähneln einfachen Triggern wie onOpen(), können jedoch auf zusätzliche Ereignisse reagieren und verhalten sich anders.
Der installierbare Trigger zum Öffnen für Google Tabellen wird beispielsweise immer dann aktiviert, wenn die Tabelle von einem Nutzer mit Bearbeitungszugriff geöffnet wird, genau wie der einfache onOpen()-Trigger. Mit der installierbaren Version können jedoch Dienste aufgerufen werden, die eine Autorisierung erfordern. Die installierbare Version wird mit der Autorisierung des Nutzers ausgeführt, der den Trigger erstellt hat, auch wenn ein anderer Nutzer mit Bearbeitungszugriff die Tabelle öffnet.
Es gibt mehrere installierbare Trigger fürGoogle Workspace -Anwendungen:
- Ein installierbarer Open-Trigger wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument oder ein Formular öffnet, für das er Bearbeitungsberechtigungen hat.
- Wenn ein Nutzer einen Wert in einer Tabelle ändert, wird ein installierbarer edit-Trigger ausgeführt.
- Ein installierbarer Änderungstrigger wird ausgeführt, wenn ein Nutzer die Struktur einer Tabelle ändert, z. B. durch Hinzufügen eines neuen Tabellenblatts oder Entfernen einer Spalte.
- Ein installierbarer Trigger zum Senden von Formularen wird ausgeführt, wenn ein Nutzer auf ein Formular antwortet. Es gibt zwei Versionen des Triggers zum Senden von Formularen: eine für Google Formulare und eine für Google Tabellen, wenn das Formular an eine Tabelle gesendet wird.
- Ein installierbarer Kalendertermin-Trigger wird ausgeführt, wenn die Kalendertermine eines Nutzers aktualisiert, also erstellt, bearbeitet oder gelöscht werden.
Installierbare Trigger können in eigenständigen und gebundenen Skripts verwendet werden. Mit einem eigenständigen Skript kann beispielsweise programmatisch ein installierbarer Trigger für eine beliebige Google Tabellen-Datei erstellt werden. Dazu wird TriggerBuilder.forSpreadsheet(key) aufgerufen und die ID der Tabelle übergeben.
Trigger manuell verwalten
So erstellen Sie manuell einen installierbaren Trigger im Skripteditor:
- Öffnen Sie Ihr Apps Script-Projekt.
- Klicken Sie links auf Trigger .
- Klicken Sie rechts unten auf Trigger hinzufügen.
- Wählen Sie den Triggertyp aus, den Sie erstellen möchten, und konfigurieren Sie ihn.
- Klicke auf Speichern.
Trigger programmatisch verwalten
Mit dem Script-Dienst können Sie Trigger auch programmatisch erstellen und löschen. Rufen Sie zuerst ScriptApp.newTrigger(functionName) auf, das ein TriggerBuilder-Objekt zurückgibt.
Im folgenden Beispiel wird gezeigt, wie Sie zwei zeitgesteuerte Trigger erstellen – einen, der alle sechs Stunden und einen jeden Montag um 9:00 Uhr (in der für Ihr Skript eingestellten Zeitzone) ausgelöst wird.
Im nächsten Beispiel wird gezeigt, wie Sie einen installierbaren offenen Trigger für eine Tabelle erstellen. Im Gegensatz zu einem einfachen onOpen()-Trigger muss das Skript für den installierbaren Trigger nicht an die Tabelle gebunden sein. Wenn Sie diesen Trigger aus einem eigenständigen Skript erstellen möchten, ersetzen Sie einfach SpreadsheetApp.getActive() durch einen Aufruf von SpreadsheetApp.openById(id).
Wenn Sie einen vorhandenen installierbaren Trigger programmatisch ändern möchten, müssen Sie ihn löschen und einen neuen erstellen. Wenn Sie die ID eines Triggers bereits gespeichert haben, können Sie sie löschen, indem Sie die ID als Argument an die Funktion unten übergeben.
Fehler in Triggern
Wenn ein installierbarer Trigger ausgelöst wird, die Funktion jedoch eine Ausnahme auslöst oder aus anderen Gründen nicht erfolgreich ausgeführt wird, wird keine Fehlermeldung auf dem Bildschirm angezeigt. Denn wenn ein zeitgesteuerter Trigger ausgeführt wird oder ein anderer Nutzer Ihren Trigger zum Senden eines Formulars aktiviert, befinden Sie sich möglicherweise gar nicht an Ihrem Computer.
Stattdessen erhalten Sie von Apps Script eine E-Mail wie die folgende:
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.
Die E-Mail enthält einen Link, über den Sie den Trigger deaktivieren oder neu konfigurieren können. Wenn das Skript an eine Google Tabellen-, Google Docs- oder Google Formulare-Datei gebunden ist, enthält die E-Mail auch einen Link zu dieser Datei. Über diese Links können Sie den Trigger deaktivieren oder das Skript bearbeiten, um den Fehler zu beheben.
So überprüfen Sie alle Trigger, die Ihrem Google-Konto zugeordnet sind, und deaktivieren die nicht mehr benötigten Trigger:
- Rufen Sie
script.google.comauf. - Klicken Sie links auf My Triggers (Meine Trigger).
Klicken Sie zum Löschen eines Triggers rechts daneben auf das Dreipunkt-Menü > Trigger löschen.
Trigger in Add-ons
Neben installierbaren Triggern können Sie Manifest-Trigger in Add-ons verwenden. Weitere Informationen finden Sie unter Trigger für Google Workspace-Add-ons.