Einfache Trigger

Mit Triggern kann Google Apps Script automatisch eine Funktion ausführen, wenn ein bestimmtes Ereignis eintritt, z. B. wenn ein Dokument geöffnet wird. Einfache Trigger sind eine Reihe reservierter 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 Arten von Triggern übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen zum Kontext enthält, in dem das Ereignis aufgetreten ist.

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

Erste Schritte

Wenn Sie einen einfachen Trigger verwenden möchten, erstellen Sie eine Funktion mit einem der folgenden reservierten Funktionsnamen:

• 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 Webanwendung aufruft 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 e Parameter in den Funktionsnamen oben ist ein Ereignisobjekt, das an die Funktion übergeben wird. Das Objekt enthält Informationen zum Kontext, der den Trigger ausgelöst 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 Skript muss an eine Google Sheets-, 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 schreibgeschützten Modus (Ansehen oder Kommentieren) geöffnet wird.
• Skriptausführungen und API-Anfragen lösen keine Trigger aus. Wenn Sie beispielsweise Range.setValue() aufrufen, um eine Zelle zu bearbeiten, wird der onEdit Trigger der Tabelle nicht ausgelöst.
• Sie können nicht auf Dienste zugreifen, die eine Autorisierung erfordern. Ein einfacher Trigger kann beispielsweise keine E‑Mail senden, da für den Gmail-Dienst eine Autorisierung erforderlich ist. Ein einfacher Trigger kann jedoch eine Phrase mit dem Language-Dienst übersetzen, der anonym ist.
• Sie können die Datei ändern, an die sie gebunden sind, aber nicht auf andere Dateien zugreifen, da dies eine Autorisierung erfordern würde.
• Je nach einem komplexen Satz von Sicherheitsbeschränkungen können sie die Identität des aktuellen Nutzers möglicherweise nicht ermitteln.
• Sie können nicht länger als 30 Sekunden ausgeführt werden.
• Unter bestimmten Umständen führen Editor-Add-ons ihre einfachen onOpen(e) und onEdit(e) Trigger im Modus ohne Autorisierung aus, was einige zusätzliche Komplikationen mit sich bringt. Weitere Informationen finden Sie im Leitfaden zum Autorisierungslebenszyklus von Add-ons.
• Für einfache Trigger gelten die Kontingentlimits für Apps Script-Trigger quota limits.

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 Google Sheets, Google Präsentationen, Google Docs oder Google Formulare benutzerdefinierte Menüelemente hinzuzufügen.

triggers/triggers.gs

Auf GitHub ansehen

/**
 * 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 onInstall(e) Trigger 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. Am häufigsten wird onInstall(e) verwendet, um onOpen(e) aufzurufen und benutzerdefinierte Menüs hinzuzufügen. Nach der Installation eines Add-ons ist die Datei bereits geöffnet. Daher wird onOpen(e) nicht automatisch ausgeführt, es sei denn, die Datei wird wieder geöffnet. Beachten Sie, dass es bestimmte Einschränkungen gibt, was onInstall(e) tun kann. Weitere Informationen zur Autorisierung.

triggers/triggers.gs

Auf GitHub ansehen

/**
 * 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 Funktion onEdit(e) unten legt beispielsweise einen Kommentar in der Zelle fest, in der die letzte Bearbeitungszeit aufgezeichnet wird.

triggers/triggers.gs

Auf GitHub ansehen

/**
 * 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()}`);
}

Der Trigger onEdit() reiht nur bis zu zwei Triggerereignisse in die Warteschlange ein.

onSelectionChange(e)

Der Trigger onSelectionChange(e) wird automatisch ausgeführt, wenn ein Nutzer die Auswahl in einer Tabelle ändert. Wenn Sie diesen Trigger aktivieren möchten, aktualisieren Sie die Tabelle, nachdem der Trigger hinzugefügt wurde und jedes Mal, wenn die Tabelle geöffnet wird.

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

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

triggers/triggers.gs

Auf GitHub ansehen

/**
 * 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 aufruft 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 zu Webanwendungen, zum HTML-Dienst, und zum Content-Dienst ausführlicher beschrieben. Beachten Sie, dass doGet(e) und doPost(e) nicht den oben aufgeführten Einschränkungen unterliegen.

Verfügbare Triggerarten

Wenn die Einschränkungen für einfache Trigger Ihre Anforderungen nicht erfüllen, kann stattdessen ein installierbarer Trigger verwendet werden. In der folgenden Tabelle sind die verfügbaren Triggerarten für die einzelnen Ereignistypen zusammengefasst. Google Sheets, Google Präsentationen, Google Formulare und Google Docs unterstützen beispielsweise alle einfache Open-Trigger, aber nur Google Sheets, Google Docs und Google Formulare unterstützen installierbare Open-Trigger.

Ereignis	Einfache Trigger	Installierbare Trigger
Öffnen	Google Sheets Google Präsentationen Google Formulare* Google Docs function onOpen(e)	Google Sheets Google Formulare* Google Docs
Bearbeiten	Google Sheets function onEdit(e)	Google Sheets
Auswahländerung	Google Sheets function onSelectionChange(e)
Installieren	Google Sheets Google Präsentationen Google Formulare Google Docs function onInstall(e)
Ändern		Google Sheets
Formular senden		Google Sheets Google Formulare
Zeitgesteuert (Uhr)		Google Sheets Google Präsentationen Google Formulare Google Docs Eigenständig
Abrufen	Eigenständig function doGet(e)
Posten	Eigenständig function doPost(e)

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