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.

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. Scriptprojekte, für die keine Autorisierung erforderlich ist, können nicht über diese API ausgeführt werden. Wenn Sie die richtigen Bereiche für das Authentifizierungstoken ermitteln möchten, öffnen Sie die Seite Übersicht 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 Cloud Platform-Projekt, das zum Autorisieren der Anfrage verwendet wurde, nicht mit dem Projekt übereinstimmt, das vom Skript verwendet wird.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
deploymentId

string

Die Bereitstellungs-ID für die Bereitstellung der ausführbaren API. Bereitstellungs-ID finden Sie im Skripteditor unter Bereitstellen > Bereitstellungen verwalten.

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 Script 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, sondern nur primitive Typen wie string, number, array, object oder boolean. Optional.
sessionState

string

Eingestellt. Nur zur Verwendung mit Android-Add-ons. Eine ID, die die aktuelle Sitzung des Nutzers in der Android-App für Google Docs oder Sheets 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 bedeutet, dass es auf Informationen wie die aktuelle Cursorposition des Nutzers (in Docs) oder die ausgewählte Zelle (in Sheets) zugreifen kann. 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 ist, wird das Skript in der zuletzt gespeicherten Version ausgeführt und nicht in 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:

Eine Darstellung der Ausführung einer Apps Script-Funktion, die mit run gestartet wurde. Die Ausführungsantwort geht erst ein, wenn die Funktion ausgeführt wurde. Die maximale Ausführungszeit ist im Apps Script-Leitfaden zu Kontingenten aufgeführt.

Nachdem die Ausführung gestartet wurde, kann sie eines von vier Ergebnissen haben:

  • 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, ist das Feld done auf false gesetzt und weder das Feld response noch das Feld error sind 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 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

Dieses Feld gibt an, ob die Skriptausführung abgeschlossen ist. Bei einer abgeschlossenen Ausführung ist das Feld response ausgefüllt und enthält die ExecutionResponse 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, kann entweder error oder response festgelegt werden. Einige Dienste stellen das Ergebnis möglicherweise nicht bereit. 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 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, 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 OAuth 2.0-Übersicht.

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 einen SCRIPT_TIMEOUT-Fehler hinweist,
  • 3, was auf einen INVALID_ARGUMENT-Fehler hinweist, oder
  • 1, was auf eine CANCELLED-Ausführung hinweist.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig ist. Jede Fehlermeldung an den Nutzer wird lokalisiert und im Feld details gesendet. Sie kann auch clientseitig lokalisiert werden.
details[]

object

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

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