Trigger für Editor-Add-ons

Apps Script-Trigger führen dazu, dass eine bestimmte Skript funktion (die Triggerfunktion) ausgeführt wird, wenn ein bestimmtes Ereignis eintritt. Nur bestimmte Ereignisse können Trigger auslösen und jede Google Workspace-Anwendung unterstützt eine andere Reihe 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.

Sobald 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 die entsprechenden Maßnahmen zu ergreifen, um auf das Ereignis zu reagieren. 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. Dabei können Sie die Daten im Ereignisobjekt verwenden.

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 der generischen Triggertypen, die für Google Apps Script Projekte in Editor-Add-ons verfügbar sind, verwenden, einschließlich einfacher Trigger und der meisten installierbarer Trigger. Die genaue Anzahl der verfügbaren Triggertypen hängt von der Anwendung ab, die erweitert wird.

Im Gegensatz zu Editor-Add-ons können Google Workspace-Add-ons keine generischen einfachen oder installierbaren Apps Script-Trigger verwenden. 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 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:

Ereignis	Ereignisobjekt	Einfache Trigger	Installierbare Trigger
Öffnen Eine Editor-Datei wird geöffnet.	Docs onOpen event object Forms onOpen event object Sheets onOpen event object Slides onOpen event object	Docs Formulare* Tabellen Präsentationen function onOpen(e)	Docs Formulare Tabellen
Installieren Das Add-on wird installiert.	onInstall event object	Docs Formulare Tabellen Präsentationen function onInstall(e)
Bearbeiten Der Inhalt einer Tabellenzelle wird geändert.	Sheets onEdit event object	Tabellen function onEdit(e)	Tabellen
Ändern Inhalte in einem Tabellenblatt werden bearbeitet oder formatiert.	Sheets onChange event object		Tabellen
Formular senden Ein Google-Formular wird gesendet.	Forms form-submit event object Sheets form-submit event object		Formulare Tabellen
Zeitgesteuert (Uhr) Der Trigger wird zu einem bestimmten Zeitpunkt oder in einem bestimmten Intervall ausgelöst.	Time-driven event object	Docs Formulare Tabellen Präsentationen

* Das Ereignis „Öffnen“ 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, die eine Autorisierung erfordern, und 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 eine Funktion mit einem der folgenden reservierten Namen implementieren:

• onOpen wird ausgeführt, wenn ein Nutzer ein Dokument, eine Tabelle oder eine Präsentation öffnet. onOpen kann auch ausgeführt werden, wenn ein Formular im Editor geöffnet wird (aber nicht, wenn es ausgefüllt wird). Es wird nur ausgeführt, wenn der Nutzer die Berechtigung hat, die betreffende Datei zu bearbeiten. Am häufigsten wird es verwendet, um Menüelementezu erstellen.
• onInstall wird ausgeführt, wenn ein Nutzer ein Add-on installiert. Normalerweise wird onInstall nur verwendet, um onOpen aufzurufen. So werden die Add-on-Menüs sofort nach der Installation angezeigt, ohne dass der Nutzer die Seite aktualisieren muss.
• onEdit wird ausgeführt, wenn ein Nutzer einen Zellenwert in einer Tabelle ändert. Dieser Trigger wird nicht als Reaktion auf Zellverschiebungen, Formatierungen oder andere Änderungen ausgelöst, die keine Zellenwerte ändern.

Einschränkungen

Für einfache Trigger in Add-ons gelten dieselben Einschränkungen wie für einfache Trigger in anderen Arten von Apps Script-Projekten. Beachten Sie diese Einschränkungen besonders beim Entwerfen von Add-ons:

• Einfache Trigger werden nicht ausgeführt, wenn eine Datei im schreibgeschützten Modus (Ansehen oder Kommentieren) geöffnet wird. Dadurch werden die Menüs Ihres Add-ons nicht gefüllt.
• Unter bestimmten Umständen führen Editor-Add-ons ihre einfachen Trigger onOpen und onEdit im Modus ohne Autorisierung aus. Dieser Modus führt zu Komplikationen, wie im Autorisierungsmodell für Add-ons beschrieben.
• Einfache Trigger können keine Dienste verwenden oder andere Aktionen ausführen, die eine Autorisierung erfordern, es sei denn, dies ist im Autorisierungsmodell für Add-ons beschrieben.
• Einfache Trigger können nicht länger als 30 Sekunden ausgeführt werden. Minimieren Sie die Menge der Verarbeitung, die in einer einfachen Triggerfunktion ausgeführt wird.
• Für einfache Trigger gelten die Kontingentlimits für Apps Script-Trigger quota limits.

Installierbare Trigger in Add-ons

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

Installierbare Trigger in Add-ons senden keine Fehlermeldungen an den Nutzer, 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 gestalten, dass Fehler nach Möglichkeit im Namen des Nutzers behandelt werden.

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

• Installierbare Öffnen-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 es ausgefüllt wird).
• Installierbare Bearbeiten-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, die keine Zellenwerte ändern.
• Installierbare Ändern-Trigger werden ausgeführt, wenn ein Nutzer Änderungen in einer Tabelle vornimmt, einschließlich Formatierungsänderungen und Änderungen an der Tabelle selbst (z. B. Hinzufügen einer Zeile).

• Installierbare Formular senden-Trigger werden ausgeführt, wenn eine Google Formular-Antwort gesendet wird.

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

• Zeitgesteuerte Trigger (auch Uhr-Trigger genannt) werden zu einem bestimmten Zeitpunkt 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 neu zu autorisieren.

Bei Add-ons, die Trigger verwenden, treten jedoch besondere Herausforderungen bei der Autorisierung auf. Stellen Sie sich ein Add-on vor, das einen Trigger verwendet, um Formulareinsendungen zu überwachen: Ein Formularersteller autorisiert das Add-on möglicherweise bei der ersten Verwendung und lässt es dann monate- oder jahrelang laufen, ohne das Formular jemals wieder zu öffnen. Wenn der Add-on-Entwickler das Add-on aktualisiert, um neue Dienste zu verwenden, die eine zusätzliche Autorisierung erfordern, sieht der Formularersteller das Dialogfeld zur erneuten Autorisierung nie, 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 Skript schlägt jedoch weiterhin fehl, wenn es auf eine Codezeile stößt, die eine Autorisierung erfordert, die es nicht hat. Verwenden Sie ScriptApp.getAuthorizationInfo , um den Zugriff auf Teile des Codes zu beschränken, die sich zwischen den Versionen von Add-on geändert haben.

In den folgenden Beispielen wird die empfohlene Struktur für Triggerfunktionen gezeigt, um Fallstricke bei der Autorisierung zu vermeiden. Die Beispiel-Triggerfunktion reagiert auf ein Formular-Senden-Ereignis in einem Google Tabellen-Add-on 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

Für installierbare Trigger in Add-ons gelten dieselben Einschränkungen wie für installierbare Trigger in anderen Arten von Apps Script Projekten.

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

• Für jedes Add-on kann es nur einen Trigger jedes Typs pro Nutzer und pro Dokument geben. In einer bestimmten Tabelle kann ein bestimmter Nutzer beispielsweise nur einen Bearbeitungstrigger haben. Der Nutzer kann aber auch einen Formular-Senden-Trigger oder einen zeitgesteuerten Trigger in derselben Tabelle haben. Ein anderer Nutzer mit Zugriff auf dieselbe Tabelle kann eine eigene Reihe von Triggern haben.
• Add-ons können nur Trigger für die Datei erstellen, in der das Add-on verwendet wird. Ein Add-on, das in Google Docs-Dokument A verwendet wird, kann also keinen Trigger erstellen, um zu überwachen, wann Google Docs-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 bei der Ausführung von Code durch einen installierbaren Trigger eine Ausnahme ausgelöst wird. Es liegt in der Verantwortung des Entwicklers, Fehlerfälle zu prüfen und zu behandeln.
• 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 wird (wenn es wieder aktiviert wird, funktioniert der Trigger wieder) oder
  • Wenn der Entwickler die Veröffentlichung des Add-ons aufhebt oder eine fehlerhafte Version im Add-on-Store einreicht.
• 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 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 Skripts eine Autorisierung erfordert.
• Für installierbare Trigger gelten die Kontingentlimits für Apps Script-Trigger quota limits.