Method: scripts.run

Führt eine Funktion in einem Apps Script-Projekt aus. Das Skriptprojekt muss für die 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 enthält. Skriptprojekte, die keine Autorisierung erfordern, können nicht über diese API ausgeführt werden. Um die richtigen Bereiche für das Authentifizierungstoken zu finden, öffnen Sie die Übersichtsseite des Skriptprojekts und scrollen Sie nach unten zu „OAuth-Bereiche des Projekts“.

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

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 Script-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 gegebenen 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)

Parameter, die an die ausgeführte 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 für Android-Add-ons. Eine ID, die die aktuelle Sitzung des Nutzers in der Android-App für Google Docs oder Google Tabellen darstellt. Diese ID ist 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 des Nutzers (in 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 es mit der zuletzt gespeicherten Version ausgeführt und nicht mit der Version, die für die Verwendung mit der Apps Script API bereitgestellt wurde. Optional; der 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 Ausführungslaufzeit finden Sie im englischsprachigen Leitfaden zu Apps Script-Kontingenten.

Nachdem die Ausführung gestartet wurde, kann es zu einem der folgenden vier Ergebnisse kommen:

  • 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 liefert.
  • Wenn die Ausführung noch nicht abgeschlossen ist, hat das Feld done den Wert false und die Felder response oder error sind nicht vorhanden.
  • Wenn der run-Aufruf fehlschlägt (z. B. aufgrund einer falsch formatierten Anfrage oder eines Autorisierungsfehlers), gibt die Methode einen HTTP-Antwortcode im 4XX-Bereich mit einem anderen Format für den Antworttext zurück. Clientbibliotheken wandeln eine 4XX-Antwort automatisch in eine Ausnahmeklasse um.

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

In diesem Feld wird angegeben, ob die Skriptausführung abgeschlossen ist. Bei einer abgeschlossenen Ausführung ist das Feld response mit der ExecutionResponse aus der ausgeführten Funktion ausgefüllt.

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 entweder error oder response festgelegt werden. Bei einigen Diensten ist das Ergebnis möglicherweise nicht verfügbar. Für result ist nur einer der folgenden Werte zulässig:
error

object (Status)

Wenn ein run-Aufruf erfolgreich ist, aber die Skriptfunktion (oder 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 liefert.

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 über OAuth 2.0.

Status

Wenn ein run-Aufruf erfolgreich ist, aber die Skriptfunktion (oder 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 ist dieser Wert entweder:

  • 10, was auf einen SCRIPT_TIMEOUT-Fehler hinweist,
  • 3, was auf den Fehler INVALID_ARGUMENT hinweist, oder
  • 1, was eine CANCELLED-Ausführung angibt.

message

string

Eine an den Entwickler gerichtete Fehlermeldung, die auf Englisch ist. Jede an den Nutzer gerichtete Fehlermeldung wird lokalisiert und im Feld details gesendet oder vom Client lokalisiert.

details[]

object

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

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" }.