Method: scripts.run

Führt eine Funktion in einem Apps Script-Projekt aus. Das Skriptprojekt muss zur Verwendung mit der Apps Script API bereitgestellt werden und die aufrufende Anwendung muss dasselbe Cloud Platform-Projekt verwenden.

Diese Methode erfordert eine Autorisierung mit einem OAuth 2.0-Token, das mindestens einen der im Abschnitt Autorisierung aufgeführten Bereiche umfasst. Skriptprojekte, die keine Autorisierung benötigen, können nicht über diese API ausgeführt werden. Die richtigen Bereiche für das Authentifizierungstoken finden Sie, indem Sie die Seite Übersicht des Skriptprojekts öffnen und nach unten zu „Projekt-OAuth-Bereiche“ scrollen.

Der Fehler 403, PERMISSION_DENIED: The caller does not have permission gibt an, dass das Cloud Platform-Projekt, das zum Autorisieren der Anfrage verwendet wird, nicht mit dem vom Skript verwendeten übereinstimmt.

HTTP-Anfrage

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
scriptId

string

Die Skript-ID des auszuführenden Skripts. Suchen Sie auf der Seite Projekteinstellungen unter „IDs“ nach der Skript-ID.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Felder
function

string

Der Name der Funktion, die im angegebenen Skript ausgeführt werden soll. Der Name enthält keine Klammern oder Parameter. Sie kann auf eine Funktion in einer enthaltenen Bibliothek wie Library.libFunction1 verweisen.
parameters[]

value (Value format)

Die Parameter, die an die auszuführende Funktion übergeben werden sollen. Der Objekttyp für jeden Parameter sollte dem erwarteten Typ in Apps Script entsprechen. Parameter können keine Apps Script-spezifischen Objekttypen (wie Document oder Calendar) sein; sie können nur primitive Typen wie string, number, array, object oder boolean sein. Optional.
sessionState

string

Verworfen. Nur zur Verwendung mit Android-Add-ons. Eine ID, die die aktuelle Sitzung des Nutzers in der Android-App für Google Docs oder Google Tabellen darstellt, als zusätzliche Daten im Intent enthalten, mit dem das Add-on gestartet wird. Wenn ein Android-Add-on mit einem Sitzungsstatus ausgeführt wird, erhält es die Berechtigungen eines gebundenen Skripts, d. h., es kann auf Informationen wie die aktuelle Cursorposition (in Google Docs) oder die ausgewählte Zelle (in Google Tabellen) zugreifen. Rufen Sie Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState") auf, um den Status abzurufen. Optional.
devMode

boolean

Wenn true und der Nutzer Inhaber des Skripts sind, wird das Skript in der zuletzt gespeicherten Version ausgeführt und nicht in der Version, die für die Apps Script API bereitgestellt wurde. Optional; Standardwert ist false.

Antworttext

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

Darstellung einer Ausführung einer Apps Script-Funktion, die mit run gestartet wurde. Die Ausführungsantwort kommt erst an, wenn die Ausführung der Funktion abgeschlossen ist. Die maximale Laufzeit für die Ausführung ist im Apps Script-Kontingent aufgeführt.

Nachdem die Ausführung begonnen hat, kann dies eines von vier Ergebnissen ergeben:

  • Wenn die Skriptfunktion erfolgreich zurückgegeben wird, enthält das Feld response ein ExecutionResponse-Objekt mit dem Rückgabewert der Funktion im Feld result des Objekts.
  • Wenn die Skriptfunktion (oder Apps Script selbst) eine Ausnahme auslöst, enthält das Feld error ein Status-Objekt. Das Feld details des Status-Objekts enthält ein Array mit einem einzelnen ExecutionError-Objekt, das Informationen zur Art des Fehlers enthält.
  • Wenn die Ausführung noch nicht abgeschlossen ist, hat das Feld done den Wert false und es sind weder die Felder response noch error vorhanden.
  • Wenn der run-Aufruf selbst fehlschlägt, z. B. aufgrund einer fehlerhaften Anfrage oder eines Autorisierungsfehlers, gibt die Methode einen HTTP-Antwortcode im 4XX-Bereich mit einem anderen Format für den Antworttext zurück. Clientbibliotheken konvertieren automatisch eine 4XX-Antwort in eine Ausnahmeklasse.

JSON-Darstellung 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Felder
done

boolean

Dieses Feld gibt an, ob die Skriptausführung abgeschlossen ist. Eine abgeschlossene Ausführung enthält ein response-Feld mit der ExecutionResponse aus der ausgeführten Funktion.
Union-Feld result. Das Ergebnis des Vorgangs kann entweder ein error oder eine gültige response sein. Wenn done = false ist, wird weder error noch response festgelegt. Wenn done = true ist, kann genau error oder response festgelegt werden. Einige Dienste liefern möglicherweise nicht das Ergebnis. Für result ist nur einer der folgenden Werte zulässig:
error

object (Status)

Wenn ein run-Aufruf erfolgreich ist, aber die Skriptfunktion (oder das Apps Script selbst) eine Ausnahme auslöst, enthält dieses Feld ein Status-Objekt. Das Feld details des Status-Objekts enthält ein Array mit einem einzelnen ExecutionError-Objekt, das Informationen zur Art des Fehlers enthält.
response

object

Wenn die Skriptfunktion erfolgreich zurückgegeben wird, enthält dieses Feld ein ExecutionResponse-Objekt mit dem Rückgabewert der Funktion.

Ein Objekt mit Feldern eines beliebigen Typs. Ein zusätzliches Feld "@type" enthält einen URI zur Identifizierung des Typs. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" }.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

Weitere Informationen finden Sie in der Übersicht zu OAuth 2.0.

Status

Wenn ein run-Aufruf erfolgreich ist, aber die Skriptfunktion (oder das Apps Script selbst) eine Ausnahme auslöst, enthält das Feld error des Antworttexts dieses Status-Objekt.

JSON-Darstellung 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Felder
code

integer

Der Statuscode. Für diese API kann der Wert entweder:

  • 10, was einen SCRIPT_TIMEOUT-Fehler angibt.
  • 3, was einen INVALID_ARGUMENT-Fehler angibt.
  • 1, was eine CANCELLED-Ausführung angibt.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die auf Englisch ist. Jede Fehlermeldung für den Nutzer wird lokalisiert und im Feld details oder vom Client lokalisiert.
details[]

object

Ein Array, das ein einzelnes ExecutionError-Objekt mit Informationen zur Art des Fehlers enthält.

Ein Objekt mit Feldern eines beliebigen Typs. Ein zusätzliches Feld "@type" enthält einen URI zur Identifizierung des Typs. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" }.