Installierbare Trigger

Wie einfache Trigger ermöglichen installierbare Trigger, dass Apps Script eine Funktion automatisch ausführt, wenn ein bestimmtes Ereignis eintritt, z. B. das Öffnen eines Dokuments. Installierbare Trigger bieten jedoch mehr Flexibilität als einfache Trigger: Sie können Dienste aufrufen, für die eine Autorisierung erforderlich ist. Außerdem bieten sie mehrere zusätzliche Ereignistypen, einschließlich zeitgesteuerter Trigger, und lassen sich programmatisch steuern. Bei einfachen und installierbaren Triggern übergibt Apps Script der ausgelösten Funktion ein Ereignisobjekt, das Informationen zum Kontext des Ereignisses enthält.

Einschränkungen

Obwohl installierbare Trigger mehr Flexibilität bieten als einfache Trigger, unterliegen sie dennoch mehreren Einschränkungen:

  • Sie werden nicht ausgeführt, wenn eine Datei im Lesemodus geöffnet wird, also zum Ansehen oder Kommentieren. Bei eigenständigen Skripts benötigen Nutzer mindestens Lesezugriff auf die Skriptdatei, damit Trigger ordnungsgemäß ausgeführt werden.

  • Skriptausführungen und API-Anfragen führen nicht zur Ausführung von Triggern. Wenn Sie beispielsweise FormResponse.submit() aufrufen, um eine neue Formularantwort zu senden, wird der Sendetrigger des Formulars nicht ausgeführt.

  • Installierbare Trigger werden immer unter dem Konto der Person ausgeführt, die sie erstellt hat. Wenn Sie beispielsweise einen installierbaren offenen Trigger erstellen, wird er ausgeführt, wenn Ihr Kollege das Dokument öffnet (sofern er Bearbeitungszugriff hat). Er wird jedoch unter Ihrem Konto ausgeführt. Wenn Sie also einen Trigger zum Senden einer E-Mail beim Öffnen eines Dokuments erstellen, wird die E-Mail immer von Ihrem Konto aus gesendet und nicht unbedingt von dem Konto, über das das Dokument geöffnet wurde. Sie könnten jedoch für jedes Konto einen installierbaren Trigger erstellen, was dazu führen würde, dass von jedem Konto eine E-Mail gesendet wird.

  • Ein bestimmtes Konto kann keine Trigger sehen, die aus einem zweiten Konto installiert wurden, auch wenn das erste Konto diese Trigger weiterhin aktivieren kann.

  • Installierbare Trigger unterliegen den Kontingentlimits für Apps Script-Trigger.

Zeitgesteuerte Trigger

Ein zeitgesteuerter Trigger (auch als Takttrigger bezeichnet) ähnelt einem Cronjob in Unix. Mit zeitgesteuerten Triggern können Skripts zu einer bestimmten Zeit oder in wiederkehrenden Intervallen ausgeführt werden, und zwar so oft wie jede Minute oder so selten wie einmal im Monat. Ein Add-on kann höchstens einmal pro Stunde einen zeitgesteuerten Trigger verwenden. Die Zeit kann leicht zufällig angeordnet sein. Wenn Sie beispielsweise einen wiederkehrenden Trigger für 9:00 Uhr erstellen, wählt Apps Script eine Zeit zwischen 9:00 Uhr und 10:00 Uhr aus und behält diesen Zeitpunkt von Tag zu Tag bei, damit 24 Stunden verstreichen, bevor der Trigger noch einmal ausgelöst wird.

Das folgende Beispiel zeigt eine Google Chat-App, die jede Minute eine Nachricht an jeden Bereich sendet, in dem sich die App befindet:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Ereignisgesteuerte Trigger

Installierbare ereignisgesteuerte Trigger ähneln einfachen Triggern wie onOpen(), können aber auf zusätzliche Ereignisse reagieren und verhalten sich anders.

Beispielsweise wird der installierbare offene Trigger für Google Tabellen genau wie der einfache Trigger onOpen() immer dann aktiviert, wenn die Tabelle von einem Nutzer mit Bearbeitungszugriff geöffnet wird. Die installierbare Version kann jedoch Dienste aufrufen, für die eine Autorisierung erforderlich ist. Die installierbare Version wird mit der Autorisierung des Nutzers ausgeführt, der den Trigger erstellt hat, auch wenn ein anderer Nutzer mit Bearbeitungszugriff die Tabelle öffnet.

FürGoogle Workspace -Anwendungen gibt es mehrere installierbare Trigger:

  • Ein installierbarer open-Trigger wird ausgeführt, wenn ein Nutzer eine Tabelle, ein Dokument oder ein Formular öffnet, für die er eine Bearbeitungsberechtigung hat.
  • Ein installierbarer edit-Trigger wird ausgeführt, wenn ein Nutzer einen Wert in einer Tabelle ändert.
  • Ein installierbarer change-Trigger wird ausgeführt, wenn ein Nutzer die Struktur einer Tabelle ändert, z. B. indem ein neues Tabellenblatt hinzugefügt oder eine Spalte entfernt wird.
  • Ein installierbarer Trigger für das Senden von Formularen wird ausgeführt, wenn ein Nutzer auf ein Formular antwortet. Es gibt zwei Versionen des Triggers zum Senden eines Formulars: eine für Google Formulare selbst und eine für Google Tabellen, wenn das Formular an eine Tabelle gesendet wird.
  • Ein installierbarer Trigger für Kalendertermine wird ausgeführt, wenn die Kalendertermine eines Nutzers aktualisiert, erstellt, bearbeitet oder gelöscht werden.

Sie können installierbare Trigger in eigenständigen und gebundenen Skripts verwenden. Ein eigenständiges Skript kann beispielsweise programmatisch einen installierbaren Trigger für eine beliebige Google Tabellen-Datei erstellen, indem TriggerBuilder.forSpreadsheet(key) aufgerufen und die ID der Tabelle übergeben wird.

Trigger manuell verwalten

So erstellen Sie manuell einen installierbaren Trigger im Skripteditor:

  1. Öffnen Sie Ihr Apps Script-Projekt.
  2. Klicken Sie links auf Trigger .
  3. Klicken Sie rechts unten auf Trigger hinzufügen.
  4. Wählen Sie den Triggertyp aus, den Sie erstellen möchten, und konfigurieren Sie ihn.
  5. Klicken Sie auf Speichern.

Trigger programmatisch verwalten

Sie können Trigger auch programmatisch mit dem Skriptdienst erstellen und löschen. Rufen Sie zuerst ScriptApp.newTrigger(functionName) auf, wodurch ein TriggerBuilder zurückgegeben wird.

Das folgende Beispiel zeigt, wie Sie zwei zeitgesteuerte Trigger erstellen – einen, der alle sechs Stunden und einen jeden Montag um 9:00 Uhr ausgelöst wird (in der Zeitzone, auf die Ihr Skript eingestellt ist).

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

Im nächsten Beispiel wird gezeigt, wie Sie einen installierbaren offenen Trigger für eine Tabelle erstellen. Im Gegensatz zu einem einfachen onOpen()-Trigger muss das Skript für den installierbaren Trigger nicht an die Tabelle gebunden sein. Wenn Sie diesen Trigger über ein eigenständiges Skript erstellen möchten, ersetzen Sie SpreadsheetApp.getActive() einfach durch einen Aufruf von SpreadsheetApp.openById(id).

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

Wenn Sie einen vorhandenen installierbaren Trigger programmatisch ändern möchten, müssen Sie ihn löschen und einen neuen erstellen. Wenn Sie die ID eines Triggers bereits gespeichert haben, können Sie sie löschen. Übergeben Sie dazu die ID als Argument an die folgende Funktion.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Fehler in Triggern

Wenn ein installierbarer Trigger ausgelöst wird, die Funktion aber eine Ausnahme auslöst oder nicht erfolgreich ausgeführt wird, wird keine Fehlermeldung auf dem Bildschirm angezeigt. Denn wenn ein zeitgesteuerter Trigger ausgeführt wird oder ein anderer Nutzer Ihren Formularversand-Trigger aktiviert, sind Sie möglicherweise nicht einmal an Ihrem Computer.

Stattdessen erhalten Sie von Apps Script eine E-Mail, die in etwa so aussieht:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Google Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

Die E-Mail enthält einen Link, über den Sie den Trigger deaktivieren oder neu konfigurieren können. Wenn das Skript an eine Google Tabellen-, Google Docs- oder Google Formulare-Datei gebunden ist, enthält die E-Mail auch einen Link zu dieser Datei. Über diese Links können Sie den Trigger deaktivieren oder das Skript bearbeiten, um den Fehler zu beheben.

So überprüfen Sie alle Trigger, die mit Ihrem Google-Konto verknüpft sind, und deaktivieren die Trigger, die Sie nicht mehr benötigen:

  1. Rufen Sie script.google.com auf.
  2. Klicken Sie links auf Meine Trigger.

  3. Klicken Sie zum Löschen eines Triggers rechts neben dem Trigger auf das Dreipunkt-Menü > Trigger löschen.

Installierbare Trigger in Add-ons

Weitere Informationen zur Verwendung installierbarer Trigger in Add-ons finden Sie unter Add-on-Trigger.