Method: scripts.run

Exécute une fonction dans un projet Apps Script. Le projet de script doit être déployé pour être utilisé 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 qui inclut au moins l'un des champs d'application répertorié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 corrects à inclure dans le jeton d'authentification, ouvrez la page Présentation du projet de script, puis faites défiler la page vers le bas 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 ne contient pas de parenthèses ni de paramètres. Elle peut référencer 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). il ne peut s'agir que de types primitifs tels que string, number, array, object ou boolean. Facultatif.
sessionState

string

Obsolète. À utiliser uniquement avec les modules complémentaires Android. ID qui représente la session actuelle de l'utilisateur dans l'application Android pour Google Docs ou Sheets, inclus 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é. Autrement dit, 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 la valeur est true et que l'utilisateur est propriétaire du script, celui-ci s'exécute sur la dernière version enregistrée, et non sur celle déployée pour être utilisée avec 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 :

Représentation de l'exécution d'une fonction Apps Script démarrée par run. La réponse n'arrive pas tant que l'exécution de la fonction n'est pas terminée. L'environnement d'exécution maximal est indiqué dans le guide des quotas Apps Script.

Une fois que l'exécution a commencé, elle peut avoir l'un des quatre résultats suivants:

  • Si le résultat de la fonction de script aboutit, 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 lui-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 false, et ni les champs response ni error ne sont présents.
  • Si l'appel run lui-même échoue (par exemple, en raison d'une requête incorrecte ou d'une erreur d'autorisation), la méthode renvoie un code de réponse HTTP de la plage 4XX avec un format de corps de réponse différent. 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. Lorsqu'une exécution est terminée, le champ response est renseigné contenant le ExecutionResponse de la fonction 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 == true, une seule des options error ou response peut être définie. 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 lui-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 aboutit, 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 lui-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 soit:

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

string

Message d'erreur destiné au développeur, en anglais. Tout message d'erreur visible par 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" }.