Einfache Trigger

Mithilfe von Triggern kann in Apps Script eine Funktion automatisch ausgeführt werden, wenn ein bestimmtes Ereignis eintritt, z. B. das Öffnen eines Dokuments. Einfache Trigger sind eine Reihe von reservierten Funktionen, die in Apps Script integriert sind, z. B. die Funktion onOpen(e), die ausgeführt wird, wenn ein Nutzer eine Google Docs-, Tabellen-, Präsentations- oder Formulare-Datei öffnet. Installierbare Trigger bieten mehr Funktionen als einfache Trigger, müssen aber vor der Verwendung aktiviert werden. Bei beiden Triggertypen übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen zum Kontext enthält, in dem das Ereignis aufgetreten ist.

Erste Schritte

Wenn Sie einen einfachen Trigger verwenden möchten, erstellen Sie einfach eine Funktion, die einen der folgenden reservierten Funktionsnamen verwendet:

  • onOpen(e) wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument, eine Präsentation oder ein Formular öffnet, für die er eine Bearbeitungsberechtigung hat.
  • onInstall(e) wird ausgeführt, wenn ein Nutzer ein Editor-Add-on über Google Docs, Google Tabellen, Google Präsentationen oder Google Formulare installiert.
  • onEdit(e) wird ausgeführt, wenn ein Nutzer einen Wert in einer Tabelle ändert.
  • onSelectionChange(e) wird ausgeführt, wenn ein Nutzer die Auswahl in einer Tabelle ändert.
  • doGet(e) wird ausgeführt, wenn ein Nutzer eine Web-App besucht oder ein Programm eine HTTP-GET-Anfrage an eine Web-App sendet.
  • doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Webanwendung sendet.

Der Parameter e in den obigen Funktionsnamen ist ein Ereignisobjekt, das an die Funktion übergeben wird. Das Objekt enthält Informationen zum Kontext, der zum Auslösen des Trigger geführt hat. Die Verwendung ist jedoch optional.

Einschränkungen

Da einfache Trigger automatisch ausgelöst werden, ohne dass der Nutzer um Autorisierung gebeten wird, unterliegen sie mehreren Einschränkungen:

  • Das Script muss einer Google Tabellen-, Google Präsentationen-, Google Docs- oder Google Formulare-Datei gebunden sein oder ein Add-on sein, das eine dieser Anwendungen erweitert.
  • Sie werden nicht ausgeführt, wenn eine Datei im Lesemodus (Ansicht oder Kommentar) geöffnet wird.
  • Skriptausführungen und API-Anfragen führen nicht zum Ausführen von Triggern. Wenn Sie beispielsweise Range.setValue() aufrufen, um eine Zelle zu bearbeiten, wird der onEdit-Trigger der Tabelle nicht ausgeführt.
  • Sie können nicht auf Dienste zugreifen, für die eine Autorisierung erforderlich ist. Ein einfacher Trigger kann beispielsweise keine E-Mail senden, da der Gmail-Dienst eine Autorisierung erfordert. Er kann jedoch einen Ausdruck mit dem anonymen Sprachdienst übersetzen.
  • Sie können die Datei, mit der sie verknüpft sind, ändern, aber nicht auf andere Dateien zugreifen, da dafür eine Autorisierung erforderlich ist.
  • Die Identität des aktuellen Nutzers kann je nach komplexen Sicherheitseinschränkungen ermittelt werden.
  • Sie dürfen nicht länger als 30 Sekunden laufen.
  • Unter bestimmten Umständen werden die einfachen Trigger onOpen(e) und onEdit(e) von Editor-Add-ons im Modus ohne Autorisierung ausgeführt. Das kann zu zusätzlichen Komplikationen führen. Weitere Informationen finden Sie im Leitfaden zum Autorisierungslebenszyklus von Add-ons.
  • Für einfache Trigger gelten die Kontingentlimits für Apps Script-Trigger.

Diese Einschränkungen gelten nicht für doGet(e) oder doPost(e).

onOpen(e)

Der Trigger onOpen(e) wird automatisch ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument, eine Präsentation oder ein Formular öffnet, für die er Bearbeitungszugriff hat. Der Trigger wird nicht ausgeführt, wenn ein Formular ausgefüllt wird, sondern nur, wenn das Formular zum Bearbeiten geöffnet wird. onOpen(e) wird am häufigsten verwendet, um Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare benutzerdefinierte Menüpunkte hinzuzufügen.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

Der Trigger onInstall(e) wird automatisch ausgeführt, wenn ein Nutzer ein Editor-Add-on über Google Docs, Google Tabellen, Google Präsentationen oder Google Formulare installiert. Der Trigger wird nicht ausgeführt, wenn ein Nutzer das Add-on über die Website des Google Workspace Marketplace installiert. Beachten Sie, dass es bestimmte Einschränkungen gibt, was onInstall(e) tun kann. Weitere Informationen finden Sie unter Autorisierung. Am häufigsten wird onInstall(e) verwendet, um onOpen(e) aufzurufen und benutzerdefinierte Menüs hinzuzufügen. Wenn ein Add-on installiert ist, ist die Datei bereits geöffnet. onOpen(e) wird also nur dann automatisch ausgeführt, wenn die Datei wieder geöffnet wird.

Trigger/Trigger.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

Der Trigger onEdit(e) wird automatisch ausgeführt, wenn ein Nutzer den Wert einer Zelle in einer Tabelle ändert. Die meisten onEdit(e)-Trigger verwenden die Informationen im Ereignisobjekt, um entsprechend zu reagieren. Mit der Funktion onEdit(e) unten wird beispielsweise ein Kommentar in der Zelle festgelegt, der das letzte Mal aufgezeichnet wurde, als sie bearbeitet wurde.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

Der onSelectionChange(e)-Trigger wird automatisch ausgeführt, wenn ein Nutzer die Auswahl in einer Tabelle ändert. Um diesen Trigger zu aktivieren, müssen Sie die Tabelle aktualisieren, sobald der Trigger hinzugefügt wurde und wenn die Tabelle geöffnet wird.

Wenn die Auswahl innerhalb kurzer Zeit zwischen mehreren Zellen verschoben wird, werden möglicherweise einige Auswahländerungsereignisse übersprungen, um die Latenz zu reduzieren. Wenn beispielsweise innerhalb von zwei Sekunden viele Auswahländerungen vorgenommen werden, werden nur die erste und die letzte Auswahländerung den onSelectionChange(e)-Trigger aktivieren.

Im folgenden Beispiel wird der Hintergrund einer Zelle mit der Funktion onSelectionChange(e) rot, wenn eine leere Zelle ausgewählt ist.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) und doPost(e)

Der Trigger doGet(e) wird automatisch ausgeführt, wenn ein Nutzer eine Web-App besucht oder ein Programm eine HTTP-GET-Anfrage an eine Web-App sendet. doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Web-App sendet. Weitere Informationen zu diesen Triggern finden Sie in den Anleitungen zu Web-Apps, HTML-Diensten und Inhaltsdiensten. Beachten Sie, dass doGet(e) und doPost(e) nicht den oben aufgeführten Einschränkungen unterliegen.

Verfügbare Triggertypen

Wenn die Einschränkungen für einfache Trigger Ihre Anforderungen nicht erfüllen, kann stattdessen ein installierbarer Trigger verwendet werden. In der folgenden Tabelle ist zusammengefasst, welche Triggertypen für die einzelnen Ereignistypen verfügbar sind. So werden beispielsweise in Google Tabellen, Google Präsentationen, Google Formulare und Google Docs einfache Trigger unterstützt, aber nur in Google Tabellen, Google Docs und Google Formulare können Trigger installiert werden.

Ereignis Einfache Trigger Installierbare Trigger
Öffnen
Google Tabellen
Google Präsentationen
Google Formulare*
Google Docs

function onOpen(e)
Tabellen
Formulare*
Google Docs
Bearbeiten
Google Tabellen

function onEdit(e)
Google Tabellen
Auswahländerung
Google Tabellen

function onSelectionChange(e)
Installieren
Tabellen
Präsentationen
Formulare
Dokumente

function onInstall(e)
Ändern
Tabellen
Formular senden
Google Tabellen
Google Formulare
Zeitgesteuert (Uhr)
Tabellen
Präsentationen
Formulare
Google Docs
Standalone-Version
Get
Standalone

function doGet(e)
Posten
Eigenständig

function doPost(e)

* Das Ereignis „open“ für Google-Formulare tritt nicht auf, wenn ein Nutzer ein Formular öffnet, um es auszufüllen, sondern wenn ein Bearbeiter das Formular öffnet, um es zu ändern.