Installierbare Trigger

Wie einfache Trigger ermöglichen installierbare Trigger, dass Apps Script eine Funktion automatisch ausführt, wenn ein bestimmtes Ereignis eintritt, z. B. wenn ein Dokument geöffnet wird. Installierbare Trigger bieten jedoch mehr Flexibilität als einfache Trigger: Sie können Dienste aufrufen, für die eine Autorisierung erforderlich ist, sie bieten mehrere zusätzliche Ereignistypen, einschließlich zeitgesteuerter (Uhr-)Trigger, und sie können programmatisch gesteuert werden. Sowohl für einfache als auch für installierbare Trigger übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen zum Kontext enthält, in dem das Ereignis aufgetreten ist.

Einschränkungen

Installierbare Trigger bieten zwar mehr Flexibilität als einfache Trigger, unterliegen aber dennoch einigen Einschränkungen:

  • Sie werden nicht ausgeführt, wenn eine Datei im Lesemodus (Ansehen oder Kommentieren) geöffnet wird. Bei eigenständigen Skripts benötigen Nutzer mindestens Lesezugriff auf die Skriptdatei, damit Trigger ordnungsgemäß ausgeführt werden.

  • Script-Ausführungen und API-Anfragen führen nicht dazu, dass Trigger ausgeführt werden. Wenn Sie beispielsweise FormResponse.submit() aufrufen, um eine neue Antwort auf ein Formular zu senden, wird der Submit-Trigger 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 er Bearbeitungszugriff hat). Die Ausführung erfolgt jedoch über Ihr Konto. 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önnten jedoch für jedes Konto einen installierbaren Trigger erstellen. In diesem Fall würde aus jedem Konto eine E-Mail gesendet.

  • In einem Konto sind keine Trigger zu sehen, die über ein zweites Konto installiert wurden. Das erste Konto kann diese Trigger jedoch weiterhin aktivieren.

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

Zeitgesteuerte Trigger

Ein zeitgesteuerter Trigger (auch als Uhrzeittrigger bezeichnet) ähnelt einem Cronjob in Unix. Mit zeitgesteuerten Triggern können Skripts zu einem bestimmten Zeitpunkt oder in einem wiederkehrenden Intervall ausgeführt werden, so häufig wie jede Minute oder so selten wie einmal pro Monat. Ein Add-on kann einen zeitgesteuerten Trigger höchstens einmal pro Stunde verwenden. Die Uhrzeit kann leicht variieren. Wenn Sie beispielsweise einen wiederkehrenden Trigger für 9:00 Uhr erstellen, wählt Apps Script eine Uhrzeit zwischen 9:00 und 10:00 Uhr aus und behält diese Uhrzeit von Tag zu Tag bei, sodass 24 Stunden vergehen, bevor der Trigger wieder ausgelöst wird.

Ereignisgesteuerte Trigger

Installierbare ereignisgesteuerte Trigger ähneln konzeptionell einfachen Triggern wie onOpen(), können aber auf zusätzliche Ereignisse reagieren und verhalten sich anders.

Der installierbare offene Trigger 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. Die installierbare Version kann jedoch Dienste aufrufen, für die eine Autorisierung erforderlich ist. 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, das er bearbeiten darf.
  • Ein installierbarer edit-Trigger wird ausgeführt, wenn ein Nutzer einen Wert in einer Tabelle ändert.
  • Ein installierbarer Änderungs-Trigger wird ausgelöst, wenn ein Nutzer die Struktur einer Tabelle ändert, z. B. indem er 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 „Formular senden“: eine für Google Formulare selbst 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 werden – also erstellt, bearbeitet oder gelöscht werden.

Sie können installierbare Trigger in eigenständigen und gebundenen Skripts verwenden. Beispielsweise kann ein eigenständiges Skript 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 einen installierbaren Trigger manuell im Scripteditor:

  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 gewünschten Triggertyp aus und konfigurieren Sie ihn.
  5. Klicken Sie auf Speichern.

Trigger programmatisch verwalten

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

Im folgenden Beispiel wird gezeigt, wie Sie zwei zeitgesteuerte Trigger erstellen – einen, der alle 6 Stunden ausgelöst wird, und einen, der jeden Montag um 9:00 Uhr (in der Zeitzone, die für Ihr Skript festgelegt ist) ausgelöst wird.

triggers/triggers.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 ein installierbarer Open-Trigger für eine Tabelle erstellt wird. 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 über ein eigenständiges Skript erstellen möchten, ersetzen Sie SpreadsheetApp.getActive() einfach durch einen Aufruf von SpreadsheetApp.openById(id).

triggers/triggers.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 erstellen. Wenn Sie die ID eines Triggers zuvor gespeichert haben, können Sie sie löschen, indem Sie die ID als Argument an die Funktion unten übergeben.

triggers/triggers.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;
    }
  }
}

Bevor Sie einen Trigger erstellen, sollten Sie prüfen, ob die zugehörige Funktion alle erforderlichen OAuth-Berechtigungen hat.

Fehler in Triggern

Wenn ein installierbarer Trigger ausgelöst wird, die Funktion aber eine Ausnahme auslöst oder aus anderen Gründen 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 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 zum Deaktivieren oder Neukonfigurieren des Triggers. 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 rufen Sie alle mit Ihrem Google-Konto verknüpften Trigger auf und deaktivieren die Trigger, die Sie nicht mehr benötigen:

  1. Rufen Sie script.google.com auf.
  2. Klicken Sie links auf Meine Trigger.

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

Zusätzlich zu installierbaren Triggern können Sie in Add-ons auch Manifest-Trigger verwenden. Weitere Informationen finden Sie unter Trigger für Google Workspace-Add-ons.