Installierbare Trigger

Wie bei einfachen Triggern kann Apps Script eine Funktion automatisch ausführen, wenn ein bestimmtes Ereignis eintritt, z. B. beim Ö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, verschiedene zusätzliche Ereignistypen einschließlich zeitgesteuerter Trigger (Uhren) aufrufen und programmatisch gesteuert werden. Sowohl bei einfachen als auch bei installierbaren Triggern übergibt Google Apps Script an die ausgelöste Funktion ein Ereignisobjekt, das Informationen zum Kontext enthält, in dem das Ereignis aufgetreten ist.

Einschränkungen

Obwohl installierbare Trigger mehr Flexibilität bieten als einfache Trigger, unterliegen sie dennoch 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 richtig ausgeführt werden.
  • Skriptausführungen und API-Anfragen lösen keine Trigger aus. Wenn Sie beispielsweise FormResponse.submit() aufrufen, um eine neue Formularantwort zu senden, wird der Übermittlungstrigger des Formulars nicht ausgeführt.

  • Installierbare Trigger werden immer unter dem Konto der Person ausgeführt, die sie erstellt hat. Wenn Sie beispielsweise einen installierbaren offenen Trigger erstellen, wird er ausgeführt, wenn Ihr Kollege das Dokument öffnet (sofern Ihr Kollege Bearbeitungszugriff hat), aber er wird als Ihr Konto ausgeführt. Wenn Sie einen Trigger zum Senden einer E-Mail beim Öffnen eines Dokuments erstellen, wird die E-Mail also immer von Ihrem Konto gesendet, nicht notwendigerweise von dem Konto, mit dem das Dokument geöffnet wurde. Sie könnten jedoch einen installierbaren Trigger für jedes Konto erstellen, was zu einer E-Mail pro Konto führt.

  • Trigger, die über ein zweites Konto installiert sind, können nicht in einem Konto aufgerufen werden.

  • Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.

Zeitgesteuerte Trigger

Ein zeitgesteuerter Trigger (auch Uhr-Trigger genannt) ähnelt einem Cronjob in Unix. Mit zeitgesteuerten Triggern können Skripts zu einer bestimmten Zeit oder in regelmäßigen Abständen ausgeführt werden. Die Ausführung kann jede Minute oder nur einmal pro Monat erfolgen. Beachten Sie, dass ein Add-on einen zeitgesteuerten Trigger maximal einmal pro Stunde verwenden kann. Die Zeit kann leicht zufällig sein. Wenn Sie zum Beispiel einen wiederkehrenden Trigger für 9:00 Uhr erstellen, wählt Apps Script eine Zeit zwischen 9:00 und 10:00 Uhr, dann wird dieses Timing von Tag zu Tag beibehalten, sodass 24 Stunden vergangen sind, bevor der Trigger wieder ausgelöst wird.

Ereignisgesteuerte Trigger

Installierbare ereignisgesteuerte Trigger funktionieren ähnlich wie einfache Trigger wie onOpen(), können jedoch auf zusätzliche Ereignisse reagieren und sich anders verhalten.

So wird beispielsweise der installierbare offene Trigger für Google Tabellen immer aktiviert, wenn die Tabelle von einem Nutzer geöffnet wird, der Bearbeitungszugriff hat – genau wie beim einfachen onOpen()-Trigger. Die installierbare Version kann jedoch Dienste aufrufen, 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ür Google Workspace Anwendungen:

  • Ein installierbarer open-Trigger wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument oder ein Formular öffnet, für die er Bearbeitungszugriff hat.
  • Ein installierbarer edit-Trigger wird ausgeführt, wenn ein Nutzer einen Wert in einer Tabelle ändert.
  • Ein installierbarer change-Trigger wird ausgeführt, wenn ein Nutzer die Struktur einer Tabelle selbst ändert, indem er beispielsweise ein neues Tabellenblatt hinzufügt oder eine Spalte entfernt.
  • Ein installierbarer Formular senden-Trigger wird ausgeführt, wenn ein Nutzer auf ein Formular antwortet. Es gibt zwei Versionen des Triggers für die Formularübermittlung: eine für Google Formulare selbst und 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, erstellt, bearbeitet oder gelöscht werden.

Sie können installierbare Trigger in eigenständigen und gebundenen Skripts verwenden. Mit einem eigenständigen Skript lässt sich beispielsweise programmatisch ein installierbarer Trigger für eine beliebige Google Tabellen-Datei erstellen. Dazu wird TriggerBuilder.forSpreadsheet(key) aufgerufen und die ID der Tabelle übergeben.

Trigger manuell verwalten

So erstellen Sie manuell einen installierbaren Trigger im Skripteditor:

  1. Öffnen Sie Ihr Apps Script-Projekt.
  2. Klicken Sie links auf Trigger .
  3. Klicken Sie rechts unten auf Trigger hinzufügen.
  4. Wählen Sie den Triggertyp aus, den Sie erstellen möchten, und konfigurieren Sie ihn.
  5. Klicken Sie auf Speichern.

Trigger programmatisch verwalten

Sie können Trigger auch programmatisch mit dem Skriptdienst erstellen und löschen. Rufen Sie zuerst ScriptApp.newTrigger(functionName) auf. Dadurch wird ein TriggerBuilder zurückgegeben.

Das folgende Beispiel zeigt, wie Sie zwei zeitgesteuerte Trigger erstellen – einen, der alle sechs Stunden ausgelöst wird, und einen, der jeden Montag um 9:00 Uhr ausgelöst wird (in der Zeitzone, auf die das Skript eingestellt ist).

Auslöser/Auslöser.gs
/**
 * 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();
}

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).

Auslöser/Auslöser.gs
/**
 * 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();
}

Wenn Sie einen vorhandenen installierbaren Trigger programmatisch ändern möchten, müssen Sie ihn löschen und einen neuen Trigger erstellen. Wenn Sie die ID eines Triggers bereits gespeichert haben, können Sie ihn löschen, indem Sie die ID als Argument an die Funktion unten übergeben.

Auslöser/Auslöser.gs
/**
 * 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;
    }
  }
}

Fehler in Triggern

Wenn ein installierbarer Trigger ausgelöst wird, aber die Funktion eine Ausnahme auslöst oder andernfalls nicht erfolgreich ausgeführt wird, wird keine Fehlermeldung angezeigt. Denn wenn ein zeitgesteuerter Trigger ausgeführt wird oder ein anderer Nutzer Ihren Formularübermittlungs-Trigger aktiviert, befinden Sie sich möglicherweise nicht einmal auf Ihrem Computer.

Stattdessen erhalten Sie von Apps Script eine E-Mail ähnlich der folgenden:

From: 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, mit dem Sie den Trigger deaktivieren oder neu konfigurieren können. Wenn das Skript an eine Datei in Google Tabellen, Google Docs oder Google Formulare 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 prüfen Sie alle Trigger, die mit Ihrem Google-Konto verknüpft sind, und deaktivieren die Trigger, die Sie nicht mehr benötigen:

  1. Gehen Sie zu script.google.com.
  2. Klicken Sie links auf Meine Trigger.
  3. Klicken Sie zum Löschen eines Triggers rechts neben dem Trigger auf das Dreipunkt-Menü > Trigger löschen.

Installierbare Trigger in Add-ons

Weitere Informationen zur Verwendung installierbarer Trigger in Add-ons finden Sie unter Add-on-Trigger.