Class ScriptApp

Skript-App

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 von autorisierten Diensten 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 als Add-on für den Nutzer 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)voidDer angegebene Trigger wird entfernt, damit er nicht mehr ausgeführt wird.
getAuthorizationInfo(authMode)AuthorizationInfoRuft ein Objekt ab, mit dem ermittelt wird, ob der Nutzer dieses Skript für die Nutzung eines oder mehrerer Dienste autorisieren muss, und um die URL für ein Autorisierungsdialogfeld anzugeben.
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 es von einem Domainadministrator für alle Nutzer installiert wurde).
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, mit dem die Veröffentlichung des Skripts als Webanwendung gesteuert wird.
getUserTriggers(document)Trigger[]Ruft alle installierbaren Trigger ab, die diesem Nutzer im jeweiligen Dokument, nur für dieses Skript oder Add-on gehören.
getUserTriggers(form)Trigger[]Ruft alle installierbaren Trigger dieses Nutzers im angegebenen Formular für dieses Skript oder Add-on ab.
getUserTriggers(spreadsheet)Trigger[]Ruft alle installierbaren Trigger dieses Nutzers in der angegebenen Tabelle für dieses Skript oder Add-on ab.
invalidateAuth()voidUngültig, dass der aktive Nutzer das aktuelle Skript ausführen muss.
newStateToken()StateTokenBuilderErstellt einen Builder für ein Statustoken, das in einer Callback API (z. B. einem OAuth-Ablauf) verwendet werden kann.
newTrigger(functionName)TriggerBuilderbeginnt mit dem Erstellen eines installierbaren Triggers, der beim Auslösen eine bestimmte Funktion aufruft.

Detaillierte Dokumentation

deleteTrigger(trigger)

Der angegebene Trigger wird entfernt, damit 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

Für Skripts, die diese Methode verwenden, ist eine Autorisierung in mindestens einem der folgenden Bereiche erforderlich:

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

getAuthorizationInfo(authMode)

Ruft ein Objekt ab, mit dem ermittelt wird, ob der Nutzer dieses Skript für die Nutzung eines oder mehrerer Dienste autorisieren muss, und um die URL für ein Autorisierungsdialogfeld anzugeben. Wenn das Skript als Add-on mit installierbaren Triggern veröffentlicht wird, können diese Informationen verwendet werden, um den Zugriff auf Codebereiche zu steuern, für die der Nutzer nicht die erforderliche Autorisierung hat. Alternativ kann der Nutzer vom Add-on dazu aufgefordert werden, 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 erfordert, dass Nutzer eine Autorisierung erteilen.

Zurücksenden

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 standardmäßig nicht enthalten. Sie müssen ihn in der Manifestdatei als expliziten Bereich hinzufügen, um ihn anzufordern. Fügen Sie die Bereiche https://www.googleapis.com/auth/userinfo.email oder https://www.googleapis.com/auth/userinfo.profile ein, 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 gültige Google-Profil-ID des 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);
Eine vollständige Liste der zurückgegebenen Felder (Ansprüche) findest du in der Dokumentation zu OpenID Connect.

Zurücksenden

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 es von einem Domainadministrator für alle Nutzer installiert wurde).

Zurücksenden

InstallationSource: Die Quelle der Installation.

getOAuthToken()

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

Das von dieser Methode zurückgegebene Token enthält nur Bereiche, die das Skript derzeit benötigt. Bereiche, die zuvor autorisiert waren, aber vom Skript nicht mehr verwendet werden, sind nicht im zurückgegebenen Token enthalten. Wenn weitere OAuth-Bereiche erforderlich sind, die über das Skript selbst hinausgehen, können sie in der Manifestdatei des Skripts angegeben werden.

Zurücksenden

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.');

Zurücksenden

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

Autorisierung

Für Skripts, die diese Methode verwenden, ist eine Autorisierung in mindestens einem der folgenden Bereiche erforderlich:

  • 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 anstelle von getProjectKey() zu erhalten. Diese ID kann an allen Stellen verwendet werden, an denen zuvor der Projektschlüssel angegeben wurde.

Zurücksenden

String: Die ID des Skriptprojekts.

getService()

Ruft ein Objekt ab, mit dem die Veröffentlichung des Skripts als Webanwendung gesteuert wird. 

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

Zurücksenden

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

getUserTriggers(document)

Ruft alle installierbaren Trigger ab, die diesem Nutzer im jeweiligen Dokument, nur für dieses Skript oder Add-on gehören. Diese Methode kann nicht verwendet werden, um die Trigger aufzurufen, die an andere Skripts angehängt sind. 

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 möglicherweise installierbare Trigger enthält.

Zurücksenden

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

Autorisierung

Für Skripts, die diese Methode verwenden, ist eine Autorisierung in mindestens einem der folgenden Bereiche erforderlich:

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

getUserTriggers(form)

Ruft alle installierbaren Trigger dieses Nutzers im angegebenen Formular für dieses Skript oder Add-on ab. Diese Methode kann nicht verwendet werden, um die Trigger aufzurufen, die an andere Skripts angehängt sind. 

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.

Zurücksenden

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

Autorisierung

Für Skripts, die diese Methode verwenden, ist eine Autorisierung in mindestens einem der folgenden Bereiche erforderlich:

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

getUserTriggers(spreadsheet)

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

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.

Zurücksenden

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

Autorisierung

Für Skripts, die diese Methode verwenden, ist eine Autorisierung in mindestens einem der folgenden Bereiche erforderlich:

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

invalidateAuth()

Ungültig, dass der aktive Nutzer das aktuelle Skript ausführen muss. Wird verwendet, um Berechtigungen für das aktuelle Skript zu entwerten. Dies ist besonders nützlich für Funktionen, die als One-Shot-Autorisierung gekennzeichnet sind. Da One-Shot-Autorisierungsfunktionen nur bei der ersten Ausführung nach der Autorisierung des Skripts aufgerufen werden können, müssen Sie, wenn Sie später eine Aktion ausführen möchten, die Autorisierung des Skripts widerrufen, damit der Nutzer das Dialogfeld für die Autorisierung wieder sehen kann. 

ScriptApp.invalidateAuth();

Throws

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;
}

In den meisten OAuth2-Abläufen wird das state-Token direkt an den Autorisierungsendpunkt übergeben und nicht als Teil der Callback-URL. 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 den Nutzer zurück zu https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • 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.

Zurücksenden

StateTokenBuilder: Ein Objekt zum Fortsetzen der Erstellung des Statustokens.

newTrigger(functionName)

beginnt mit dem Erstellen 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 aufzurufende Funktion, wenn der Trigger ausgelöst wird. Sie können Funktionen aus enthaltenen Bibliotheken wie Library.libFunction1 verwenden.

Zurücksenden

TriggerBuilder: Ein Objekt zum Fortsetzen der Triggererstellung.

Autorisierung

Für Skripts, die diese Methode verwenden, ist eine Autorisierung in mindestens einem der folgenden Bereiche erforderlich:

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

Eingestellte Methoden