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 listé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 bons champs d'application à 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/{deploymentId}:run

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
deploymentId

string

ID de déploiement du déploiement de l'exécutable d'API. Recherchez l'ID de déploiement sous Déployer > Gérer les déploiements dans l'éditeur de script.

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 dans 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 (comme Document ou Calendar). 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 en cours 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 bénéficie des privilèges 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 avec la version enregistrée la plus récente, et non avec la version 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 avec run. La réponse d'exécution n'arrive qu'une fois l'exécution de la fonction terminée. La durée d'exécution maximale est indiquée dans le guide des quotas Apps Script.

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

  • Si la fonction de script est exécutée avec succès, le champ response contient un objet ExecutionResponse avec la valeur renvoyée de 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 défini sur false et les champs response et error ne sont pas présents.
  • Si l'appel run lui-même échoue (par exemple, en raison d'une requête mal formée ou d'une erreur d'autorisation), 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 comporte 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 == 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 est exécutée avec succès, 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 peut être :

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

string

Message d'erreur destiné aux développeurs, qui doit être en anglais. Tout message d'erreur destiné aux utilisateurs 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" }.