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 von reservierten Funktionen, die in Apps Script integriert sind, z. B. die Funktion onOpen(e), die ausgeführt wird, wenn ein Nutzer eine Datei aus 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 des Ereignisses enthält.

Erste Schritte

Um einen einfachen Trigger zu verwenden, 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 die er eine Bearbeitungsberechtigung 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 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 Triggers geführt hat. Die Verwendung des Objekts 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 Skript muss an eine Datei in Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare gebunden sein oder ein Add-on sein, das eine dieser Anwendungen ergänzt.
  • Sie werden nicht ausgeführt, wenn eine Datei im Lesemodus (Anzeigen oder Kommentieren) geöffnet wird.
  • Skriptausführungen und API-Anfragen führen nicht zur Ausführung von Triggern. Wenn beispielsweise Range.setValue() aufgerufen wird, 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. Mit einem einfachen Trigger kann beispielsweise keine E-Mail gesendet werden, weil der Gmail-Dienst eine Autorisierung erfordert. Ein einfacher Trigger kann jedoch eine Wortgruppe mit dem anonymen Sprachdienst übersetzen.
  • Sie können die Datei, an die sie gebunden sind, ändern, aber nicht auf andere Dateien zugreifen, da dafür eine Autorisierung erforderlich ist.
  • Ob sie die Identität des aktuellen Nutzers ermitteln können, hängt von einer Reihe komplexer Sicherheitseinschränkungen ab.
  • Sie können nicht länger als 30 Sekunden ausgeführt werden.
  • Unter bestimmten Umständen führen Editor-Add-ons die einfachen Trigger onOpen(e) und onEdit(e) in einem Modus ohne Autorisierung aus, was einige 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) und 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 eine Bearbeitungsberechtigung hat. Der Trigger wird nicht ausgeführt, wenn Sie auf ein Formular antworten, sondern nur, wenn Sie das Formular öffnen, um es zu bearbeiten. onOpen(e) wird in der Regel verwendet, um in Google Tabellen, Google Präsentationen, Google Docs oder Google Formulare benutzerdefinierte Menüelemente 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 onInstall(e)-Trigger 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 von der Google Workspace Marketplace-Website installiert. Für onInstall(e) gelten bestimmte Einschränkungen. Weitere Informationen zur Autorisierung Am häufigsten wird onInstall(e) verwendet, um onOpen(e) aufzurufen, um benutzerdefinierte Menüs hinzuzufügen. Denn wenn ein Add-on installiert wird, ist die Datei bereits geöffnet, sodass onOpen(e) nur dann eigenständig ausgeführt wird, wenn die Datei noch einmal 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 Zelle in einer Tabelle ändert. Bei den meisten onEdit(e)-Triggern werden die Informationen im Ereignisobjekt verwendet, um korrekt zu reagieren. Die folgende onEdit(e)-Funktion legt beispielsweise einen Kommentar für die Zelle fest, in der die letzte Bearbeitung aufgezeichnet 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 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 reduzieren. Wenn beispielsweise viele Auswahländerungen innerhalb von zwei Sekunden voneinander vorgenommen werden, aktivieren nur die erste und letzte Auswahländerungen den Trigger onSelectionChange(e).

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

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 ausgeführt, wenn ein Nutzer eine Webanwendung aufruft oder von einem Programm eine GET-HTTP-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 Anleitungen zu Webanwendungen, HTML-Dienst und Inhaltsdienst näher erläutert. doGet(e) und doPost(e) unterliegen nicht den oben aufgeführten Einschränkungen.

Verfügbare Triggertypen

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

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

function onOpen(e)

Tabellen
Google Formulare*
Docs
Bearbeiten
Tabellen

function onEdit(e)

Tabellen
Auswahländerung
Tabellen

function onSelectionChange(e)

Installieren
Tabellen
Präsentationen
Google Formulare
Docs

function onInstall(e)

Umsteigen
Tabellen
Formular gesendet
Tabellen
Google Formulare
Zeitgesteuert (Uhr)
Tabellen
Präsentationen
Google Formulare
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 nur, wenn ein Bearbeiter das Formular öffnet, um es zu ändern.