Trigger für Editor-Add-ons

Apps Script-Trigger sorgen dafür, dass eine bestimmte Scriptfunktion (die Triggerfunktion) ausgeführt wird, wenn ein bestimmtes Ereignis eintritt. Nur bestimmte Ereignisse können Auslöser aktivieren. Jede Google Workspace-Anwendung unterstützt eine andere Gruppe von Ereignissen.

Wenn ein Trigger ausgelöst wird, wird ein Ereignisobjekt erstellt. Diese JSON-Struktur enthält Details zum aufgetretenen Ereignis. Die Informationen in der Ereignisobjektstruktur sind je nach Triggertyp unterschiedlich organisiert.

Nachdem das Ereignisobjekt erstellt wurde, gibt Apps Script es als Parameter an die Triggerfunktion weiter. Die Triggerfunktion ist eine Callback-Funktion, die Sie selbst implementieren müssen, um die erforderlichen Aktionen auszuführen, um auf das Ereignis zu reagieren. In einem Editor-Add-on wird beispielsweise ein Trigger verwendet, um Add-on-Menüpunkte zu erstellen, wenn ein Dokument geöffnet wird. In diesem Fall implementieren Sie die Triggerfunktion „on onOpen(e)“, um die für das Add-on erforderlichen Menüpunkte zu erstellen. Dabei können Sie gegebenenfalls die Daten im Ereignisobjekt verwenden.

Auf dieser Seite finden Sie Richtlinien zur Verwendung von Triggern in Add-on-Projekten für den Editor.

Triggertypen für Editor-Add-ons

Sie können die meisten der generischen Triggertypen, die für Apps Script-Projekte verfügbar sind, in Editor-Add-ons verwenden, einschließlich einfacher Trigger und der meisten installierbaren Trigger. Welche Triggertypen genau verfügbar sind, hängt von der erweiterten Anwendung ab.

Hinweis :Im Gegensatz zu Editor-Add-ons können für Google Workspace-Add-ons derzeit keine generischen Apps Script-Trigger verwendet werden. Stattdessen werden Trigger verwendet, die speziell für Google Workspace-Add-ons entwickelt wurden. Weitere Informationen finden Sie unter Trigger für Google Workspace-Add-ons.

In der folgenden Tabelle sind die Arten einfacher und installierbarer Trigger aufgeführt, die in Editor-Add-ons verwendet werden können. Außerdem finden Sie Links zu den entsprechenden Ereignisobjekten:

Ereignis	Ereignisobjekt	Einfache Trigger	Installierbare Trigger
Öffnen : Eine Editordatei wird geöffnet.	Docs onOpen-Ereignisobjekt Forms onOpen-Ereignisobjekt Sheets onOpen-Ereignisobjekt Präsentationen onOpen-Ereignisobjekt	Google Docs Google Formulare* Google Tabellen Google Präsentationen function onOpen(e)	Google Docs Google Formulare Google Tabellen
Installieren Das Add-on wird installiert.	onInstall-Ereignisobjekt	Google Docs Google Formulare Google Tabellen Google Präsentationen function onInstall(e)
Bearbeiten Der Inhalt der Tabellenzelle wird geändert.	Ereignisobjekt „onEdit“ in Google Tabellen	Google Tabellen function onEdit(e)	Google Tabellen
Ändern : Inhalte in einer Tabelle werden bearbeitet oder formatiert.	Ereignisobjekt „onChange“ in Google Tabellen		Google Tabellen
Form-submit Ein Google-Formular wird gesendet.	Ereignisobjekt „form-submit“ in Google Formulare Ereignisobjekt „form-submit“ in Google Tabellen		Formulare Tabellen
Zeitgesteuert (Uhr) Der Trigger wird zu einer bestimmten Zeit oder in einem bestimmten Intervall ausgelöst.	Zeitlich gesteuertes Ereignisobjekt		Google Docs Google Formulare Google Tabellen Google Präsentationen

* 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.

Einfache Trigger in Add-ons

Einfache Trigger verwenden eine Reihe reservierter Funktionsnamen, können keine Dienste verwenden, für die eine Autorisierung erforderlich ist, und sind automatisch aktiviert. In einigen Fällen kann ein einfaches Triggerereignis stattdessen von einem installierbaren Trigger verarbeitet werden.

Sie können einem Add-on einen einfachen Trigger hinzufügen, indem Sie einfach eine Funktion mit einem der folgenden reservierten Namen implementieren:

• onOpen(e) wird ausgeführt, wenn ein Nutzer ein Dokument, eine Tabelle oder eine Präsentation öffnet. onOpen(e) kann auch ausgeführt werden, wenn ein Formular im Editor geöffnet wird, aber nicht, wenn eine Antwort auf das Formular gegeben wird. Sie wird nur ausgeführt, wenn der Nutzer die Berechtigung zum Bearbeiten der betreffenden Datei hat. Sie wird am häufigsten zum Erstellen von Menüpunkten verwendet.
• onInstall(e) wird ausgeführt, wenn ein Nutzer ein Add-on installiert. Normalerweise wird onInstall(e) nur verwendet, um onOpen(e) aufzurufen. So werden die Add-on-Menüs sofort nach der Installation angezeigt, 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 durch das Verschieben von Zellen, das Formatieren oder andere Änderungen ausgelöst, die die Zellenwerte nicht verändern.

Einschränkungen

Einfache Trigger in Add-ons unterliegen denselben Einschränkungen wie einfache Trigger in anderen Arten von Apps Script-Projekten. Beachten Sie beim Entwerfen von Add-ons insbesondere die folgenden Einschränkungen:

• Einfache Trigger werden nicht ausgeführt, wenn eine Datei im Lesemodus (Ansicht oder Kommentar) geöffnet wird. Dadurch werden Ihre Add-on-Menüs nicht ausgefüllt.
• Unter bestimmten Umständen werden die einfachen Trigger onOpen(e) und onEdit(e) von Editor-Add-ons ohne Autorisierung ausgeführt. Dieser Modus bringt einige zusätzliche Komplikationen mit sich, die im Autorisierungsmodell für Add-ons beschrieben werden.
• Mit einfachen Triggern können keine Dienste verwendet oder andere Aktionen ausgeführt werden, die eine Autorisierung erfordern, es sei denn, dies ist im Autorisierungsmodell für Add-ons beschrieben.
• Einfache Trigger dürfen nicht länger als 30 Sekunden laufen. Achten Sie darauf, die Verarbeitung in einer einfachen Triggerfunktion so gering wie möglich zu halten.
• Für einfache Trigger gelten die Kontingentlimits für Apps Script-Trigger.

Installierbare Trigger in Add-ons

Mit dem Apps Script-Dienst Script können Sie installierbare Trigger programmatisch erstellen und ändern. Sie können nicht manuell erstellt werden. Im Gegensatz zu einfachen Triggern können für installierbare Trigger Dienste verwendet werden, für die eine Autorisierung erforderlich ist.

Bei installierbaren Triggern in Add-ons werden keine Fehler-E-Mails an den Nutzer gesendet, wenn Fehler auftreten, da er das Problem in den meisten Fällen nicht beheben kann. Aus diesem Grund sollten Sie Ihr Add-on so gestalten, dass Fehler im Namen des Nutzers nach Möglichkeit reibungslos verarbeitet werden.

Für Add-ons können die folgenden installierbaren Trigger verwendet werden:

• Installierbare Trigger vom Typ Öffnen werden ausgeführt, wenn ein Nutzer ein Dokument, eine Tabelle oder ein Formular im Editor öffnet (nicht jedoch, wenn er das Formular ausfüllt).
• Installierbare Trigger vom Typ Bearbeiten werden ausgeführt, wenn ein Nutzer einen Zellenwert in einer Tabelle ändert. Dieser Trigger wird nicht durch Formatierungen oder andere Änderungen ausgelöst, die die Zellenwerte nicht ändern.
• Installierbare Trigger vom Typ Änderung werden ausgeführt, wenn ein Nutzer eine Änderung in einer Tabelle vornimmt, einschließlich Formatierungsänderungen und Änderungen an der Tabelle selbst (z. B. das Hinzufügen einer Zeile).

• Installierbare Trigger vom Typ „Formular gesendet“ werden ausgeführt, wenn eine Google-Formularantwort gesendet wird.

  Hinweis: Es gibt zwei Versionen von Triggern für das Senden von Formularen: eine für Google Tabellen (wo Formularantworten erfasst werden) und eine für Google Formulare. Das Ereignisobjekt, das an eine Triggerfunktion für das Senden von Formularen in Google Tabellen übergeben wird, ist einfacher und gibt die Antwortwerte in einfachen Arrays zurück. Das Ereignisobjekt, das an eine Triggerfunktion für das Senden von Formularen in Google Forms übergeben wird, enthält weitere Informationen in einem FormResponse-Objekt.

• Zeitgesteuerte Trigger (auch als Uhrentrigger bezeichnet) werden zu einer bestimmten Zeit oder wiederholt in einem regelmäßigen Zeitintervall ausgelöst.

Installierbare Trigger autorisieren

Wenn ein Entwickler ein Add-on aktualisiert, um neue Dienste zu verwenden, die eine zusätzliche Autorisierung erfordern, werden Nutzer normalerweise aufgefordert, das Add-on bei der nächsten Verwendung noch einmal zu autorisieren.

Bei Add-ons mit Triggern gibt es jedoch besondere Autorisierungsprobleme. Angenommen, ein Add-on verwendet einen Trigger, um Formulareinreichungen zu überwachen: Ein Ersteller eines Formulars kann das Add-on bei der ersten Verwendung autorisieren und dann monate- oder jahrelang laufen lassen, ohne das Formular noch einmal zu öffnen. Wenn der Add-on-Entwickler das Add-on aktualisiert, um neue Dienste zu verwenden, für die eine zusätzliche Autorisierung erforderlich ist, wird dem Ersteller des Formulars das Dialogfeld zur erneuten Autorisierung nie angezeigt, da er das Formular nie wieder geöffnet hat. Das Add-on funktioniert dann nicht mehr.

Im Gegensatz zu Triggern in regulären Apps Script-Projekten werden Trigger in Add-ons auch dann ausgelöst, wenn sie neu autorisiert werden müssen. Das Script schlägt jedoch weiterhin fehl, wenn eine Codezeile erreicht wird, für die eine Autorisierung erforderlich ist, die das Script nicht hat. Um dies zu vermeiden, können Entwickler die Methode ScriptApp.getAuthorizationInfo() verwenden, um den Zugriff auf Codeteile zu steuern, die sich zwischen den veröffentlichten Versionen des Add-ons geändert haben.

Unten sehen Sie ein Beispiel für die empfohlene Struktur in Triggerfunktionen, um Autorisierungsfallen zu vermeiden. Die Beispiel-Triggerfunktion reagiert auf ein Ereignis vom Typ „Formular gesendet“ in einem Google Tabellen-Add-on und sendet dem Nutzer des Add-ons bei Bedarf eine Benachrichtigungs-E-Mail mit einer HTML-Vorlage.

Code.gs

triggers/form/Code.gs

Auf GitHub ansehen

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

Auf GitHub ansehen

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Einschränkungen

Installierbare Trigger in Add-ons unterliegen denselben Einschränkungen wie installierbare Trigger in anderen Arten von Apps Script-Projekten.

Zusätzlich zu diesen Einschränkungen gelten für installierbare Trigger in Add-ons noch weitere Einschränkungen:

• Jedes Add-on kann pro Nutzer und Dokument nur einen Trigger jedes Typs haben. In einer bestimmten Tabelle kann ein bestimmter Nutzer beispielsweise nur einen Bearbeitungstrigger haben, aber auch einen Trigger für das Senden eines Formulars oder einen zeitgesteuerten Trigger in derselben Tabelle. Ein anderer Nutzer mit Zugriff auf dieselbe Tabelle kann eigene Trigger haben.
• Mit Add-ons können nur Trigger für die Datei erstellt werden, in der das Add-on verwendet wird. Das heißt, ein Add-on, das in Google-Dokument A verwendet wird, kann keinen Trigger erstellen, um zu überwachen, wann Google-Dokument B geöffnet wird.
• Zeitbasierte Trigger können nicht häufiger als einmal pro Stunde ausgeführt werden.
• Add-ons senden dem Nutzer nicht automatisch eine E-Mail, wenn durch Code, der von einem installierbaren Trigger ausgeführt wird, eine Ausnahme ausgelöst wird. Es liegt in der Verantwortung des Entwicklers, Fehler zu prüfen und ordnungsgemäß zu behandeln.
• In den folgenden Fällen werden Add-on-Trigger nicht mehr ausgelöst:
  • Wenn das Add-on vom Nutzer deinstalliert wird,
  • Wenn das Add-on in einem Dokument deaktiviert ist (wird es wieder aktiviert, funktioniert der Trigger wieder) oder
  • Wenn der Entwickler das Add-on deaktiviert oder eine fehlerhafte Version im Add-on-Shop einreicht.
• Add-on-Triggerfunktionen werden ausgeführt, bis Code erreicht wird, in dem ein nicht autorisierter Dienst verwendet wird. Dann werden sie beendet. Dies gilt nur, wenn das Add-on veröffentlicht ist. Derselbe Trigger in einem regulären Apps Script-Projekt oder einem nicht veröffentlichten Add-on wird überhaupt nicht ausgeführt, wenn ein Teil des Scripts autorisiert werden muss.
• Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.