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 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 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 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, für das er die Berechtigung zum Bearbeiten hat.
  • onInstall(e) wird ausgeführt, wenn ein Nutzer ein Editor-Add-on aus 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 Funktionsnamen oben 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 des Triggers 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 Datei in Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare gebunden sein oder es muss sich um ein Add-on handeln, 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 lösen keine Trigger aus. Wenn Sie beispielsweise Range.setValue() aufrufen, um eine Zelle zu bearbeiten, führt dies nicht dazu, dass der onEdit-Trigger der Tabelle ausgeführt wird.
  • Sie können nicht auf Dienste zugreifen, für die eine Autorisierung erforderlich ist. Ein einfacher Trigger kann beispielsweise keine E-Mail senden, weil der Gmail-Dienst eine Autorisierung erfordert. Ein einfacher Trigger kann jedoch eine Wortgruppe mit dem Sprachdienst übersetzen, der anonym ist.
  • Sie können die Datei, an die sie gebunden sind, ändern, aber nicht auf andere Dateien zugreifen, da hierfür eine Autorisierung erforderlich ist.
  • Abhängig von einer komplexen Gruppe von Sicherheitsbeschränkungen können sie die Identität des aktuellen Nutzers möglicherweise nicht ermitteln.
  • Sie dürfen maximal 30 Sekunden dauern.
  • 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 im Leitfaden zum Lebenszyklus der Add-on-Autorisierung.
  • 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, für das er die Bearbeitungsberechtigung hat. Der Trigger wird nicht beim Antworten auf ein Formular ausgeführt, sondern nur beim Öffnen des Formulars, um es zu bearbeiten. onOpen(e) wird in der Regel verwendet, um benutzerdefinierte Menüelemente in Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare hinzuzufügen.

Trigger/Trigger.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 aus 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. Für onInstall(e) gelten bestimmte Einschränkungen. Weitere Informationen zur Autorisierung Die häufigste Verwendung von onInstall(e) besteht darin, onOpen(e) aufzurufen, um benutzerdefinierte Menüs hinzuzufügen. Denn wenn ein Add-on installiert wird, ist die Datei bereits geöffnet. Daher wird onOpen(e) erst automatisch ausgeführt, wenn die Datei noch einmal 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 folgenden onEdit(e)-Funktion wird beispielsweise ein Kommentar für die Zelle festgelegt, in der die letzte Bearbeitung angegeben ist.

Trigger/Trigger.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 und jedes Mal 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 verringern. Wenn beispielsweise viele Auswahländerungen innerhalb von zwei Sekunden aufeinander vorgenommen werden, wird der onSelectionChange(e)-Trigger nur durch die erste und die letzte Auswahländerung ausgelöst.

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

Trigger/Trigger.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 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. Weitere Informationen zu diesen Triggern finden Sie in den Anleitungen zu Webanwendungen, HTML-Diensten und Inhaltsdiensten. doGet(e) und doPost(e) unterliegen nicht den oben aufgeführten Einschränkungen.

Verfügbare Triggertypen

Wenn die Einschränkungen für einfache Trigger dafür sorgen, dass Ihre Anforderungen nicht erfüllt werden, 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 einfachen Öffnen-Trigger, aber nur Google Tabellen, Google Docs und Google Formulare unterstützen installierbare offene Trigger.

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

function onOpen(e)
Tabellen
Formulare*
Dokumente
Bearbeiten
Tabellen

function onEdit(e)
Tabellen
Auswahländerung
Tabellen

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

function onInstall(e)
Umsteigen
Tabellen
Formular gesendet
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“ 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.