Installierbare Trigger

Wie einfache Trigger ermöglichen auch installierbare Trigger, dass Google Apps Script automatisch eine Funktion ausführt, wenn ein bestimmtes Ereignis eintritt, z. B. wenn ein Dokument geöffnet wird. Installierbare Trigger sind jedoch flexibler als einfache Trigger: Sie können Dienste aufrufen, für die eine Autorisierung erforderlich ist, bieten mehrere zusätzliche Ereignistypen, einschließlich zeitgesteuerter Trigger, und können programmgesteuert 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.

Weitere Informationen zur Verwendung von Triggern in Add-ons finden Sie unter Trigger für Google Workspace-Add-ons.

Einschränkungen

Obwohl installierbare Trigger flexibler als einfache Trigger sind, unterliegen sie mehreren Einschränkungen:

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

  • Skriptausführungen und API-Anfragen lösen keine Trigger aus. Wenn Sie beispielsweise aufrufen, FormResponse.submit() um eine neue Formularantwort zu senden, wird der Sende-Trigger des Formulars nicht ausgeführt.

    Eine Ausnahme von dieser Einschränkung ist Form.submitGrades(). Wenn Ihr Code einen onFormSubmit-Trigger verwendet, löst der Aufruf von Form.submitGrades() die onFormSubmit-Bedingung aus und verursacht eine Endlosschleife. Um die Endlosschleife zu verhindern, fügen Sie Code hinzu, der prüft, ob bereits Noten vorhanden sind, bevor Sie submitGrades() aufrufen.

  • Installierbare Trigger werden immer unter dem Konto der Person ausgeführt, die sie erstellt hat. Wenn Sie beispielsweise einen installierbaren Öffnungs-Trigger erstellen, wird er 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 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 für jedes Konto einen installierbaren Trigger erstellen, sodass eine E-Mail von jedem Konto gesendet wird.

  • Trigger, die von einem zweiten Konto installiert wurden, sind für ein bestimmtes Konto nicht sichtbar, obwohl das erste Konto diese Trigger weiterhin aktivieren kann.

  • Für installierbare Trigger gelten die Kontingentlimits für Apps Script-Trigger quota limits.

Zeitgesteuerte Trigger

Ein zeitgesteuerter Trigger (auch als Uhr-Trigger bezeichnet) ähnelt einem Cronjob in Unix. Mit zeitgesteuerten Triggern können Skripts zu einem bestimmten Zeitpunkt 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 Uhr und 10:00 Uhr aus und behält diese Zeit 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 Öffnungs-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ür Google Workspace-Anwendungen:

  • Ein installierbarer Öffnungs-Trigger wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument oder ein Formular öffnet, das er bearbeiten darf.
  • 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 ändert, z. B. ein neues Tabellenblatt hinzufügt oder eine Spalte entfernt.
  • Ein installierbarer Formular-Sende-Trigger wird ausgeführt, wenn ein Nutzer auf ein Formular antwortet. Es gibt zwei Versionen des Formular-Sende-Triggers: eine für Google Formulare selbst und eine für Google Tabellen, wenn das Formular an eine Tabelle gesendet wird.
  • Ein installierbarer Kalenderereignis-Trigger wird ausgeführt, wenn die Kalenderereignisse eines Nutzers aktualisiert werden, z. B. erstellt, bearbeitet oder gelöscht werden.

Installierbare Trigger sind in eigenständigen und gebundenen Skripts verfügbar. Ein eigenständiges Skript kann beispielsweise programmgesteuert einen installierbaren Trigger für eine beliebige Google Tabellen-Datei erstellen, indem es TriggerBuilder.forSpreadsheet(key) aufruft und die ID der Tabelle übergibt.

Trigger manuell verwalten

So erstellen Sie manuell einen installierbaren Trigger im Script-Editor:

  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 programmgesteuert verwalten

Mit dem Script-Dienst können Sie Trigger programmgesteuert erstellen und löschen. Rufen Sie zuerst ScriptApp.newTrigger(functionName)auf, das einen TriggerBuilderzurückgibt.

Das folgende Beispiel zeigt, 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();
}

Das nächste Beispiel zeigt, wie Sie einen installierbaren Öffnungs-Trigger für eine Tabelle erstellen. Anders als bei 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 SpreadsheetApp.getActive() 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 programmgesteuert ändern möchten, müssen Sie ihn löschen und einen neuen erstellen. Wenn Sie die ID eines Triggers zuvor gespeichert haben, löschen Sie ihn, indem Sie die ID als Argument an die folgende Funktion ü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;
    }
  }
}

Prüfen Sie vor dem Erstellen eines Triggers, ob die zugehörige Funktion alle die erforderlichen OAuth-Berechtigungen hat.

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 auf dem Bildschirm keine Fehlermeldung angezeigt. Wenn ein zeitgesteuerter Trigger ausgeführt wird oder ein anderer Nutzer Ihren Formular-Sende-Trigger aktiviert, sind Sie möglicherweise nicht einmal an Ihrem Computer.

Stattdessen sendet Apps Script eine E-Mail wie die folgende:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for 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.

Wenn Sie Fehler in Ihrem Skript beheben möchten, klicken Sie auf den Link in der Benachrichtigungs-E-Mail, um Ihr Skriptprojekt zu öffnen. Nachdem das Projekt geöffnet wurde, rufen Sie die Ausführungslogs auf, indem Sie in der linken Navigationsbereich auf Ausführungen klicken. In den Logs wird angezeigt, welche Ausführungen fehlgeschlagen sind, und es werden Fehlermeldungen angezeigt, die Ihnen bei der Diagnose und Behebung des Problems helfen.

Bei installierbaren Triggern, die von Add-ons erstellt wurden, werden diese E-Mail-Benachrichtigungen nicht an Nutzer gesendet.

So rufen Sie alle Trigger auf, die mit Ihrem Google-Konto verknüpft sind, 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.

Wenn ein Trigger deaktiviert wird, werden auch die entsprechenden Fehlermeldungen deaktiviert. Fehlermeldungen sind ein fester Bestandteil eines aktiven Triggers. Wenn Sie also keine Fehlermeldungen mehr für einen bestimmten Trigger erhalten möchten, deaktivieren oder löschen Sie den Trigger selbst. Solange ein Trigger aktiv ist, können Sie nur die Häufigkeit dieser Benachrichtigungen anpassen.

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

Trigger in Add-ons

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