Einfache Trigger

Mithilfe von Triggern kann Apps Script eine Funktion automatisch ausführen, wenn ein bestimmtes Ereignis auftritt, 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 Datei aus Google Docs, Google Tabellen, Google Präsentationen oder Google Formulare ö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 über den Kontext enthält, in dem das Ereignis aufgetreten ist.

Erste Schritte

Um einen einfachen Trigger zu verwenden, erstellen Sie einfach eine Funktion, die einen dieser 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 in 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 Webanwendung besucht oder ein Programm eine HTTP-GET-Anfrage an eine Webanwendung 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 Triggers geführt hat. Die Verwendung dieses Objekts ist jedoch optional.

Einschränkungen

Da einfache Trigger automatisch ausgelöst werden, ohne dass der Nutzer um Autorisierung gebeten wird, gelten für sie mehrere Einschränkungen:

  • Das Skript muss an eine Datei in Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare gebunden sein oder ein Add-on sein, das eine dieser Anwendungen erweitert.
  • Sie werden nicht ausgeführt, wenn eine Datei im Lese- oder Kommentarmodus 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, die eine Autorisierung erfordern. Ein einfacher Trigger kann beispielsweise keine E-Mail senden, da der Gmail-Dienst eine Autorisierung erfordert. Ein einfacher Trigger kann jedoch eine Wortgruppe mit dem Sprachdienst übersetzen. Die Funktion ist anonym.
  • Sie können die Datei ändern, an die sie gebunden sind, aber nicht auf andere Dateien zugreifen, da dies eine Autorisierung erfordert.
  • 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 führen Editor-Add-ons die einfachen Trigger onOpen(e) und onEdit(e) in einem Modus ohne Autorisierung aus, was zusätzliche Komplikationen mit sich bringt. Weitere Informationen finden Sie in der Anleitung zum Add-on-Autorisierungslebenszyklus.
  • Einfache Trigger unterliegen den 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 nur dann ausgeführt, wenn Sie das Formular öffnen, um es zu bearbeiten. onOpen(e) wird am häufigsten verwendet, um benutzerdefinierte Menüpunkte in Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare 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 in 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 Google Workspace Marketplace-Website installiert. Es gelten bestimmte Einschränkungen für die Nutzung von onInstall(e). Weitere Informationen zur Autorisierung Am häufigsten wird onInstall(e) verwendet, um einfach onOpen(e) aufzurufen, um benutzerdefinierte Menüs hinzuzufügen. Schließlich ist die Datei bereits geöffnet, wenn ein Add-on installiert ist. Daher wird onOpen(e) nur dann automatisch ausgeführt, wenn die Datei wieder geöffnet wird.

triggers/triggers.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. Die folgende Funktion onEdit(e) legt beispielsweise einen Kommentar für die Zelle fest, in dem die letzte Bearbeitung aufgezeichnet wird.

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 Trigger onSelectionChange(e) 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, wird der Trigger onSelectionChange(e) nur durch die erste und die letzte Änderung ausgelöst.

Wenn im folgenden Beispiel eine leere Zelle ausgewählt wird, setzt die Funktion onSelectionChange(e) den Hintergrund der Zelle auf Rot.

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 doGet(e)-Trigger wird automatisch ausgeführt, wenn ein Nutzer eine Webanwendung oder ein Programm eine HTTP-GET-Anfrage an eine Webanwendung sendet. doPost(e) wird ausgeführt, wenn ein Programm eine HTTP-POST-Anfrage an eine Webanwendung sendet. Diese Trigger werden in den Leitfäden für Webanwendungen, HTML-Dienst und Inhaltsdienst näher erläutert. 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 unterstützen beispielsweise Google Tabellen, Google Präsentationen, Google Formulare und Google Docs alle einfache offene Trigger, aber nur Google Tabellen, Google Docs und Google Formulare unterstützen installierbare offene Trigger.

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

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

function onEdit(e)
Tabellen
Auswahländerung
Tabellen

function onSelectionChange(e)
Installieren
Google Tabellen
Google Präsentationen
Google Formulare
Google Docs

function onInstall(e)
Ändern
Tabellen
Formular senden
Tabellen
Formulare
Zeitgesteuert (Uhr)
Google Tabellen
Google Präsentationen
Google Formulare
Google Docs
Eigenständig
Get
Eigenständig

function doGet(e)
Beitrag
Eigenständig

function doPost(e)

* Das Ereignis „open“ in Google Formulare wird nicht ausgelöst, wenn ein Nutzer ein Formular öffnet, um es zu beantworten, sondern wenn ein Bearbeiter das Formular öffnet, um es zu ändern.