Apps Script-Trigger lösen ein bestimmtes Skript aus (die Trigger-Funktion), die ausgeführt werden soll, wenn ein bestimmtes Ereignis erfolgt. Nur bestimmte Ereignisse können zum Auslösen von Triggern führen. Die Google Workspace App unterstützt andere Termine.
Wenn ein Trigger ausgelöst wird, wird ein Ereignisobjekt erstellt. Diese JSON-Struktur enthält Details zu dem aufgetretenen Ereignis. Informationen zum Ereignis ist je nach Triggertyp unterschiedlich organisiert.
Sobald das Ereignisobjekt erstellt wurde, übergibt Apps Script es als Parameter an den
auslösen. Die Trigger-Funktion ist eine Callback-Funktion, die Sie
die entsprechenden Maßnahmen zu ergreifen,
. In einem Editor-Add-on ist z. B. ein Trigger
wird verwendet, um beim Öffnen eines Dokuments Add-on-Menüelemente zu erstellen. In diesem Fall
Implementieren der Triggerfunktion onOpen(e)
, um die Menüpunkte des Add-ons zu erstellen
möglicherweise unter Verwendung der Daten im Ereignisobjekt.
Diese Seite enthält Richtlinien zur Verwendung von Triggern in Editor Add-on-Projekte erstellt haben.
Triggertypen für Editor-Add-ons
Sie können die meisten allgemeinen Triggertypen verwenden, die für Apps Script-Projekte verfügbar sind in Editor-Add-ons, einschließlich einfacher Trigger und den meisten installierbaren Triggern. Die Die genaue Auswahl der verfügbaren Triggertypen hängt von der Erweiterung der Anwendung ab.
In der folgenden Tabelle sind die Arten von einfachen und installierbaren Triggern aufgeführt, die Editor-Add-ons können verwendet werden und enthalten Links zu den entsprechenden Ereignisobjekten:
Ereignis | Ereignisobjekt | Einfache Trigger | Installierbare Trigger |
---|---|---|---|
Öffnen Eine Editordatei wird geöffnet. |
<ph type="x-smartling-placeholder"></ph>
Docs-onOpen-Ereignisobjekt <ph type="x-smartling-placeholder"></ph> Ereignisobjekt „onOpen“ in Formularen . Tabellen-Ereignisobjekt „onOpen“ Google Präsentationen-Ereignisobjekt „onOpen“ |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Installieren Das Add-on wird installiert. |
<ph type="x-smartling-placeholder"></ph> Ereignisobjekt „onInstall“ |
![]() ![]() ![]() ![]()
|
|
Bearbeiten Der Zelleninhalt der Tabelle wird geändert. |
<ph type="x-smartling-placeholder"></ph> Google Tabellen-Ereignisobjekt „onEdit“ |
![]()
|
![]() |
Ändern Die Inhalte in einem Tabellenblatt werden bearbeitet oder formatiert. |
<ph type="x-smartling-placeholder"></ph> Google Tabellen-Ereignisobjekt „onChange“ |
![]() |
|
Formular senden Ein Google-Formular wird eingereicht. |
<ph type="x-smartling-placeholder"></ph>
Ereignisobjekt zum Senden von Formularen <ph type="x-smartling-placeholder"></ph> Google Tabellen-Ereignisobjekt „Formular senden“ |
![]() ![]() |
|
Zeitgesteuert (Uhr) Der Trigger wird zu einem bestimmten Zeitpunkt oder Intervall ausgelöst. |
<ph type="x-smartling-placeholder"></ph> Zeitgesteuertes Ereignisobjekt |
![]() ![]() ![]() ![]() |
* Das Ereignis "open" für Google Formulare tritt nicht ein, wenn ein Nutzer ein um sie zu beantworten, als wenn ein Bearbeiter das Formular öffnet, um es zu ändern.
Einfache Trigger in Add-ons
Bei einfachen Triggern wird eine Gruppe von Funktionsnamen, Dienste, die eine Autorisierung erfordern, und automatisch aktiviert. Manchmal kann ein einfaches Triggerereignis von einem installierbaren Trigger verarbeitet werden.
Sie können einem Add-on einen einfachen Trigger hinzufügen, indem Sie einfach eine Funktion implementieren mit einem der folgenden reservierten Namen:
onOpen(e)
wird ausgeführt, wenn ein Nutzer ein Dokument, eine Tabelle oder zu präsentieren.onOpen(e)
kann auch ausgeführt werden, wenn ein Formular im Editor geöffnet wird (aber nicht beim Ausfüllen des Formulars). Sie wird nur ausgeführt, wenn der Nutzer Bearbeitungsberechtigung für die betreffende Datei. Sie wird meistens dazu verwendet, Menüpunkte.onInstall(e)
wird ausgeführt, wenn ein Nutzer ein Add-on installiert. NormalerweiseonInstall(e)
wird nur zum Aufrufen vononOpen(e)
verwendet. wird sichergestellt, dass die Add-on-Menüs direkt nach der Installation, ohne dass der Nutzer die Seite aktualisieren muss.onEdit(e)
wird ausgeführt, wenn ein Nutzer einen Zellenwert in einer Tabelle ändert. Dieser Trigger wird nicht als Reaktion auf Zellenverschiebungen, Formatierungen oder andere Änderungen, die Zellenwerte nicht verändern.
Einschränkungen
Einfache Trigger in Add-ons unterliegen denselben Einschränkungen, die für einfache in anderen Apps Script-Projekten auslösen. Beachten Sie insbesondere diese Einschränkungen beim Entwerfen von Add-ons:
- Einfache Trigger werden nicht ausgeführt, wenn eine Datei schreibgeschützt geöffnet ist (Anzeige- oder Kommentarmodus. Dadurch wird verhindert, dass Ihre Add-on-Menüs ausgefüllt werden.
- Unter bestimmten Umständen führen Editor-Add-ons die
onOpen(e)
undonEdit(e)
einfache Trigger in einem Modus ohne Autorisierung. In diesem Modus werden einige zusätzliche Komplikationen, die in den Add-on-Autorisierungsmodell. - Einfache Trigger können keine Dienste verwenden oder Aktionen ausführen, die eine Autorisierung mit Ausnahme von die in den Add-on-Autorisierungsmodell.
- Einfache Trigger können nicht länger als 30 Sekunden ausgeführt werden. Achten Sie darauf, wie viel Verarbeitungsaufwand in einer einfachen Triggerfunktion erfolgt.
- Einfache Trigger unterliegen einem Apps Script-Trigger die Kontingentlimits.
Installierbare Trigger in Add-ons
Add-ons können
Installierbare Trigger programmatisch erstellen und ändern
mit dem Apps Script-Dienst Script
. Add-on
Installierbare Trigger können nicht manuell erstellt werden. Im Gegensatz zu einfachen Triggern
Installierbare Trigger können Dienste verwenden, die eine Autorisierung erfordern.
Installierbare Trigger in Add-ons senden keine Fehler-E-Mails wenn Fehler auftreten, da Nutzende in den meisten Fällen um das Problem anzugehen. Aus diesem Grund sollten Sie Ihr Add-on wenn möglich auch Fehler im Namen des Nutzers verarbeiten.
Add-ons können die folgenden installierbaren Trigger verwenden:
- Installierbare Open-Trigger werden ausgeführt, wenn ein Nutzer ein Dokument öffnet. Tabelle oder wenn ein Formular im Editor geöffnet wird (aber nicht beim Antworten hinzufügen).
- Editierbare Trigger werden ausgeführt, wenn ein Nutzer einen Zellenwert in einem Tabelle. Dieser Trigger wird nicht als Reaktion auf die Formatierung oder andere die Zellenwerte nicht verändern.
- Installierbare Änderungstrigger werden ausgeführt, wenn ein Nutzer eine Änderung in einem Tabelle, einschließlich Formatierungsänderungen und -änderungen an der Tabelle selbst (z. B. durch Hinzufügen einer Zeile).
Installierbare Formularübermittlungs-Trigger werden ausgeführt, wenn eine Google-Formularantwort gesendet.
Zeitgesteuerte Trigger (auch als „Auslöser“ bezeichnet), die zu einer bestimmten Zeit oder wiederholt auf einer regelmäßiges Zeitintervall.
Installierbare Trigger autorisieren
Wenn ein Entwickler ein Add-on aktualisiert, um neue Dienste zu nutzen, wird der Nutzer aufgefordert, das Add-on erneut zu autorisieren wenn sie es verwenden.
Bei Add-ons, die Trigger verwenden, gelten jedoch spezielle Identitätsbestätigungen. Stellen Sie sich ein Add-on vor, das das Senden von Formularen mithilfe eines Triggers überwacht: kann der Creator das Add-on bei der ersten Verwendung autorisieren und es dann monate- oder jahrelang ausgeführt werden, ohne das Formular erneut öffnen zu müssen. Wenn der Entwickler des Add-ons das Add-on aktualisieren müsste, um neue Dienste zu nutzen, eine zusätzliche Autorisierung erfordern, wird dem Ersteller des Formulars Dialogfeld zur erneuten Autorisierung, da das Formular und das Add-on funktionieren nicht mehr.
Im Gegensatz zu Triggern in normalen Apps Script-Projekten,
Add-ons werden weiterhin ausgelöst, auch wenn sie noch einmal autorisiert werden müssen. Das Skript
schlägt weiterhin fehl, wenn eine Codezeile gefunden wird, die eine Autorisierung durch das Skript erfordert.
nicht hat. Um dies zu vermeiden, können Entwickler die Methode verwenden,
ScriptApp.getAuthorizationInfo()
um den Zugriff auf Codeteile zu beschränken, die sich zwischen den veröffentlichten Versionen der
für das Add-on.
Unten sehen Sie ein Beispiel für die empfohlene Struktur, die Sie in Triggerfunktionen verwenden können, um Autorisierungsfehler zu vermeiden. Die Beispiel-Triggerfunktion reagiert auf eine Ereignis in einem Google Tabellen-Add-on und, falls eine erneute Autorisierung durchgeführt wird, erforderlich, sendet dem Nutzer des Add-ons eine Benachrichtigungs-E-Mail mithilfe von HTML-Vorlagen.
Code.gs
authorizationemail.html
Einschränkungen
Installierbare Trigger in Add-ons unterliegen denselben Einschränkungen die installierbare Trigger in anderen Apps Script-Projekten steuern.
Zusätzlich zu diesen Einschränkungen gelten für installierbare Auslöser für Add-ons:
- Jedes Add-on kann nur einen Trigger pro Typ, Nutzer und Dokument haben. Beispiel: Ein Nutzer kann in einer bestimmten Tabelle nur eine Änderung vornehmen. Der Nutzer kann aber auch einen Trigger für das Senden von Formularen oder einen zeitgesteuerten Triggers in derselben Tabelle. Ein anderer Nutzer mit Zugriff können eigene Trigger haben.
- Add-ons können nur Trigger für die Datei erstellen, in der das Add-on verwendet wird. Das heißt, ein Add-on, das in Google-Dokument A verwendet wird, wenn Google Dokument B geöffnet wird.
- Zeitgesteuerte Trigger können nicht häufiger als einmal pro Stunde ausgeführt werden.
- Add-ons senden dem Nutzer nicht automatisch eine E-Mail, wenn Code von einem installierbaren Trigger löst eine Ausnahme aus. Der Entwickler kann prüfen, Fehlerfälle zu erkennen und zu bearbeiten.
- Add-on-Trigger werden in folgenden Situationen nicht mehr ausgelöst:
<ph type="x-smartling-placeholder">
- </ph>
- Wenn das Add-on vom Nutzer deinstalliert wird,
- Wenn das Add-on in einem Dokument deaktiviert ist (bei erneuter Aktivierung, wird der Trigger wieder betriebsbereit wird) oder
- Wenn der Entwickler die Veröffentlichung des Add-ons aufhebt oder eine fehlerhafte Version an das Add-on-Store.
- Add-on-Triggerfunktionen werden ausgeführt, bis sie Code erreichen, der eine nicht autorisierte Dienstleistung erbracht werden, an der sie beendet werden. Dies gilt nur, wenn das Add-on veröffentlicht wurde. in einem regulären Apps Script-Projekt oder ein unveröffentlichtes Add-on wird überhaupt nicht ausgeführt, wenn irgendein Teil des Skripts Autorisierung.
- Installierbare Trigger unterliegen dem Apps Script-Trigger die Kontingentlimits.