Einfache Trigger

Mit Triggern kann Apps Script eine Funktion automatisch ausführen, wenn ein bestimmtes Ereignis eintritt, z. B. wenn ein Dokument geöffnet wird. 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 in Google Docs, Google Sheets, 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 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 dieser reservierten Funktionsnamen verwendet:

  • onOpen(e) wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument, eine Präsentation oder ein Formular öffnet, das er bearbeiten darf.
  • onInstall(e) wird ausgeführt, wenn ein Nutzer ein Editor-Add-on in Google Docs, Google Sheets, 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 aufruft 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.

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

Einschränkungen

Da einfache Trigger automatisch ausgelöst werden, ohne den Nutzer um Autorisierung zu bitten, unterliegen sie mehreren Einschränkungen:

  • Das Script muss an eine Datei in Google Sheets, Präsentationen, Docs oder Formulare 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.
  • Script-Ausführungen und API-Anfragen führen nicht dazu, dass Trigger ausgeführt werden. 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 für den Gmail-Dienst eine Autorisierung erforderlich ist. Ein einfacher Trigger kann jedoch einen Ausdruck mit dem Language-Dienst übersetzen, der anonym ist.
  • Sie können die Datei, an die sie gebunden sind, ändern, aber nicht auf andere Dateien zugreifen, da dies eine Autorisierung erfordern würde.
  • Je nach komplexen Sicherheitsbeschränkungen können sie die Identität des aktuellen Nutzers möglicherweise ermitteln.
  • Sie dürfen nicht länger als 30 Sekunden laufen.
  • Unter bestimmten Umständen werden Editor-Add-ons mit ihren einfachen Triggern onOpen(e) und onEdit(e) in einem Modus ohne Autorisierung ausgeführt, was einige zusätzliche Komplikationen mit sich bringt. Weitere Informationen finden Sie im Leitfaden zum Autorisierungslebenszyklus von Add-ons.
  • 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, das er bearbeiten darf. Der Trigger wird nicht ausgeführt, wenn Sie auf ein Formular antworten, sondern nur, wenn Sie das Formular zum Bearbeiten öffnen. onOpen(e) wird am häufigsten verwendet, um benutzerdefinierte Menüelemente in Google Sheets, Google Präsentationen, Google Docs oder Google Formulare einzufü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 Sheets, 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. Beachten Sie, dass es bestimmte Einschränkungen gibt, was onInstall(e) tun kann. Weitere Informationen zur Autorisierung onInstall(e) wird am häufigsten 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 nicht automatisch ausgeführt, es sei denn, die Datei wird wieder geöffnet.

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 angemessen zu reagieren. Mit der Funktion onEdit(e) im folgenden Beispiel wird beispielsweise ein Kommentar für die Zelle festgelegt, in der die letzte Bearbeitungszeit 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. Damit dieser Trigger aktiviert wird, müssen Sie die Tabelle aktualisieren, nachdem Sie den Trigger hinzugefügt haben, und jedes Mal, wenn die Tabelle geöffnet wird.

Wenn die Auswahl in kurzer Zeit zwischen mehreren Zellen wechselt, werden einige Ereignisse für die Änderung der Auswahl möglicherweise übersprungen, um die Latenz zu verringern. Wenn beispielsweise viele Auswahländerungen innerhalb von zwei Sekunden vorgenommen werden, wird der onSelectionChange(e)-Trigger nur durch die erste und die letzte Auswahländerung ausgelöst.

Im folgenden Beispiel wird die Hintergrundfarbe einer leeren Zelle mit der Funktion onSelectionChange(e) auf Rot gesetzt, wenn die Zelle ausgewählt wird.

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 ausgelöst, wenn ein Nutzer eine Web-App aufruft 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. Diese Trigger werden in den Anleitungen zu Web-Apps, HTML-Dienst und Content-Dienst genauer beschrieben. doGet(e) und doPost(e) unterliegen nicht den oben aufgeführten Einschränkungen.

Verfügbare Triggertypen

Wenn die Einschränkungen für einfache Trigger dazu führen, dass sie Ihre Anforderungen nicht erfüllen, kann stattdessen ein installierbarer Trigger verwendet werden. In der folgenden Tabelle sehen Sie, welche Arten von Triggern für die einzelnen Ereignistypen verfügbar sind. Beispielsweise unterstützen Google Sheets, Google Präsentationen, Google Formulare und Google Docs alle einfachen Open-Trigger, aber nur Google Sheets, Google Docs und Google Formulare unterstützen installierbare Open-Trigger.

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

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

function onEdit(e)
Google Sheets
Auswahl ändern
Google Sheets

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

function onInstall(e)
Ändern
Google Sheets
Formular senden
Google Sheets
Google Formulare
Zeitgesteuert (Uhr)
Tabellen
Präsentationen
Formulare
Dokumente
Standalone
Get
Standalone

function doGet(e)
Posten
Standalone

function doPost(e)

* Das Ereignis „Öffnen“ für Google-Formulare wird nicht ausgelöst, wenn ein Nutzer ein Formular öffnet, um darauf zu antworten, sondern wenn ein Bearbeiter das Formular öffnet, um es zu ändern.