Einfache Trigger

Mit Triggern kann Apps Script eine Funktion automatisch ausführen, wenn ein bestimmtes Ereignis eintritt, z. B. das Öffnen eines Dokuments. Einfache Trigger sind eine Reihe von reservierten Funktionen in Apps Script. Die Funktion onOpen(e) wird beispielsweise ausgeführt, wenn ein Nutzer eine Google Docs-, Google Tabellen-, Google Präsentationen- oder Google Formulare-Datei öffnet. Installierbare Trigger bieten mehr Möglichkeiten als einfache Trigger, müssen aber vor der Verwendung aktiviert werden. Für beide Triggertypen übergibt Apps Script die ausgelöste Funktion an ein Ereignisobjekt, das Informationen über den 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, in der er Bearbeitungszugriff 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 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 Parameter e in den oben aufgeführten Funktionsnamen 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 dass der Nutzer um eine Autorisierung gebeten wird, unterliegen sie mehreren Einschränkungen:

  • Das Skript muss an eine 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 geöffnet wird.
  • Skriptausführungen und API-Anfragen führen nicht zur Ausführung von Triggern. Wenn Sie beispielsweise Range.setValue() zum Bearbeiten einer Zelle aufrufen, wird der Trigger onEdit der Tabelle nicht ausgeführt.
  • Er kann nicht auf Dienste zugreifen, die eine Autorisierung erfordern. Von einem einfachen Trigger kann beispielsweise keine E-Mail gesendet werden, da der Gmail-Dienst eine Autorisierung erfordert. Mit einem einfachen Trigger kann jedoch eine Wortgruppe in den Sprachdienst umgewandelt werden, der anonym ist.
  • Sie können die gebundene Datei ändern, aber nicht auf andere Dateien zugreifen, da hierfür eine Autorisierung erforderlich wäre.
  • Je nach komplexen Sicherheitsbeschränkungen können sie die Identität des aktuellen Nutzers möglicherweise 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 in einem Modus ohne Autorisierung aus, der einige zusätzliche Komplikationen mit sich bringt. Weitere Informationen finden Sie im Leitfaden zum Lebenszyklus der Add-on-Autorisierung.
  • 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 beim Antworten auf ein Formular nicht ausgeführt, sondern nur beim Öffnen des Formulars, um es zu bearbeiten.) onOpen(e) wird am häufigsten verwendet, um benutzerdefinierte Menüpunkte zu 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 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. Beachten Sie, dass es bestimmte Einschränkungen dafür gibt, was onInstall(e) tun darf. Weitere Informationen zur Autorisierung Die gebräuchlichste Verwendung von onInstall(e) ist einfach der Aufruf von onOpen(e), um benutzerdefinierte Menüs hinzuzufügen. Wenn ein Add-on installiert ist, ist die Datei schließlich bereits geöffnet und onOpen(e) wird nur dann allein ausgeführt, wenn die Datei wieder 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 in der Zelle festgelegt, in dem die letzte Bearbeitung aufgezeichnet wird.

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. Wenn Sie diesen Trigger aktivieren möchten, müssen Sie die Tabelle aktualisieren, nachdem der Trigger hinzugefügt wurde, und jedes Mal, wenn die Tabelle geöffnet wird.

Wenn sich die Auswahl innerhalb kurzer Zeit zwischen mehreren Zellen bewegt, können einige Auswahländerungsereignisse übersprungen werden, um die Latenz zu verringern. Wenn beispielsweise viele Auswahländerungen innerhalb von zwei Sekunden nacheinander vorgenommen werden, werden nur bei der ersten und letzten Auswahländerung der onSelectionChange(e)-Trigger aktiviert.

Wenn im Beispiel unten eine leere Zelle ausgewählt ist, legt die Funktion onSelectionChange(e) den Hintergrund der Zelle auf Rot fest.

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

Verfügbare Triggertypen

Wenn sie aufgrund der Einschränkungen für einfache Trigger nicht Ihren Anforderungen entsprechen, ist möglicherweise ein installierbarer Trigger geeignet. In der folgenden Tabelle ist zusammengefasst, welche Arten von Triggern für jeden Ereignistyp verfügbar sind. Google Tabellen, Google Präsentationen, Google Formulare und Google Docs unterstützen zwar alle einfache Trigger, aber nur Google Tabellen, Google Docs und Google Formulare können installierbare offene Trigger unterstützen.

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

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

function onEdit(e)
Tabellen
Änderung der Auswahl
Tabellen

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

function onInstall(e)
Umsteigen
Tabellen
Formular gesendet
Tabellen
Formulare
Zeitgesteuert (Uhr)
Tabellen
Präsentationen
Formulare
Google Docs
Google Sites
Standalone
Get
Google Sites
Standalone

function doGet(e)
beitrag
Google Sites
Standalone

function doPost(e)

* Das offene Ereignis für Google Formulare tritt nicht auf, wenn ein Nutzer ein Formular öffnet, um zu antworten. Vielmehr wird ein Formular von einem Mitbearbeiter geöffnet, um es zu ändern.