Trigger für Editor-Add-ons

Apps Script-Trigger sorgen dafür, dass bei jedem Auftreten eines bestimmten Ereignisses eine angegebene Skriptfunktion (die Triggerfunktion) ausgeführt wird. Nur bestimmte Ereignisse können Trigger auslösen. Jede Google Workspace-Anwendung unterstützt unterschiedliche Ereignisse.

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, übergibt Apps Script es als Parameter an die Triggerfunktion. Die Triggerfunktion ist eine Callback-Funktion, die Sie selbst implementieren müssen, um auf das Ereignis reagieren zu können. In einem Editor-Add-on wird beispielsweise ein Trigger verwendet, um Add-on-Menüelemente zu erstellen, wenn ein Dokument geöffnet wird. In diesem Fall implementieren Sie die Triggerfunktion onOpen(e), um die Menüelemente zu erstellen, die das Add-on benötigt. Dazu verwenden Sie möglicherweise die Daten im Ereignisobjekt.

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

Triggertypen für Editor-Add-ons

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

In der folgenden Tabelle sind die Typen von einfachen und installierbaren Triggern aufgeführt, die von Editor-Add-ons verwendet werden können. Außerdem finden Sie Links zu den entsprechenden Ereignisobjekten:

Veranstaltung	Ereignisobjekt	Einfache Trigger	Installierbare Trigger
Öffnen Eine Editordatei wird geöffnet.	Docs-Ereignisobjekt „onOpen“ Ereignisobjekt „onOpen“ in Google Formulare Ereignisobjekt „onOpen“ in Google Tabellen Ereignisobjekt „onOpen“ in Google Präsentationen	Docs Formulare* Tabellen Präsentationen function onOpen(e)	Docs Formulare Tabellen
Installieren Das Add-on ist installiert.	Ereignisobjekt „onInstall“	Docs Formulare Tabellen Präsentationen function onInstall(e)
Bearbeiten Der Inhalt der Tabellenzellen wurde geändert.	onEdit-Ereignisobjekt in Google Tabellen	Tabellen function onEdit(e)	Tabellen
Ändern Inhalte in einem Tabellenblatt werden bearbeitet oder formatiert.	Tabellen-onChange-Ereignisobjekt		Tabellen
Formular senden Ein Google-Formular wurde eingereicht.	Google Formulare-Ereignisobjekt Google Tabellen-Formular senden-Ereignisobjekt		Formulare Tabellen
Zeitgesteuert (Uhr) Der Trigger wird zu einer bestimmten Zeit oder zu einem bestimmten Intervall ausgelöst.	Zeitgesteuertes Ereignisobjekt		Docs Formulare Tabellen Präsentationen

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

Einfache Trigger in Add-ons

Für einfache Trigger werden reservierte Funktionsnamen verwendet. Sie können keine Dienste nutzen, für die eine Autorisierung erforderlich ist, und sie werden automatisch für die Verwendung 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 das Formular beantwortet wird). Sie wird nur ausgeführt, wenn der Nutzer die Berechtigung zum Bearbeiten der betreffenden Datei hat. Sie wird meistens zum Erstellen von Menüelementen verwendet.
• onInstall(e) wird ausgeführt, wenn ein Nutzer ein Add-on installiert. Normalerweise wird onInstall(e) nur verwendet, um onOpen(e) aufzurufen. Dadurch wird sichergestellt, dass die Add-on-Menüs sofort nach der Installation angezeigt werden, 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 bei Zellenverschiebungen, Formatierungen oder anderen Änderungen ausgelöst, die keine Zellenwerte ändern.

Einschränkungen

Für einfache Trigger in Add-ons gelten die gleichen Einschränkungen, die auch für einfache Trigger in anderen Arten von Apps Script-Projekten gelten. Beachten Sie bei der Entwicklung von Add-ons insbesondere folgende Einschränkungen:

• Einfache Trigger werden nicht ausgeführt, wenn eine Datei im Lese- oder Kommentarmodus geöffnet wird. Dadurch wird verhindert, dass Ihre Add-on-Menüs mit Daten gefüllt werden.
• Unter bestimmten Umständen führen Editor-Add-ons die einfachen Trigger onOpen(e) und onEdit(e) in einem Modus ohne Autorisierung aus. Dieser Modus ist mit einigen zusätzlichen Komplikationen verbunden, die im Add-on-Autorisierungsmodell beschrieben werden.
• Einfache Trigger können keine Dienste verwenden oder andere Aktionen ausführen, für die eine Autorisierung erforderlich ist. Hiervon ausgenommen sind die im Add-on-Autorisierungsmodell beschriebenen Fälle.
• Einfache Trigger können nicht länger als 30 Sekunden ausgeführt werden. Achten Sie darauf, die Verarbeitungsmenge 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

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

Installierbare Trigger in Add-ons senden dem Nutzer keine Fehler-E-Mails, wenn Fehler auftreten, da der Nutzer das Problem in den meisten Fällen nicht beheben kann. Aus diesem Grund sollten Sie Ihr Add-on so entwickeln, dass Fehler für den Nutzer nach Möglichkeit korrekt behoben werden.

Add-ons können die folgenden installierbaren Trigger verwenden:

• Installierbare Open-Trigger werden ausgeführt, wenn ein Nutzer ein Dokument oder eine Tabelle öffnet oder wenn ein Formular im Editor geöffnet wird (aber nicht, wenn das Formular beantwortet wird).
• Installierbare Edit-Trigger werden ausgeführt, wenn ein Nutzer einen Zellenwert in einer Tabelle ändert. Dieser Trigger wird nicht als Reaktion auf Formatierungen oder andere Änderungen ausgelöst, durch die keine Zellenwerte geändert werden.
• Installierbare Change-Trigger werden ausgeführt, wenn ein Nutzer Änderungen an einer Tabelle vornimmt, einschließlich Formatierungsänderungen und Änderungen an der Tabelle selbst (z. B. das Hinzufügen einer Zeile).

• Installierbare Form-submit-Trigger werden ausgeführt, wenn eine Google-Formularantwort gesendet wird.

• Zeitgesteuerte Trigger (auch als Zeittrigger 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, für die eine zusätzliche Autorisierung erforderlich ist, werden Nutzer normalerweise aufgefordert, das Add-on bei der nächsten Verwendung noch einmal zu autorisieren.

Für Add-ons, die Trigger verwenden, gelten jedoch spezielle Autorisierungsanforderungen. Stellen Sie sich ein Add-on vor, das einen Trigger verwendet, um Formularübermittlungen zu überwachen: Ein Formularersteller kann das Add-on bei der ersten Verwendung autorisieren und es dann Monate oder Jahre lang ausführen, ohne das Formular noch einmal zu öffnen. Wenn der Add-on-Entwickler das Add-on so aktualisieren müsste, dass neue Dienste verwendet werden, für die eine zusätzliche Autorisierung erforderlich ist, sieht der Ersteller das Dialogfeld zur erneuten Autorisierung nicht, da er das Formular nie wieder geöffnet hat. Das Add-on würde dann nicht mehr funktionieren.

Im Gegensatz zu Triggern in normalen Apps Script-Projekten werden Trigger in Add-ons weiterhin ausgelöst, selbst wenn sie noch einmal autorisiert werden müssen. Das Skript schlägt jedoch weiterhin fehl, wenn es auf eine Codezeile stößt, die eine Autorisierung erfordert, die das Skript nicht hat. Um dies zu vermeiden, können Entwickler die Methode ScriptApp.getAuthorizationInfo() verwenden, um den Zugriff auf Teile des Codes zu sperren, die sich zwischen veröffentlichten Versionen des Add-ons geändert haben.

Im Folgenden finden Sie ein Beispiel für die empfohlene Struktur zur Verwendung in Triggerfunktionen, um Probleme bei der Autorisierung zu vermeiden. Die Beispiel-Triggerfunktion reagiert auf ein Formular senden-Ereignis innerhalb eines Google Tabellen-Add-ons und sendet dem Nutzer des Add-ons eine Benachrichtigungs-E-Mail mit HTML-Vorlagen, wenn eine erneute Autorisierung erforderlich ist.

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

<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 den gleichen Einschränkungen wie installierbare Trigger in anderen Arten von Apps Script-Projekten.

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

• Jedes Add-on kann nur einen Trigger pro Typ, Nutzer und Dokument haben. Beispielsweise kann ein bestimmter Nutzer in einer bestimmten Tabelle nur einen Bearbeitungstrigger haben, obwohl er auch einen Trigger zum Senden eines Formulars oder einen zeitgesteuerten Trigger in derselben Tabelle haben kann. Ein anderer Nutzer mit Zugriff auf dieselbe Tabelle kann 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, kann keinen Trigger erstellen, der überwacht, wann 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, der von einem installierbaren Trigger ausgeführt wird, eine Ausnahme auslöst. Der Entwickler kann nach Fehlern suchen und diese ordnungsgemäß bearbeiten.
• Add-on-Trigger werden in den folgenden Situationen nicht mehr ausgelöst:
  • Wenn das Add-on vom Nutzer deinstalliert wird,
  • Wenn das Add-on in einem Dokument deaktiviert ist (wenn es wieder aktiviert wird, wird der Trigger wieder funktionsfähig) oder
  • Wenn der Entwickler die Veröffentlichung des Add-ons aufhebt oder eine fehlerhafte Version an den Add-on-Store sendet.
• Add-on-Triggerfunktionen werden ausgeführt, bis sie Code erreichen, der einen nicht autorisierten Dienst verwendet. Dann werden sie beendet. Dies gilt nur, wenn das Add-on veröffentlicht wurde. Derselbe Trigger in einem regulären Apps Script-Projekt oder ein nicht veröffentlichtes Add-on wird nicht ausgeführt, wenn ein Teil des Skripts autorisiert werden muss.
• Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.