Trigger für Editor-Add-ons

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“ 		Google Docs
Formulare*
Tabellen
Folien

function onOpen(e)

 Google Docs
Formulare
Google Tabellen
Installieren
Das Add-on wird installiert.		 <ph type="x-smartling-placeholder"></ph> Ereignisobjekt „onInstall“ Google Docs
Formulare
Tabellen
Folien

function onInstall(e)
Bearbeiten
Der Zelleninhalt der Tabelle wird geändert.		 <ph type="x-smartling-placeholder"></ph> Google Tabellen-Ereignisobjekt „onEdit“ Tabellen

function onEdit(e)

 Tabellen
Ändern
Die Inhalte in einem Tabellenblatt werden bearbeitet oder formatiert.		 <ph type="x-smartling-placeholder"></ph> Google Tabellen-Ereignisobjekt „onChange“ Tabellen
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“ 		Formulare
Google Tabellen
Zeitgesteuert (Uhr)
Der Trigger wird zu einem bestimmten Zeitpunkt oder Intervall ausgelöst.		 <ph type="x-smartling-placeholder"></ph> Zeitgesteuertes Ereignisobjekt Google Docs
Formulare
Tabellen
Folien

* 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. Normalerweise onInstall(e) wird nur zum Aufrufen von onOpen(e) verwendet. So 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) und onEdit(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 programmierbare 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 in das Formular ein.
  • 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 für die Uhr“ bezeichnet), die zu einer bestimmten Zeit oder wiederholt auf einer Zeitintervall.

Installierbare Trigger autorisieren

Wenn ein Entwickler ein Add-on aktualisiert, um neue Dienste zu verwenden, 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 im 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 funktioniert 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

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 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 Tabelle nur eine Änderung vornehmen. Der Nutzer kann aber auch einen Trigger zum Senden 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 nicht ausgeführt, wenn irgendein Teil des Skripts Autorisierung.
  • Installierbare Trigger unterliegen dem Apps Script-Trigger die Kontingentlimits.