Method: scripts.run

Exécute une fonction dans un projet Apps Script. Le projet de script doit être déployé pour une utilisation avec l'API Apps Script, et l'application appelante doit partager le même projet Cloud Platform.

Cette méthode nécessite une autorisation avec un jeton OAuth 2.0 ayant au moins l'un des champs d'application indiqués dans la section Autorisation. Les projets de script qui ne nécessitent pas d'autorisation ne peuvent pas être exécutés via cette API. Pour trouver les champs d'application appropriés à inclure dans le jeton d'authentification, ouvrez la page Présentation du projet de script et faites défiler la page jusqu'à "Champs d'application OAuth du projet".

L'erreur 403, PERMISSION_DENIED: The caller does not have permission indique que le projet Cloud Platform utilisé pour autoriser la requête n'est pas le même que celui utilisé par le script.

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
scriptId

string

ID du script à exécuter. Recherchez l'ID de script sur la page Paramètres du projet, sous "ID".

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Champs
function

string

Nom de la fonction à exécuter dans le script donné. Le nom n'inclut pas de parenthèses ni de paramètres. Elle peut faire référence à une fonction d'une bibliothèque incluse telle que Library.libFunction1.

parameters[]

value (Value format)

Paramètres à transmettre à la fonction en cours d'exécution. Le type d'objet de chaque paramètre doit correspondre au type attendu dans Apps Script. Les paramètres ne peuvent pas être des types d'objets spécifiques à Apps Script (Document ou Calendar, par exemple). Ils ne peuvent être que des types primitifs tels que string, number, array, object ou boolean. Facultatif.

sessionState

string

Obsolète. À utiliser uniquement avec les modules complémentaires Android. ID représentant la session actuelle de l'utilisateur dans l'application Android pour Google Docs ou Sheets, incluse en tant que données supplémentaires dans l'intent qui lance le module complémentaire. Lorsqu'un module complémentaire Android est exécuté avec un état de session, il obtient les droits d'un script lié, c'est-à-dire qu'il peut accéder à des informations telles que la position actuelle du curseur de l'utilisateur (dans Docs) ou la cellule sélectionnée (dans Sheets). Pour récupérer l'état, appelez Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Facultatif.

devMode

boolean

Si true et que l'utilisateur est propriétaire du script, celui-ci s'exécute sur la dernière version enregistrée plutôt que sur la version déployée pour l'API Apps Script. Facultatif. La valeur par défaut est false.

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

La représentation de l'exécution d'une fonction Apps Script commence par run. La réponse n'arrive pas tant que l'exécution de la fonction n'est pas terminée. La durée d'exécution maximale est indiquée dans le guide des quotas Apps Script.

Une fois l'exécution lancée, elle peut avoir l'un des quatre résultats suivants:

  • Si la fonction de script s'affiche correctement, le champ response contient un objet ExecutionResponse avec la valeur renvoyée par la fonction dans le champ result de l'objet.
  • Si la fonction de script (ou Apps Script elle-même) génère une exception, le champ error contient un objet Status. Le champ details de l'objet Status contient un tableau avec un seul objet ExecutionError qui fournit des informations sur la nature de l'erreur.
  • Si l'exécution n'est pas encore terminée, le champ done est défini sur false, et les champs response et error ne sont pas présents.
  • Si l'appel run lui-même échoue (en raison d'une requête incorrecte ou d'une erreur d'autorisation, par exemple), la méthode renvoie un code de réponse HTTP dans la plage 4XX avec un format différent pour le corps de la réponse. Les bibliothèques clientes convertissent automatiquement une réponse 4XX en classe d'exception.

Représentation JSON
{
  "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.
}
Champs
done

boolean

Ce champ indique si l'exécution du script est terminée. Une exécution terminée présente un champ response renseigné contenant le ExecutionResponse de la fonction qui a été exécutée.

Champ d'union result. Résultat de l'opération, qui peut être une erreur (message error) ou une réponse valide (message response). Si done == false, ni error, ni response ne sont définis. Si done est égal à true, un seul élément error ou response peut être défini. Certains services peuvent ne pas fournir le résultat. result ne peut être qu'un des éléments suivants :
error

object (Status)

Si un appel run aboutit, mais que la fonction de script (ou Apps Script elle-même) génère une exception, ce champ contient un objet Status. Le champ details de l'objet Status contient un tableau avec un seul objet ExecutionError qui fournit des informations sur la nature de l'erreur.

response

object

Si la fonction de script s'affiche correctement, ce champ contient un objet ExecutionResponse avec la valeur renvoyée par la fonction.

Objet contenant des champs d'un type arbitraire. Un champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

  • 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

Pour en savoir plus, consultez la présentation d'OAuth 2.0.

État

Si un appel run aboutit, mais que la fonction de script (ou Apps Script elle-même) génère une exception, le champ error du corps de la réponse contient cet objet Status.

Représentation JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Champs
code

integer

Code d'état. Pour cette API, cette valeur est l'une des suivantes:

  • 10, qui indique une erreur SCRIPT_TIMEOUT,
  • 3, qui indique une erreur INVALID_ARGUMENT ; ou
  • 1, indiquant une exécution CANCELLED.

message

string

Message d'erreur en anglais destiné aux développeurs. Tout message d'erreur destiné à l'utilisateur est localisé et envoyé dans le champ details, ou localisé par le client.

details[]

object

Tableau contenant un seul objet ExecutionError qui fournit des informations sur la nature de l'erreur.

Objet contenant des champs d'un type arbitraire. Un champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.