Class ScriptApp

ScriptApp

Skriptveröffentlichung und Trigger aufrufen und bearbeiten Mit dieser Klasse können Nutzer Skript-Trigger erstellen und die Veröffentlichung des Skripts als Dienst steuern.

Attribute

PropertyTypBeschreibung
AuthModeAuthModeEine Aufzählung, die angibt, welche Kategorien autorisierter Dienste Apps Script über eine ausgelöste Funktion ausführen kann.
AuthorizationStatusAuthorizationStatusEine Aufzählung, die den Autorisierungsstatus eines Skripts angibt.
EventTypeEventTypeEine Aufzählung, die den Typ des ausgelösten Ereignisses angibt.
InstallationSourceInstallationSourceEine Aufzählung, die angibt, wie das Skript für den Nutzer als Add-on installiert wurde.
TriggerSourceTriggerSourceEine Aufzählung, die die Quelle des Ereignisses angibt, das den Trigger auslöst.
WeekDayWeekdayEine Aufzählung, die die Wochentage darstellt.

Methoden

MethodeRückgabetypKurzbeschreibung
deleteTrigger(trigger)voidEntfernt den angegebenen Trigger, sodass er nicht mehr ausgeführt wird.
getAuthorizationInfo(authMode)AuthorizationInfoRuft ein Objekt ab, mit dem ermittelt wird, ob der Nutzer dieses Skript autorisieren muss, um einen oder mehrere Dienste zu verwenden, und die URL für ein Autorisierungsdialogfeld angeben.
getIdentityToken()StringRuft ein OpenID Connect-Identitätstoken für den aktiven Nutzer ab, wenn der Bereich openid gewährt wurde.
getInstallationSource()InstallationSourceGibt einen enum-Wert zurück, der angibt, wie das Skript als Add-on für den aktuellen Nutzer installiert wurde, z. B. ob der Nutzer es selbst über den Chrome Web Store installiert hat oder ob ein Domainadministrator es für alle Nutzer installiert hat.
getOAuthToken()StringRuft das OAuth 2.0-Zugriffstoken für den aktiven Nutzer ab.
getProjectTriggers()Trigger[]Ruft alle installierbaren Trigger ab, die mit dem aktuellen Projekt und dem aktuellen Nutzer verknüpft sind.
getScriptId()StringRuft die eindeutige ID des Skriptprojekts ab.
getService()ServiceRuft ein Objekt ab, über das die Veröffentlichung des Skripts als Webanwendung gesteuert wird.
getUserTriggers(document)Trigger[]Ruft alle installierbaren Trigger dieses Nutzers im angegebenen Dokument ab, nur für dieses Skript oder Add-on.
getUserTriggers(form)Trigger[]Ruft alle installierbaren Trigger dieses Nutzers in der angegebenen Form nur für dieses Skript oder Add-on ab.
getUserTriggers(spreadsheet)Trigger[]Ruft alle installierbaren Trigger dieses Nutzers in der angegebenen Tabelle ab, nur für dieses Skript oder Add-on.
invalidateAuth()voidUngültig macht die Autorisierung, die der aktive Nutzer zum Ausführen des aktuellen Skripts hat.
newStateToken()StateTokenBuilderErstellt einen Builder für ein Statustoken, das in einer Callback-API (z. B. einem OAuth-Ablauf) verwendet werden kann.
newTrigger(functionName)TriggerBuilderStartet den Prozess der Erstellung eines installierbaren Triggers, der beim Auslösen eine bestimmte Funktion aufruft.

Detaillierte Dokumentation

deleteTrigger(trigger)

Entfernt den angegebenen Trigger, sodass er nicht mehr ausgeführt wird.

// Deletes all triggers in the current project.
var triggers = ScriptApp.getProjectTriggers();
for (var i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Parameter

NameTypBeschreibung
triggerTriggerDer zu löschende Trigger.

Autorisierung

Skripts, die diese Methode verwenden, erfordern eine Autorisierung mit einem oder mehreren der folgenden Bereiche:

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

Ruft ein Objekt ab, mit dem ermittelt wird, ob der Nutzer dieses Skript autorisieren muss, um einen oder mehrere Dienste zu verwenden, und die URL für ein Autorisierungsdialogfeld angeben. Wenn das Skript als Add-on mit installierbaren Triggern veröffentlicht wird, kann mit diesen Informationen der Zugriff auf Codeabschnitte gesteuert werden, für die der Nutzer nicht die erforderliche Autorisierung hat. Alternativ kann das Add-on den Nutzer auffordern, die URL für das Autorisierungsdialogfeld zu öffnen, um das Problem zu beheben.

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

Parameter

NameTypBeschreibung
authModeAuthModeDer Autorisierungsmodus, für den Autorisierungsinformationen angefordert werden. In fast allen Fällen sollte der Wert für authMode ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL) sein, da kein anderer Autorisierungsmodus eine Autorisierung durch Nutzer erfordert.

Return

AuthorizationInfo: ein Objekt, das Informationen zum Autorisierungsstatus des Nutzers liefern kann


getIdentityToken()

Ruft ein OpenID Connect-Identitätstoken für den aktiven Nutzer ab, wenn der Bereich openid gewährt wurde. Dieser Bereich ist nicht standardmäßig enthalten. Sie müssen ihn der Manifestdatei als expliziten Bereich hinzufügen, um ihn anzufordern. Geben Sie die Bereiche https://www.googleapis.com/auth/userinfo.email oder https://www.googleapis.com/auth/userinfo.profile an, um zusätzliche Nutzerinformationen im Token zurückzugeben.

Das zurückgegebene ID-Token ist ein codiertes JSON Web Token (JWT) und muss decodiert werden, um Informationen daraus zu extrahieren. Die folgenden Beispiele zeigen, wie das Token decodiert und die Google-Profil-ID des betreffenden Nutzers extrahiert wird.

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
Die vollständige Liste der zurückgegebenen Felder (Anforderungen) finden Sie in der Dokumentation zu OpenID Connect.

Return

String: Das Identitätstoken, falls verfügbar, andernfalls null.


getInstallationSource()

Gibt einen enum-Wert zurück, der angibt, wie das Skript als Add-on für den aktuellen Nutzer installiert wurde, z. B. ob der Nutzer es selbst über den Chrome Web Store installiert hat oder ob ein Domainadministrator es für alle Nutzer installiert hat.

Return

InstallationSource: Die Quelle der Installation.


getOAuthToken()

Ruft das OAuth 2.0-Zugriffstoken für den aktiven Nutzer ab. Wenn die OAuth-Bereiche des Skripts ausreichen, um eine andere Google API zu autorisieren, die normalerweise einen eigenen OAuth-Ablauf erfordert (z. B. Google Picker), können Skripts stattdessen die zweite Autorisierungsaufforderung umgehen, indem sie dieses Token übergeben. Das Token läuft nach einer gewissen Zeit (mindestens einige Minuten) ab. Skripts sollten Autorisierungsfehler verarbeiten und diese Methode aufrufen, um bei Bedarf ein neues Token zu erhalten.

Das von dieser Methode zurückgegebene Token enthält nur Bereiche, die das Skript derzeit benötigt. Zuvor autorisierte Bereiche, die vom Skript nicht mehr verwendet werden, sind nicht im zurückgegebenen Token enthalten. Werden zusätzliche OAuth-Bereiche benötigt, die das Skript selbst erfordert, können diese in der Manifestdatei des Skripts angegeben werden.

Return

String: Eine Stringdarstellung des OAuth 2.0-Tokens.


getProjectTriggers()

Ruft alle installierbaren Trigger ab, die mit dem aktuellen Projekt und dem aktuellen Nutzer verknüpft sind.

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

Return

Trigger[]: Ein Array der Trigger des aktuellen Nutzers, die mit diesem Projekt verknüpft sind.

Autorisierung

Skripts, die diese Methode verwenden, erfordern eine Autorisierung mit einem oder mehreren der folgenden Bereiche:

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

Ruft die eindeutige ID des Skriptprojekts ab. Dies ist die bevorzugte Methode, um die eindeutige Kennzeichnung für das Skriptprojekt abzurufen, im Gegensatz zu getProjectKey(). Diese ID kann überall verwendet werden, wo zuvor der Projektschlüssel bereitgestellt wurde.

Return

String: Die ID des Skriptprojekts.


getService()

Ruft ein Objekt ab, über das die Veröffentlichung des Skripts als Webanwendung gesteuert wird.

// Get the URL of the published web app.
var url = ScriptApp.getService().getUrl();

Return

Service: Ein Objekt, mit dem die Veröffentlichung des Skripts als Webanwendung beobachtet und gesteuert wird.


getUserTriggers(document)

Ruft alle installierbaren Trigger dieses Nutzers im angegebenen Dokument ab, nur für dieses Skript oder Add-on. Diese Methode kann nicht verwendet werden, um die an andere Skripts angehängten Trigger zu sehen.

var doc = DocumentApp.getActiveDocument();
var triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Parameter

NameTypBeschreibung
documentDocumentEine Google Docs-Datei, die installierbare Trigger enthalten kann.

Return

Trigger[]: Ein Array von Triggern, die diesem Nutzer im angegebenen Dokument gehören.

Autorisierung

Skripts, die diese Methode verwenden, erfordern eine Autorisierung mit einem oder mehreren der folgenden Bereiche:

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(form)

Ruft alle installierbaren Trigger dieses Nutzers in der angegebenen Form nur für dieses Skript oder Add-on ab. Diese Methode kann nicht verwendet werden, um die an andere Skripts angehängten Trigger zu sehen.

var form = FormApp.getActiveForm();
var triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Parameter

NameTypBeschreibung
formFormEine Google Formulare-Datei, die installierbare Trigger enthalten kann.

Return

Trigger[]: Ein Array mit Triggern, die diesem Nutzer in der angegebenen Form gehören.

Autorisierung

Skripts, die diese Methode verwenden, erfordern eine Autorisierung mit einem oder mehreren der folgenden Bereiche:

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(spreadsheet)

Ruft alle installierbaren Trigger dieses Nutzers in der angegebenen Tabelle ab, nur für dieses Skript oder Add-on. Diese Methode kann nicht verwendet werden, um die an andere Skripts angehängten Trigger zu sehen.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Parameter

NameTypBeschreibung
spreadsheetSpreadsheetEine Google Tabellen-Datei, die installierbare Trigger enthalten kann.

Return

Trigger[]: Ein Array mit Triggern, die diesem Nutzer in der angegebenen Tabelle gehören.

Autorisierung

Skripts, die diese Methode verwenden, erfordern eine Autorisierung mit einem oder mehreren der folgenden Bereiche:

  • https://www.googleapis.com/auth/script.scriptapp

invalidateAuth()

Ungültig macht die Autorisierung, die der aktive Nutzer zum Ausführen des aktuellen Skripts hat. Wird verwendet, um alle Berechtigungen für das aktuelle Skript zu verwerfen. Dies ist besonders nützlich für Funktionen, die mit einer einmaligen Autorisierung gekennzeichnet sind. Da Autorisierungsfunktionen mit einer einzigen Aktion nur bei der ersten Ausführung aufgerufen werden können, nachdem das Skript die Autorisierung erhalten hat, müssen Sie jede Autorisierung widerrufen, die dem Skript erteilt wurde, damit der Nutzer das Dialogfeld für die Autorisierung wieder sehen kann.

ScriptApp.invalidateAuth();

Löst aus

Error – wenn die Entwertung fehlschlägt


newStateToken()

Erstellt einen Builder für ein Statustoken, das in einer Callback-API (z. B. einem OAuth-Ablauf) verwendet werden kann.

// Generate a callback URL, given the name of a callback function. The script does not need to
// be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var stateToken = ScriptApp.newStateToken()
      .withMethod(callbackFunction)
      .withTimeout(120)
      .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

Bei den meisten OAuth2-Abläufen wird das state-Token direkt an den Autorisierungsendpunkt (nicht als Teil der Callback-URL) übergeben. Der Autorisierungsendpunkt übergibt es dann als Teil der Callback-URL.

Beispiel:

  • Das Skript leitet den Nutzer an die OAuth2-Autorisierungs-URL weiter: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
  • Der Nutzer klickt auf „Autorisieren“ und die OAuth2-Autorisierungsseite leitet ihn zu https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants weiter
  • Die obige Weiterleitung (zurück zu http://script.google.com/...) löst die Browseranfrage an /usercallback aus, wodurch die von StateTokenBuilder.withMethod(method) angegebene Methode aufgerufen wird.

Return

StateTokenBuilder: Ein Objekt, mit dem der Erstellungsprozess des Statustokens fortgesetzt wird.


newTrigger(functionName)

Startet den Prozess der Erstellung eines installierbaren Triggers, der beim Auslösen eine bestimmte Funktion aufruft.

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Parameter

NameTypBeschreibung
functionNameStringDie Funktion, die beim Auslösen des Triggers aufgerufen werden soll. Sie können Funktionen aus enthaltenen Bibliotheken wie Library.libFunction1 verwenden.

Return

TriggerBuilder: Ein Objekt, mit dem der Triggererstellungsprozess fortgesetzt wird.

Autorisierung

Skripts, die diese Methode verwenden, erfordern eine Autorisierung mit einem oder mehreren der folgenden Bereiche:

  • https://www.googleapis.com/auth/script.scriptapp

Verworfene Methoden