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, für die eine Autorisierung erforderlich ist, bieten mehrere zusätzliche Ereignistypen, einschließlich zeitgesteuerter (Uhr-)Trigger, und können programmatisch gesteuert werden. Sowohl bei einfachen als auch bei installierbaren Auslösern übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen zum Kontext enthält, in dem das Ereignis aufgetreten ist.
Einschränkungen
Auch wenn installierbare Trigger mehr Flexibilität bieten als einfache Trigger, gelten für sie dennoch einige Einschränkungen:
- Sie werden nicht ausgeführt, wenn eine Datei im Lesemodus (Anzeigen oder Kommentieren) geöffnet wird. Bei eigenständigen Scripts benötigen Nutzer mindestens Lesezugriff auf die Scriptdatei, damit Trigger ordnungsgemäß ausgeführt werden können.
Auslöser werden nicht durch Scriptausführungen und API-Anfragen ausgeführt. 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 Trigger für das Öffnen erstellen, wird er ausgeführt, wenn Ihr Kollege das Dokument öffnet (sofern er Bearbeitungszugriff hat). Er wird jedoch unter Ihrem Konto ausgeführt. Wenn Sie also einen Trigger erstellen, um eine E-Mail zu senden, wenn ein Dokument geöffnet wird, wird die E-Mail immer von Ihrem Konto gesendet, nicht unbedingt von dem Konto, mit dem das Dokument geöffnet wurde. Sie können jedoch einen installierbaren Trigger für jedes Konto erstellen, wodurch eine E-Mail von jedem Konto gesendet wird.
In einem bestimmten Konto sind keine Trigger zu sehen, die in einem zweiten Konto installiert wurden, auch wenn diese Trigger im ersten Konto weiterhin aktiviert werden können.
Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.
Zeitgesteuerte Trigger
Ein zeitgesteuerter Trigger (auch als Uhren-Trigger bezeichnet) ähnelt einem Cronjob unter Unix. Mit zeitbasierten Triggern können Scripts zu einer bestimmten Zeit oder in einem wiederkehrenden Intervall ausgeführt werden, z. B. jede Minute oder 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.
Im folgenden Beispiel wird eine Google Chat-App verwendet, die jede Minute eine Nachricht in allen Gruppenbereichen postet, in denen 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.
- Ein installierbarer Bearbeitungs-Trigger wird ausgeführt, wenn ein Nutzer einen Wert in einer Tabelle ändert.
- Ein installierbarer Änderungs-Trigger wird ausgeführt, wenn ein Nutzer die Struktur einer Tabelle selbst ä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 „Senden des Formulars“: eine für Google Formulare selbst und eine für Google Tabellen, wenn das Formular in eine Tabelle gesendet wird.
- Ein installierbarer Trigger für Kalendertermine wird ausgeführt, wenn die Kalendertermine eines Nutzers aktualisiert werden, also erstellt, bearbeitet oder gelöscht werden.
Installierbare Trigger können in eigenständigen und gebundenen Skripts verwendet werden. Beispielsweise kann ein eigenständiges Script programmatisch einen installierbaren Trigger für eine beliebige Google Tabellen-Datei erstellen, indem TriggerBuilder.forSpreadsheet(key) aufgerufen und die ID der Tabelle übergeben wird.
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.
- Klicken Sie 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 ausgelöst wird, und einen, der jeden Montag um 9:00 Uhr (in der Zeitzone, in der Ihr Script festgelegt ist) ausgelöst wird.
Im nächsten Beispiel wird gezeigt, wie Sie einen installierbaren offenen Trigger für eine Tabelle erstellen. Anders als bei einem einfachen onOpen()-Trigger muss das Script für den installierbaren Trigger nicht an die Tabelle gebunden sein. Wenn Sie diesen Trigger aus einem eigenständigen Script 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 zuvor gespeichert haben, können Sie sie löschen, indem Sie die ID als Argument an die folgende Funktion übergeben.
Fehler in Triggern
Wenn ein installierbarer Trigger ausgelöst wird, die Funktion aber eine Ausnahme auslöst oder anderweitig nicht erfolgreich ausgeführt wird, wird keine Fehlermeldung auf dem Bildschirm angezeigt. Wenn ein zeitgesteuerter Trigger ausgeführt wird oder ein anderer Nutzer Ihren Trigger für das Senden von Formularen aktiviert, sind Sie möglicherweise nicht einmal an Ihrem Computer.
Stattdessen erhalten Sie von Apps Script eine E-Mail wie diese:
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 Script mit einer Google Tabellen-, Docs- oder Formulare-Datei verknüpft ist, enthält die E-Mail auch einen Link zu dieser Datei. Über diese Links können Sie den Trigger deaktivieren oder das Script bearbeiten, um den Fehler zu beheben.
Gehen Sie wie folgt vor, um alle mit Ihrem Google-Konto verknüpften Trigger zu überprüfen und die nicht mehr benötigten Trigger zu deaktivieren:
- Rufen Sie
script.google.comauf. - Klicken Sie links auf Meine Trigger.
Wenn Sie einen Trigger löschen möchten, klicken Sie rechts neben dem Trigger auf das Dreipunkt-Menü > Trigger löschen.
Trigger in Add-ons
Neben installierbaren Triggern können Sie in Add-ons auch Manifesttrigger verwenden. Weitere Informationen finden Sie unter Trigger für Google Workspace-Add-ons.