Trigger für Editor-Add-ons

Apps Script-Trigger führen dazu, dass eine bestimmte Scriptfunktion (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 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 Apps Script-Projekte verfügbar sind, in Editor-Add-ons verwenden, einschließlich einfacher Trigger und der meisten installierbaren Trigger. Die genaue Anzahl der verfügbaren Triggertypen hängt von der Anwendung ab, die erweitert wird.

In der folgenden Tabelle sind die Arten von einfachen und installierbaren Triggern 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 Editor-Datei wird geöffnet.		 Docs-onOpen-Ereignisobjekt
Forms-onOpen-Ereignisobjekt
Sheets-onOpen-Ereignisobjekt
Präsentationen-onOpen-Ereignisobjekt 		Docs
Formulare*
Tabellen
Präsentationen

function onOpen(e)

 Docs
Forms
Sheets
Installieren
Das Add‑on wird installiert.		 onInstall-Ereignisobjekt Docs
Forms
Sheets
Präsentationen

function onInstall(e)
Bearbeiten
Der Inhalt einer Tabellenzelle wird geändert.		 „onEdit“-Ereignisobjekt für Google Sheets Google Sheets

function onEdit(e)

 Google Sheets
Änderung
Inhalte in einem Tabellenblatt werden bearbeitet oder formatiert.		 Sheets-Ereignisobjekt „onChange“ Google Sheets
Form-submit
Ein Google-Formular wird gesendet.		 Formular-Ereignisobjekt „form-submit“ in Google Formulare
Formular-Ereignisobjekt „form-submit“ in Google Tabellen 		Formulare
Tabellen
Zeitgesteuert (Uhr)
Der Trigger wird zu einer bestimmten Zeit oder in einem bestimmten Intervall ausgelöst.		 Zeitgesteuertes Ereignisobjekt Docs
Formulare
Sheets
Präsentationen

* Das Ereignis „Öffnen“ für Google-Formulare wird nicht ausgelöst, wenn ein Nutzer ein Formular öffnet, um darauf zu antworten, 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 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 auf das Formular geantwortet wird). Sie wird nur ausgeführt, wenn der Nutzer die Berechtigung hat, die betreffende Datei zu bearbeiten. 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 zum Aufrufen von onOpen(e) verwendet. So werden die Add-on-Menüs direkt 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 ausgelöst, wenn Zellen verschoben oder formatiert werden oder andere Änderungen vorgenommen werden, die die Zellenwerte nicht ä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 schreibgeschützten Modus (Ansichts- oder Kommentarmodus) geöffnet wird. Dadurch werden die Add-on-Menüs nicht gefüllt.
  • Unter bestimmten Umständen werden die einfachen Trigger onOpen(e) und onEdit(e) von Editor-Add-ons im Modus „Keine Autorisierung“ ausgeführt. Dieser Modus birgt einige zusätzliche Komplikationen, wie im Autorisierungsmodell für Add-ons beschrieben.
  • Einfache Trigger können keine Dienste verwenden oder andere Aktionen ausführen, für die eine Autorisierung erforderlich ist, sofern nicht im Autorisierungsmodell für Add-ons anders angegeben.
  • Einfache Trigger dürfen nicht länger als 30 Sekunden ausgeführt werden. Achten Sie darauf, die Verarbeitung in einer einfachen Triggerfunktion zu minimieren.
  • Einfache Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.

Installierbare Trigger in Add‑ons

Mit dem Apps Script-Dienst Script können Add-ons installierbare Trigger programmatisch 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, für die eine Autorisierung erforderlich ist.

Installierbare Trigger in Add-ons senden keine Fehler-E-Mails an den Nutzer, wenn Fehler auftreten, da der Nutzer das Problem in den meisten Fällen nicht beheben kann. Daher sollten Sie Ihr Add-on so gestalten, dass Fehler nach Möglichkeit im Namen des Nutzers ordnungsgemäß behandelt werden.

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

  • Open-Installable-Trigger werden ausgeführt, wenn ein Nutzer ein Dokument oder eine Tabelle öffnet oder wenn ein Formular im Editor geöffnet wird (nicht jedoch, wenn auf das Formular geantwortet wird).
  • Bearbeitbare installierbare Trigger werden ausgeführt, wenn ein Nutzer einen Zellwert in einer Tabelle ändert. Dieser Trigger wird nicht ausgelöst, wenn Formatierungen oder andere Änderungen vorgenommen werden, die die Zellwerte nicht ändern.
  • Änderung: Installierbare 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 Trigger vom Typ „Form-submit“ werden ausgeführt, wenn eine Google Formular-Antwort gesendet wird.

    enthält weitere Informationen in einem FormResponse-Objekt.

  • Zeitgesteuerte Trigger (auch als Uhr-Trigger bezeichnet) werden zu einem bestimmten Zeitpunkt oder wiederholt in regelmäßigen Zeitintervallen 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 beim nächsten Mal, wenn sie das Add-on verwenden, aufgefordert, es neu zu autorisieren.

Bei Add-ons, die Trigger verwenden, gibt es jedoch besondere Autorisierungsanforderungen. Stellen Sie sich ein Add-on vor, das einen Trigger verwendet, um Formulareinsendungen zu überwachen: Ein Formularersteller autorisiert das Add-on möglicherweise beim ersten Mal, wenn er es verwendet, und lässt es dann monate- oder jahrelang laufen, ohne das Formular jemals wieder zu öffnen. Wenn der Add-on-Entwickler das Add-on aktualisieren würde, um neue Dienste zu verwenden, für die eine zusätzliche Autorisierung erforderlich ist, würde der Formularersteller das Dialogfeld für die erneute Autorisierung nie sehen, da er das Formular nie wieder geöffnet hat. Das Add-on würde dann nicht mehr funktionieren.

Im Gegensatz zu Triggern in regulären Apps Script-Projekten werden Trigger in Add-ons weiterhin ausgelöst, auch wenn sie neu autorisiert werden müssen. Das Skript schlägt jedoch weiterhin fehl, wenn es auf eine Codezeile trifft, für die eine Autorisierung erforderlich ist, 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 beschränken, die sich zwischen veröffentlichten Versionen des Add-ons geändert haben.

Unten sehen Sie ein Beispiel für die empfohlene Struktur, die in Triggerfunktionen verwendet werden sollte, um Autorisierungsfehler zu vermeiden. Die Beispiel-Triggerfunktion reagiert auf ein Ereignis vom Typ „form-submit“ in einem Google Sheets-Add-on und sendet dem Nutzer des Add-ons bei Bedarf eine Benachrichtigungs-E-Mail mit Vorlagen-HTML.

Code.gs

triggers/form/Code.gs
/**
 * 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
<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 mehrere Einschränkungen:

  • Jedes Add-on kann nur einen Trigger jedes Typs pro Nutzer und Dokument haben. In einer bestimmten Tabelle kann ein bestimmter Nutzer beispielsweise nur einen Bearbeitungstrigger haben, obwohl er in derselben Tabelle auch einen Formular-Sende-Trigger oder einen zeitgesteuerten Trigger haben könnte. 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. Ein Add-on, das in Google-Dokument A verwendet wird, kann also keinen Trigger erstellen, um zu überwachen, 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 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 ordnungsgemäß 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 ist (wenn es wieder aktiviert wird, ist der Trigger wieder betriebsbereit) oder
    • Wenn der Entwickler das Add-on aus dem Add-on-Shop entfernt oder eine fehlerhafte Version einreicht.
  • Add-on-Triggerfunktionen werden ausgeführt, bis sie Code erreichen, der einen nicht autorisierten Dienst verwendet. An diesem Punkt werden sie beendet. Dies gilt nur, wenn das Add‑on veröffentlicht wird. Derselbe Trigger in einem regulären Apps Script-Projekt oder einem unveröffentlichten Add‑on wird überhaupt nicht ausgeführt, wenn für einen Teil des Scripts eine Autorisierung erforderlich ist.
  • Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.