Class ScriptApp

ScriptApp

Auf Script-Veröffentlichungen und Trigger zugreifen und sie bearbeiten. Mit dieser Klasse können Nutzer Script-Trigger erstellen und die Veröffentlichung des Scripts als Dienst steuern.

Attribute

AttributTypBeschreibung
AuthModeAuthModeEine Aufzählung, die angibt, welche Kategorien von autorisierten Diensten in Apps Script über eine ausgelöste Funktion ausgeführt werden können.
AuthorizationStatusAuthorizationStatusEine Aufzählung, die den Autorisierungsstatus eines Scripts angibt.
EventTypeEventTypeEine Aufzählung, die den Typ des ausgelösten Ereignisses angibt.
InstallationSourceInstallationSourceEine Aufzählung, die angibt, wie das Script 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, sodass er nicht mehr ausgeführt wird.
getAuthorizationInfo(authMode)AuthorizationInfoHiermit wird ein Objekt abgerufen, mit dem ermittelt wird, ob der Nutzer dieses Script für die Verwendung 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 effektiven Nutzer ab, wenn der Umfang openid gewährt wurde.
getInstallationSource()InstallationSourceGibt einen Enum-Wert zurück, der angibt, wie das Script 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 effektiven Nutzer ab.
getProjectTriggers()Trigger[]Alle installierbaren Trigger abrufen, die mit dem aktuellen Projekt und dem aktuellen Nutzer verknüpft sind
getScriptId()StringRuft die eindeutige ID des Script-Projekts ab.
getService()ServiceHiermit wird ein Objekt abgerufen, mit dem die Veröffentlichung des Scripts als Webanwendung gesteuert wird.
getUserTriggers(document)Trigger[]Hiermit werden alle installierbaren Trigger abgerufen, die diesem Nutzer im angegebenen Dokument gehören, und zwar nur für dieses Script oder Add-on.
getUserTriggers(form)Trigger[]Hiermit werden alle installierbaren Trigger abgerufen, die diesem Nutzer im angegebenen Formular gehören, und zwar nur für dieses Script oder Add-on.
getUserTriggers(spreadsheet)Trigger[]Hiermit werden alle installierbaren Trigger abgerufen, die diesem Nutzer in der angegebenen Tabelle gehören, und zwar nur für dieses Script oder Add-on.
invalidateAuth()voidMacht die Autorisierung ungültig, die der effektive Nutzer zum Ausführen des aktuellen Scripts hat.
newStateToken()StateTokenBuilderErstellt einen Builder für ein Statustoken, das in einer Callback-API (z. B. einem OAuth-Ablauf) verwendet werden kann.
newTrigger(functionName)TriggerBuilderHiermit wird der Prozess zum Erstellen eines installierbaren Triggers gestartet, der beim Auslösen eine bestimmte Funktion aufruft.

Detaillierte Dokumentation

deleteTrigger(trigger)

Der angegebene Trigger wird entfernt, sodass er nicht mehr ausgeführt wird. 

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

Parameter

NameTypBeschreibung
triggerTriggerDer zu löschende Trigger.

Autorisierung

Scripts, die diese Methode verwenden, erfordern eine Autorisierung für einen oder mehrere der folgenden Bereiche:

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

getAuthorizationInfo(authMode)

Hiermit wird ein Objekt abgerufen, mit dem ermittelt wird, ob der Nutzer dieses Script für die Verwendung eines oder mehrerer Dienste autorisieren muss, und um die URL für ein Autorisierungsdialogfeld anzugeben. Wenn das Script als Add-on veröffentlicht wird, das installierbare Trigger verwendet, können diese Informationen verwendet werden, um den Zugriff auf Codeabschnitte zu steuern, 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 bei keinem anderen Autorisierungsmodus Nutzer die Autorisierung erteilen müssen.

Rückflug

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

getIdentityToken()

Ruft ein OpenID Connect-Identitätstoken für den effektiven Nutzer ab, wenn der Umfang openid gewährt wurde. Dieser Bereich ist nicht standardmäßig enthalten. Sie müssen ihn als expliziten Bereich in die Manifestdatei einfügen, um ihn anzufordern. Fügen Sie die Bereiche https://www.googleapis.com/auth/userinfo.email oder https://www.googleapis.com/auth/userinfo.profile hinzu, 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. In den folgenden Beispielen wird gezeigt, wie das Token decodiert und die Google-Profil-ID des tatsächlichen Nutzers extrahiert wird. 

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);
 Eine vollständige Liste der zurückgegebenen Felder (Anspruche) findest du in der OpenID Connect-Dokumentation.

Rückflug

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

getInstallationSource()

Gibt einen Enum-Wert zurück, der angibt, wie das Script 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.

Rückflug

InstallationSource – Die Installationsquelle.

getOAuthToken()

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

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

Rückflug

String: Eine Stringdarstellung des OAuth 2.0-Tokens.

getProjectTriggers()

Alle installierbaren Trigger abrufen, die mit dem aktuellen Projekt und dem aktuellen Nutzer verknüpft sind 

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

Rückflug

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

Autorisierung

Scripts, die diese Methode verwenden, erfordern eine Autorisierung für einen oder mehrere der folgenden Bereiche:

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

getScriptId()

Ruft die eindeutige ID des Script-Projekts ab. Dies ist die bevorzugte Methode, um die eindeutige Kennung für das Script-Projekt abzurufen, im Gegensatz zu getProjectKey(). Diese ID kann an allen Stellen verwendet werden, an denen zuvor der Projektschlüssel angegeben wurde.

Rückflug

String: Die ID des Scriptprojekts.

getService()

Hiermit wird ein Objekt abgerufen, mit dem die Veröffentlichung des Scripts als Webanwendung gesteuert wird. 

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

Rückflug

Service: Ein Objekt, mit dem das Veröffentlichen des Scripts als Webanwendung beobachtet und gesteuert wird.

getUserTriggers(document)

Hiermit werden alle installierbaren Trigger abgerufen, die diesem Nutzer im angegebenen Dokument gehören, und zwar nur für dieses Script oder Add-on. Mit dieser Methode können Sie nicht die Trigger sehen, die mit anderen Scripts verknüpft sind. 

const doc = DocumentApp.getActiveDocument();
const 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.

Rückflug

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

Autorisierung

Scripts, die diese Methode verwenden, erfordern eine Autorisierung für einen oder mehrere der folgenden Bereiche:

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

getUserTriggers(form)

Hiermit werden alle installierbaren Trigger abgerufen, die diesem Nutzer im angegebenen Formular gehören, und zwar nur für dieses Script oder Add-on. Mit dieser Methode können Sie nicht die Trigger sehen, die mit anderen Scripts verknüpft sind. 

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

Parameter

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

Rückflug

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

Autorisierung

Scripts, die diese Methode verwenden, erfordern eine Autorisierung für einen oder mehrere der folgenden Bereiche:

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

getUserTriggers(spreadsheet)

Hiermit werden alle installierbaren Trigger abgerufen, die diesem Nutzer in der angegebenen Tabelle gehören, und zwar nur für dieses Script oder Add-on. Mit dieser Methode können Sie nicht die Trigger sehen, die mit anderen Scripts verknüpft sind. 

const ss = SpreadsheetApp.getActiveSpreadsheet();
const 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.

Rückflug

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

Autorisierung

Scripts, die diese Methode verwenden, erfordern eine Autorisierung für einen oder mehrere der folgenden Bereiche:

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

invalidateAuth()

Macht die Autorisierung ungültig, die der effektive Nutzer zum Ausführen des aktuellen Scripts hat. Damit werden alle Berechtigungen für das aktuelle Script ungültig gemacht. Das ist besonders nützlich für Funktionen, die als einmalige Autorisierung getaggt sind. Da Funktionen für die einmalige Autorisierung nur beim ersten Ausführen nach der Autorisierung des Scripts aufgerufen werden können, müssen Sie alle Autorisierungen für das Script widerrufen, wenn Sie eine Aktion danach ausführen möchten, damit der Nutzer das Autorisierungsdialogfeld noch einmal sehen kann. 

ScriptApp.invalidateAuth();

Löst

Error – wenn die Aufhebung 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.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const stateToken = ScriptApp.newStateToken()
                         .withMethod(callbackFunction)
                         .withTimeout(120)
                         .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

Bei den meisten OAuth2-Abläufen wird das state-Token direkt (nicht als Teil der Rückruf-URL) an den Autorisierungsendpunkt übergeben, der es dann als Teil der Rückruf-URL weitergibt.

Beispiel:

  • Das Script leitet den Nutzer zur 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 wird von der OAuth2-Autorisierungsseite zurück zu https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants weitergeleitet.
  • Die obige Weiterleitung (zurück zu http://script.google.com/...) führt dazu, dass der Browser eine Anfrage an /usercallback sendet, wodurch die von StateTokenBuilder.withMethod(method) angegebene Methode aufgerufen wird.

Rückflug

StateTokenBuilder: Ein Objekt, mit dem der Prozess zum Erstellen des Statustokens fortgesetzt wird.

newTrigger(functionName)

Hiermit wird der Prozess zum Erstellen eines installierbaren Triggers gestartet, 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 aufgerufen werden soll, wenn der Trigger ausgelöst wird. Sie können Funktionen aus den enthaltenen Bibliotheken wie Library.libFunction1 verwenden.

Rückflug

TriggerBuilder: Ein Objekt, mit dem Sie den Trigger erstellen können.

Autorisierung

Scripts, die diese Methode verwenden, erfordern eine Autorisierung für einen oder mehrere der folgenden Bereiche:

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

Eingestellte Methoden