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 sich im selben Cloud Platform-Projekt befinden.

Für diese Methode ist eine Autorisierung mit einem OAuth 2.0-Token erforderlich, 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 Seite Übersicht des Skriptprojekts und scrollen Sie nach unten zu „Projekt-OAuth-Bereiche“.

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 Projekt identisch ist, das vom Skript verwendet wird.

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 die Skript-ID auf der Seite Projekteinstellungen unter „IDs“.

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)

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 sein, z. B. Document oder Calendar. Es können nur primitive Typen wie string, number, array, object oder boolean sein. Optional.
sessionState

string

Eingestellt. Nur für die 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. Sie 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, das heißt, es kann auf Informationen wie die aktuelle Cursorposition (in Docs) oder die ausgewählte Zelle (in 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 Eigentümer des Skripts ist, wird das Skript mit der zuletzt gespeicherten Version ausgeführt und nicht in der für die Verwendung mit der Apps Script API bereitgestellten Version. 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 Leitfaden zu Apps Script-Kontingenten.

Nach dem Start der Ausführung kann eines von vier Ergebnissen auftreten:

  • 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, enthält das Feld done den Wert false und weder das Feld response noch das Feld error sind vorhanden.
  • Wenn der run-Aufruf selbst fehlschlägt, beispielsweise 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 wurde. Bei einer abgeschlossenen Ausführung ist das Feld response mit der ausgeführten Funktion ExecutionResponse von gefü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, kann entweder error oder response festgelegt werden. Einige Dienste liefern das Ergebnis möglicherweise nicht. Für result ist nur einer der folgenden Werte zulässig:
error

object (Status)

Wenn ein run-Aufruf erfolgreich ist, die Skriptfunktion (oder Apps Script selbst) jedoch 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, das Felder eines beliebigen Typs enthält. 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, die Skriptfunktion (oder Apps Script selbst) jedoch 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 den Fehler SCRIPT_TIMEOUT hinweist,
  • 3, was auf den Fehler INVALID_ARGUMENT hinweist, oder
  • 1, was auf eine CANCELLED-Ausführung hinweist.
message

string

Eine an den Entwickler gerichtete Fehlermeldung in englischer Sprache. 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 über die Art des Fehlers liefert.

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