La API de Google Apps Script ofrece
Método scripts.run
que ejecuta de forma remota una función específica de Apps Script. Puedes usar este método
en una aplicación de llamada para ejecutar una función en uno de tus proyectos de secuencia de comandos
de forma remota y recibir una respuesta.
Requisitos
Debes cumplir con los siguientes requisitos antes de que una aplicación que realiza la llamada pueda usar
el scripts.run
. Debes hacer lo siguiente:
Implementa el proyecto de secuencia de comandos como un ejecutable de API. Puedes implementar, anular la implementación y volver a implementar proyectos según sea necesario.
Proporcionar un token de OAuth con el alcance adecuado para la ejecución Este token de OAuth debe abarcar todos los alcances. que se usan en la secuencia de comandos, no solo los que usa la función llamada. Consulta la lista completa de los permisos de autorización en la referencia del método.
Asegúrate de que la secuencia de comandos y el protocolo OAuth2 de la aplicación que realiza la llamada cliente comparten un proyecto común de Google Cloud. El proyecto de Cloud debe ser un proyecto estándar de Cloud. los proyectos predeterminados que se crearon para los 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
La scripts.run
método requiere información de identificación clave para ejecutarse:
- El ID del proyecto de secuencia de comandos.
- El nombre de la función ejecutar.
- La lista de parámetros que la función requiere (si corresponde).
Si lo deseas, puedes configurar tu secuencia de comandos para que se ejecute en modo de desarrollo.
Este modo se ejecuta con la versión guardada más reciente del proyecto de secuencia de comandos.
en lugar de la versión implementada más recientemente. Para ello, configura
Booleano devMode en el
cuerpo de la solicitud
a true. Solo el propietario de la secuencia de comandos puede ejecutarla en modo de desarrollo.
Maneja tipos de datos de parámetros
Usa la API de Apps Script
Método scripts.run
suele implicar el envío de datos a Apps Script como parámetros de función y
recuperar datos como valores devueltos de funciones. La API solo puede tomar y devolver
valores con tipos básicos: cadenas, arrays, objetos, números y booleanos. Estos
son similares a los básicos de JavaScript. Más complejo
Objetos de Apps Script, como Document
o la Hoja no se puede pasar a
o desde el proyecto
de secuencia de comandos de la API.
Cuando tu aplicación de llamadas está escrita en un lenguaje de tipo fuerte, como
En Java, pasa parámetros como una lista o un array de objetos genéricos.
correspondientes a estos tipos básicos. En muchos casos, puedes aplicar reglas
tipo de conversiones automáticamente. Por ejemplo, una función que toma un número
puede tener un objeto Double, Integer o Long de Java como una
sin control adicional.
Cuando la API devuelve la respuesta de la función, a menudo necesitas transmitir el el valor devuelto al tipo correcto antes de que se pueda usar. Estos son algunos ejemplos Ejemplos basados en Java:
- Los números que muestra la API a una aplicación de Java llegan como
java.math.BigDecimaly es posible que deba convertirse aDoublesoint, según sea necesario. Si la función Apps Script devuelve un array de cadenas, una aplicación de Java convierte la respuesta en un objeto
List<String>:List<String> mylist = (List<String>)(op.getResponse().get("result"));Si quieres mostrar un array de
Bytes, puede resultarte conveniente. para codificar el array como una cadena base64 dentro de la función Apps Script y En cambio, devolverá esa String:return Utilities.base64Encode(myByteArray); // returns a String.
Las muestras de código de ejemplo que aparecen a continuación ilustran maneras de para interpretar las respuestas de la API.
Procedimiento general
A continuación, se describe el procedimiento general para usar la API de Apps Script para ejecutar funciones de Apps Script:
Paso 1: Configura el proyecto común de Cloud
Tanto la secuencia de comandos como la aplicación que realiza la llamada deben compartir la misma Cloud. Este proyecto de Cloud puede ser un proyecto existente o un nuevo proyecto creado con este propósito. Cuando 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 tipos de implementación
.
> API ejecutable. - En la sección “Usuarios con acceso”, en el menú desplegable, 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 que realiza la llamada
La aplicación que realiza la llamada debe habilitar la API de Apps Script y establecer OAuth crendenciales antes de poder usarlos. Debes tener acceso al proyecto de Cloud para hacerlo.
- Configura el proyecto de Cloud que usan tu aplicación y secuencia de comandos de llamada. Para hacerlo, sigue estos pasos:
- 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 alcances a los que de tu secuencia de comandos.
En el código de la aplicación que realiza la llamada, genera un token de acceso OAuth para la secuencia de comandos. para la llamada a la API. Este no es un token que la API utilice en sí, sino más bien uno de la secuencia de comandos. Se debe crear usando el El ID de cliente del proyecto de Cloud y los permisos de la secuencia de comandos que registraste.
Las bibliotecas cliente de Google pueden asistir en la creación de este token y el manejo de OAuth para la aplicación, lo que generalmente permite crear "credenciales" de nivel más alto objeto con los permisos de secuencias de comandos. Consulta la Guías de inicio rápido de la API de Apps Script para ver ejemplos de crear un objeto de credenciales a partir de una lista de alcances.
Paso 4: Realiza la solicitud script.run
Una vez configurada la aplicación que realiza la llamada, puedes hacer lo siguiente:
Llamadas a scripts.run Cada API
llamada consiste en los siguientes pasos:
- Compila una solicitud a la API. usando el ID de la secuencia de comandos, el nombre de la función y cualquier parámetros.
- Haz que
scripts.runllama e incluye el token OAuth de la secuencia de comandos que creaste en (si se usa una solicitud básicaPOST), o bien utiliza un objeto de credenciales que creaste con los permisos de secuencias de comandos. - Permite que la secuencia de comandos termine de ejecutarse. Las secuencias de comandos pueden ocupar hasta 6 minutos de tiempo de ejecución, por lo que tu aplicación debería permitirlo.
- Al finalizar, la función script puede devolver un valor, que la API envía a la aplicación si el valor es de un tipo admitido.
Encontrarás ejemplos de llamadas a la API de script.run.
a continuación.
Ejemplos de solicitud a la API
Los siguientes ejemplos muestran cómo realizar una solicitud de ejecución a la API de Apps Script en
en varios idiomas, llamando a una función Apps Script para imprimir una lista de
carpetas del directorio raíz del usuario. El ID de secuencia de comandos del proyecto de Apps Script
que contenga la función ejecutada deben especificarse donde se indique con
ENTER_YOUR_SCRIPT_ID_HERE Los ejemplos se basan en el
bibliotecas cliente de las APIs de Google para sus respectivos
idiomas.
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 la el proyecto que aloja la secuencia de comandos.
Además, las aplicaciones de llamadas deben enviar credenciales OAuth que incluyan el siguiente alcance de Drive:
https://www.googleapis.com/auth/drive
Estas aplicaciones de ejemplo usan bibliotecas cliente de Google para compilar objetos de credenciales para OAuth que usan este permiso.
/**
* 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
/**
* Call an Apps Script function to list the folders in the user's root Drive
* folder.
*
*/
async function callAppsScript() {
const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';
const {GoogleAuth} = require('google-auth-library');
const {google} = require('googleapis');
// Get credentials and build service
// TODO (developer) - Use appropriate auth mechanism for your app
const auth = new GoogleAuth({
scopes: 'https://www.googleapis.com/auth/drive',
});
const script = google.script({version: 'v1', auth});
try {
// Make the API request. The request object is included here as 'resource'.
const resp = await script.scripts.run({
auth: auth,
resource: {
function: 'getFoldersUnderRoot',
},
scriptId: scriptId,
});
if (resp.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 = resp.error.details[0];
console.log('Script error message: ' + error.errorMessage);
console.log('Script error stacktrace:');
if (error.scriptStackTraceElements) {
// There may not be a stacktrace if the script didn't start executing.
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 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
// Node.js object (folderSet).
const folderSet = resp.response.result;
if (Object.keys(folderSet).length == 0) {
console.log('No folders returned!');
} else {
console.log('Folders under your root folder:');
Object.keys(folderSet).forEach(function(id) {
console.log('\t%s (%s)', folderSet[id], id);
});
}
}
} catch (err) {
// TODO(developer) - Handle error
throw err;
}
}
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 varias limitaciones:
Un proyecto común de Cloud. El script que se llama y el que realiza la llamada debe compartir un proyecto de Cloud. El proyecto de Cloud debe ser una proyecto estándar de Cloud; los proyectos predeterminados que se crearon para los proyectos de Apps Script no son suficientes. El un proyecto de Cloud estándar puede ser un proyecto nuevo o uno existente.
Parámetros básicos y tipos de datos que se muestran. La API no puede pasar ni devolver Objetos específicos de Apps Script (como Documentos, BLOB Calendarios, Archivos de Drive, etc.) a la y mantener la integridad de su aplicación. Solo tipos básicos como cadenas, arrays, objetos, números y booleanos se pueden pasar y mostrar.
Alcances de OAuth. La API solo puede ejecutar secuencias de comandos que tengan al menos un alcance obligatorio. Esto significa que no puedes usar la API para llamar a una secuencia de comandos que no requiere la autorización de uno o más servicios.
Sin activadores.La API no puede crear Apps Script activadores.