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äsentationen- 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, das er bearbeiten darf.
  • 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-, Präsentationen-, Docs- oder 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.
  • Auslöser werden nicht durch Scriptausführungen und API-Anfragen ausgeführt. 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 dies eine Autorisierung erfordert.
  • Je nach komplexen Sicherheitseinschränkungen kann die Identität des aktuellen Nutzers ermittelt werden oder nicht.
  • Sie dürfen nicht länger als 30 Sekunden laufen.
  • 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.

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

onOpen(e)

Der onOpen(e)-Trigger 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 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.

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 beliebigen 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 jedes Mal, wenn die Tabelle geöffnet wird.

Wenn die Auswahl innerhalb kurzer Zeit zwischen mehreren Zellen bewegt wird, werden einige Ereignisse zur Auswahländerung möglicherweise übersprungen, um die Latenz zu verringern. 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. Für doGet(e) und doPost(e) gelten die oben aufgeführten Einschränkungen nicht.

Verfügbare Triggertypen

Wenn die Einschränkungen für einfache Trigger dazu führen, dass sie nicht Ihren Anforderungen entsprechen, kann stattdessen ein installierbarer Trigger verwendet werden. In der folgenden Tabelle sind die Triggertypen für die einzelnen Ereignistypen zusammengefasst. 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
Tabellen
Präsentationen
Formulare*
Google Docs

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

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

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

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

function doGet(e)
Posten
Standalone

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.