The Google Apps Script API provides a scripts.run method that remotely executes a specified Apps Script function. You can use this method in a calling application to run a function in one of your script projects remotely and receive a response. Show RequirementsYou must satisfy the following requirements before a calling application can use the scripts.run method. You must:
The scripts.run methodThe scripts.run method requires key identifying information in order to run: You can optionally configure your script to execute in development mode. This mode executes with the most recently saved version of the script project rather than the most recently deployed version. Do this by setting the devMode boolean in the request body to true. Only the owner of the script can execute it in development mode. Handling parameter data typesUsing the Apps Script API scripts.run method usually involves sending data to Apps Script as function parameters and getting data back as function return values. The API can only take and return values with basic types: strings, arrays, objects, numbers, and booleans. These are similar to the basic types in JavaScript. More complex Apps Script objects like Document or Sheet cannot be passed into or from the script project by the API. When your calling application is written in a strongly-type language such as Java, it passes in parameters as a list or array of generic objects corresponding to these basic types. In many cases, you can apply simple type conversions automatically. For example, a function that takes a number parameter can be given a Java Double or Integer or Long object as a parameter without extra handling. When the API returns the function response, you often need to cast the returned value to the correct type before it can be used. Here are some Java-based examples:
The example code samples below illustrate ways of interpreting the API response. General procedureThe following describes the general procedure for using the Apps Script API to execute Apps Script functions: Step 1: Set up the common Cloud projectBoth your script and the calling application need to share the same Cloud project. This Cloud project can be an existing project or a new project created for this purpose. Once you have a Cloud project, you must switch your script project to use it. Step 2: Deploy the script as an API executable
Step 3: Configure the calling applicationThe calling application must enable the Apps Script API and establish OAuth crendentials before it can be used. You must have access to the Cloud project to do this.
Step 4: Make the script.run requestOnce the calling application is configured, you can make scripts.run calls. Each API call consists of the following steps:
You can find examples of script.run API calls below. To refresh your access token, you can add the following snippet before your script.run API request: if (credential.getExpiresInSeconds() <= 360) { credential.refreshToken(); }API request examplesThe following examples show how to make an Apps Script API execution request in various languages, calling an Apps Script function to print out a list of folders in the user's root directory. The script ID of the Apps Script project containing the executed function must be specified where indicated with ENTER_YOUR_SCRIPT_ID_HERE. The examples rely on the Google API Client libraries for their respective languages.
The function in this script uses the Drive API. You must enable the Drive API in the project hosting the script. Additionally, calling applications must send OAuth credentials which include the following Drive scope:
The example applications here use the Google client libraries to build credential objects for OAuth using this scope. The Apps Script API has several limitations:
|