La API de Apps Script proporciona un método scripts.run que ejecuta de forma remota una función especificada de Google Apps Script. Puedes usar este método en una aplicación de llamada para ejecutar una función en uno de tus proyectos de secuencias de comandos de forma remota y recibir una respuesta.
Requisitos
Antes de que una aplicación de llamadas pueda usar el método scripts.run, debes hacer lo siguiente:
Implementa el proyecto de secuencia de comandos como un ejecutable de la API. Puedes implementar, anular la implementación y volver a implementar proyectos según sea necesario.
Proporciona un token de OAuth con el alcance adecuado para la ejecución. Este token de OAuth debe abarcar todos los alcances que usa la secuencia de comandos, no solo los que usa la función llamada. Consulta la lista completa de alcances de autorización en la referencia del método.
Asegúrate de que la secuencia de comandos y el cliente OAuth2 de la aplicación que realiza la llamada compartan un proyecto de Google Cloud común. El proyecto de Cloud debe ser un proyecto de Cloud estándar; los proyectos predeterminados creados para proyectos de Apps Script no son suficientes. Puedes usar un proyecto de Cloud estándar nuevo o uno existente.
Habilita la API de Google Apps Script en el proyecto de Cloud.
El método scripts.run
El método scripts.run requiere la siguiente información:
- Es el ID del proyecto de secuencia de comandos.
- El nombre de la función que se ejecutará.
- Lista de parámetros que requiere la función, si corresponde.
De manera opcional, puedes configurar tu secuencia de comandos para que se ejecute en modo de desarrollo.
Este modo se ejecuta con la versión del proyecto de secuencia de comandos guardada más recientemente, en lugar de la versión implementada más recientemente. Para ello, establece el valor booleano devMode en true en el cuerpo de la solicitud. Solo el propietario de la secuencia de comandos puede ejecutarla en modo de desarrollo.
Cómo controlar los tipos de datos de los parámetros
Usar el método scripts.run de la API de Apps Script suele implicar enviar datos a Apps Script como parámetros de funciones y recuperar datos como valores de devolución de funciones. La API solo puede tomar y devolver valores con tipos básicos: cadenas, arrays, objetos, números y valores booleanos. La API no puede pasar objetos de Apps Script más complejos, como Document o Sheet, hacia el proyecto de secuencia de comandos ni desde él.
Cuando tu aplicación de llamada se escribe en un lenguaje con escritura sólida, como Java, pasa parámetros como una lista o un array de objetos genéricos que corresponden a estos tipos básicos. En muchos casos, puedes aplicar conversiones de tipo automáticamente. Por ejemplo, a una función que toma un parámetro numérico se le puede dar un objeto Double, Integer o Long de Java como parámetro sin necesidad de un control adicional.
Cuando la API devuelve la respuesta de la función, a menudo debes transmitir el valor devuelto al tipo correcto antes de que se pueda usar. Estos son algunos ejemplos basados en Java:
- Los números que devuelve la API a una aplicación de Java llegan como objetos
java.math.BigDecimaly es posible que deban convertirse a tiposDoubleoint. Si la función de Apps Script devuelve un array de cadenas, una aplicación Java convierte la respuesta en un objeto
List<String>:List<String> mylist = (List<String>)(op.getResponse().get("result"));Si deseas devolver un array de
Bytes, codifícalo como una cadena en Base64 dentro de la función de Apps Script y devuelve esa cadena:return Utilities.base64Encode(myByteArray); // returns a string.
En los siguientes ejemplos de código, se ilustran formas de interpretar la respuesta de la API.
Procedimiento general
Para usar la API de Apps Script y ejecutar funciones de Apps Script, sigue estos pasos:
Paso 1: Configura el proyecto común de Cloud
Tanto tu secuencia de comandos como la aplicación que la llama deben compartir el mismo proyecto de Cloud. Puede ser un proyecto existente o uno nuevo creado para este propósito. Una vez que tengas un proyecto de Cloud, debes cambiar tu proyecto de secuencia de comandos para usarlo.
Paso 2: Implementa la secuencia de comandos como un ejecutable de la API
- Abre el proyecto de Apps Script con las funciones que deseas usar.
- En la esquina superior derecha, haz clic en Implementar > Nueva implementación.
- En el diálogo que se abre, haz clic en Habilitar los tipos de implementación
> API Executable.
- En el menú desplegable "Quién tiene acceso", selecciona los usuarios que pueden llamar a las funciones de la secuencia de comandos con la API de Apps Script.
- Haz clic en Implementar.
Paso 3: Configura la aplicación de llamadas
La aplicación que realiza la llamada debe habilitar la API de Apps Script y establecer credenciales de OAuth antes de usarla. Para ello, debes tener acceso al proyecto de Cloud.
- Configura el proyecto de Cloud que usan tu aplicación y tu secuencia de comandos de llamada:
- Abre el proyecto de secuencia de comandos y, a la izquierda, haz clic en Descripción general
.
- En Permisos de OAuth del proyecto, registra todos los permisos que requiere la secuencia de comandos.
En el código de la aplicación que realiza la llamada, genera un token de acceso de OAuth de secuencia de comandos para la llamada a la API. Este no es un token que use la API en sí, sino uno que requiere la secuencia de comandos cuando se ejecuta. Se debe compilar con el ID de cliente del proyecto de Cloud y los permisos de la secuencia de comandos que registraste.
Las bibliotecas cliente de Google pueden ayudarte a compilar este token y controlar OAuth para la aplicación, lo que suele permitirte compilar un objeto "credenciales" de nivel superior con los permisos de la secuencia de comandos. Consulta las guías de inicio rápido de la API de Apps Script para ver ejemplos de cómo compilar un objeto de credenciales a partir de una lista de permisos.
Paso 4: Realiza la solicitud de scripts.run
Una vez que se configura la aplicación de llamadas, puedes realizar llamadas de scripts.run:
- Crea una solicitud a la API con el ID de la secuencia de comandos, el nombre de la función y los parámetros obligatorios.
- Realiza la llamada
scripts.runy, luego, incluye el token de OAuth de la secuencia de comandos que compilaste en el encabezado (si usas una solicitudPOSTbásica) o usa un objeto de credenciales que compilaste con los permisos de la secuencia de comandos. - Permite que la secuencia de comandos termine de ejecutarse. Los scripts pueden tardar hasta seis minutos en ejecutarse, por lo que tu aplicación debe permitirlo.
- Cuando finaliza, la función de secuencia de comandos puede devolver un valor, que la API entrega a la aplicación si el valor es de un tipo admitido.
Encontrarás ejemplos de llamadas a la API de scripts.run en la siguiente sección.
Para actualizar tu token de acceso, agrega el siguiente fragmento antes de tu solicitud a la API de scripts.run:
if (credential.getExpiresInSeconds() <= 360) {
credential.refreshToken();
}
Ejemplos de solicitudes a la API
En los siguientes ejemplos, se muestra cómo realizar una solicitud de ejecución de la API de Apps Script en varios idiomas, llamando a una función de Apps Script para imprimir una lista de carpetas en el directorio raíz del usuario. El ID de la secuencia de comandos del proyecto de Apps Script que contiene la función ejecutada se debe especificar donde se indica con ENTER_YOUR_SCRIPT_ID_HERE. Los ejemplos se basan en las bibliotecas cliente de las APIs de Google.
Secuencia de comandos de destino
La función de esta secuencia de comandos usa la API de Drive.
Debes habilitar la API de Drive en el proyecto que aloja la secuencia de comandos.
Además, las aplicaciones que realizan llamadas deben enviar credenciales de OAuth que incluyan el siguiente alcance de Drive:
https://www.googleapis.com/auth/drive
Las aplicaciones de ejemplo que se incluyen aquí usan las bibliotecas cliente de Google para compilar objetos de credenciales para OAuth con este alcance.
/**
* Return the set of folder names contained in the user's root folder as an
* object (with folder IDs as keys).
* @return {Object} A set of folder names keyed by folder ID.
*/
function getFoldersUnderRoot() {
const root = DriveApp.getRootFolder();
const folders = root.getFolders();
const folderSet = {};
while (folders.hasNext()) {
const folder = folders.next();
folderSet[folder.getId()] = folder.getName();
}
return folderSet;
}
Java
/**
* Create a HttpRequestInitializer from the given one, except set
* the HTTP read timeout to be longer than the default (to allow
* called scripts time to execute).
*
* @param {HttpRequestInitializer} requestInitializer the initializer
* to copy and adjust; typically a Credential object.
* @return an initializer with an extended read timeout.
*/
private static HttpRequestInitializer setHttpTimeout(
final HttpRequestInitializer requestInitializer) {
return new HttpRequestInitializer() {
@Override
public void initialize(HttpRequest httpRequest) throws IOException {
requestInitializer.initialize(httpRequest);
// This allows the API to call (and avoid timing out on)
// functions that take up to 6 minutes to complete (the maximum
// allowed script run time), plus a little overhead.
httpRequest.setReadTimeout(380000);
}
};
}
/**
* Build and return an authorized Script client service.
*
* @param {Credential} credential an authorized Credential object
* @return an authorized Script client service
*/
public static Script getScriptService() throws IOException {
Credential credential = authorize();
return new Script.Builder(
HTTP_TRANSPORT, JSON_FACTORY, setHttpTimeout(credential))
.setApplicationName(APPLICATION_NAME)
.build();
}
/**
* Interpret an error response returned by the API and return a String
* summary.
*
* @param {Operation} op the Operation returning an error response
* @return summary of error response, or null if Operation returned no
* error
*/
public static String getScriptError(Operation op) {
if (op.getError() == null) {
return null;
}
// Extract the first (and only) set of error details and cast as a Map.
// The values of this map are the script's 'errorMessage' and
// 'errorType', and an array of stack trace elements (which also need to
// be cast as Maps).
Map<String, Object> detail = op.getError().getDetails().get(0);
List<Map<String, Object>> stacktrace =
(List<Map<String, Object>>) detail.get("scriptStackTraceElements");
java.lang.StringBuilder sb =
new StringBuilder("\nScript error message: ");
sb.append(detail.get("errorMessage"));
sb.append("\nScript error type: ");
sb.append(detail.get("errorType"));
if (stacktrace != null) {
// There may not be a stacktrace if the script didn't start
// executing.
sb.append("\nScript error stacktrace:");
for (Map<String, Object> elem : stacktrace) {
sb.append("\n ");
sb.append(elem.get("function"));
sb.append(":");
sb.append(elem.get("lineNumber"));
}
}
sb.append("\n");
return sb.toString();
}
public static void main(String[] args) throws IOException {
// ID of the script to call. Acquire this from the Apps Script editor,
// under Publish > Deploy as API executable.
String scriptId = "ENTER_YOUR_SCRIPT_ID_HERE";
Script service = getScriptService();
// Create an execution request object.
ExecutionRequest request = new ExecutionRequest()
.setFunction("getFoldersUnderRoot");
try {
// Make the API request.
Operation op =
service.scripts().run(scriptId, request).execute();
// Print results of request.
if (op.getError() != null) {
// The API executed, but the script returned an error.
System.out.println(getScriptError(op));
} else {
// The result provided by the API needs to be cast into
// the correct type, based upon what types the Apps
// Script function returns. Here, the function returns
// an Apps Script Object with String keys and values,
// so must be cast into a Java Map (folderSet).
Map<String, String> folderSet =
(Map<String, String>) (op.getResponse().get("result"));
if (folderSet.size() == 0) {
System.out.println("No folders returned!");
} else {
System.out.println("Folders under your root folder:");
for (String id : folderSet.keySet()) {
System.out.printf(
"\t%s (%s)\n", folderSet.get(id), id);
}
}
}
} catch (GoogleJsonResponseException e) {
// The API encountered a problem before the script was called.
e.printStackTrace(System.out);
}
}
JavaScript
/**
* Load the API and make an API call. Display the results on the screen.
*/
function callScriptFunction() {
const scriptId = '<ENTER_YOUR_SCRIPT_ID_HERE>';
// Call the Apps Script API run method
// 'scriptId' is the URL parameter that states what script to run
// 'resource' describes the run request body (with the function name
// to execute)
try {
gapi.client.script.scripts.run({
'scriptId': scriptId,
'resource': {
'function': 'getFoldersUnderRoot',
},
}).then(function(resp) {
const result = resp.result;
if (result.error && result.error.status) {
// The API encountered a problem before the script
// started executing.
appendPre('Error calling API:');
appendPre(JSON.stringify(result, null, 2));
} else if (result.error) {
// The API executed, but the script returned an error.
// Extract the first (and only) set of error details.
// The values of this object are the script's 'errorMessage' and
// 'errorType', and an array of stack trace elements.
const error = result.error.details[0];
appendPre('Script error message: ' + error.errorMessage);
if (error.scriptStackTraceElements) {
// There may not be a stacktrace if the script didn't start
// executing.
appendPre('Script error stacktrace:');
for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
const trace = error.scriptStackTraceElements[i];
appendPre('\t' + trace.function + ':' + trace.lineNumber);
}
}
} else {
// The structure of the result will depend upon what the Apps
// Script function returns. Here, the function returns an Apps
// Script Object with String keys and values, and so the result
// is treated as a JavaScript object (folderSet).
const folderSet = result.response.result;
if (Object.keys(folderSet).length == 0) {
appendPre('No folders returned!');
} else {
appendPre('Folders under your root folder:');
Object.keys(folderSet).forEach(function(id) {
appendPre('\t' + folderSet[id] + ' (' + id + ')');
});
}
}
});
} catch (err) {
document.getElementById('content').innerText = err.message;
return;
}
}
Node.js
import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';
/**
* Calls an Apps Script function to list the folders in the user's root Drive folder.
*/
async function callAppsScript() {
// The ID of the Apps Script project to call.
const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';
// Authenticate with Google and get an authorized client.
// TODO (developer): Use an appropriate auth mechanism for your app.
const auth = new GoogleAuth({
scopes: 'https://www.googleapis.com/auth/drive',
});
// Create a new Apps Script API client.
const script = google.script({version: 'v1', auth});
const resp = await script.scripts.run({
auth,
requestBody: {
// The name of the function to call in the Apps Script project.
function: 'getFoldersUnderRoot',
},
scriptId,
});
if (resp.data.error?.details?.[0]) {
// The API executed, but the script returned an error.
// Extract the error details.
const error = resp.data.error.details[0];
console.log(`Script error message: ${error.errorMessage}`);
console.log('Script error stacktrace:');
if (error.scriptStackTraceElements) {
// Log the stack trace.
for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
const trace = error.scriptStackTraceElements[i];
console.log('\t%s: %s', trace.function, trace.lineNumber);
}
}
} else {
// The script executed successfully.
// The structure of the response depends on the Apps Script function's return value.
const folderSet = resp.data.response ?? {};
if (Object.keys(folderSet).length === 0) {
console.log('No folders returned!');
} else {
console.log('Folders under your root folder:');
Object.keys(folderSet).forEach((id) => {
console.log('\t%s (%s)', folderSet[id], id);
});
}
}
}
Python
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
def main():
"""Runs the sample."""
# pylint: disable=maybe-no-member
script_id = "1VFBDoJFy6yb9z7-luOwRv3fCmeNOzILPnR4QVmR0bGJ7gQ3QMPpCW-yt"
creds, _ = google.auth.default()
service = build("script", "v1", credentials=creds)
# Create an execution request object.
request = {"function": "getFoldersUnderRoot"}
try:
# Make the API request.
response = service.scripts().run(scriptId=script_id, body=request).execute()
if "error" in response:
# The API executed, but the script returned an error.
# Extract the first (and only) set of error details. The values of
# this object are the script's 'errorMessage' and 'errorType', and
# a list of stack trace elements.
error = response["error"]["details"][0]
print(f"Script error message: {0}.{format(error['errorMessage'])}")
if "scriptStackTraceElements" in error:
# There may not be a stacktrace if the script didn't start
# executing.
print("Script error stacktrace:")
for trace in error["scriptStackTraceElements"]:
print(f"\t{0}: {1}.{format(trace['function'], trace['lineNumber'])}")
else:
# The structure of the result depends upon what the Apps Script
# function returns. Here, the function returns an Apps Script
# Object with String keys and values, and so the result is
# treated as a Python dictionary (folder_set).
folder_set = response["response"].get("result", {})
if not folder_set:
print("No folders returned!")
else:
print("Folders under your root folder:")
for folder_id, folder in folder_set.items():
print(f"\t{0} ({1}).{format(folder, folder_id)}")
except HttpError as error:
# The API encountered a problem before the script started executing.
print(f"An error occurred: {error}")
print(error.content)
if __name__ == "__main__":
main()
Limitaciones
La API de Apps Script tiene las siguientes limitaciones:
Un proyecto de Cloud común El script al que se llama y la aplicación que llama deben compartir un proyecto de Cloud. El proyecto de Cloud debe ser un proyecto de Cloud estándar; los proyectos predeterminados creados para proyectos de Apps Script no son suficientes.
Tipos de parámetros y de datos que se muestran básicos La API no puede pasar ni devolver objetos específicos de Apps Script (como Documentos, Blobs, Calendarios, Archivos de Drive, etcétera) a la aplicación. Solo se pueden pasar y devolver tipos básicos, como cadenas, arrays, objetos, números y booleanos.
Permisos de OAuth La API solo puede ejecutar secuencias de comandos que tengan al menos un permiso obligatorio. Esto significa que no puedes usar la API para llamar a una secuencia de comandos que no requiera la autorización de uno o más servicios.
Sin activadores. La API no puede crear activadores de Apps Script.