Ejecute funciones con la API de Apps Script

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

La API de Google Apps Script proporciona un método scripts.run que ejecuta una función específica de Apps Script de forma remota. Puedes usar este método en una aplicación de llamadas para ejecutar una función en uno de tus proyectos de secuencia de comandos de forma remota y recibir una respuesta.

Requisitos

Debes cumplir los siguientes requisitos para que una aplicación que realiza la llamada pueda usar el método scripts.run. Debe 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.

  • Proporciona un token de OAuth con 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 de OAuth2 de la aplicación que realiza la llamada compartan un proyecto común de Google 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. 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 información de identificación clave para ejecutarse:

De forma opcional, puedes configurar tu secuencia de comandos para que se ejecute en modo de desarrollo. Este modo se ejecuta con la última versión guardada del proyecto de secuencia de comandos en lugar de la última versión implementada. Para ello, establece el booleano devMode en el cuerpo de la solicitud en true. Solo el propietario de la secuencia de comandos puede ejecutarla en modo de desarrollo.

Controla los tipos de datos de parámetros

Por lo general, el uso del método scripts.run de la API de Apps Script implica el envío de datos a Apps Script como parámetros de funciones y la recuperación de datos como valores de retorno de funciones. La API solo puede tomar y mostrar valores con tipos básicos: strings, arreglos, objetos, números y booleanos. Estos son similares a los tipos básicos en JavaScript. La API no puede pasar objetos de Apps Script más complejos, como Documento, o bien Hoja de cálculo.

Cuando tu aplicación de llamadas está escrita en un lenguaje de tipo seguro, como Java, pasa los parámetros como una lista o un arreglo de objetos genéricos correspondientes a estos tipos básicos. En muchos casos, puedes aplicar conversiones de tipo simple de forma automática. 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 control adicional.

Cuando la API muestra la respuesta de la función, a menudo es necesario convertir el valor mostrado en el tipo correcto para poder usarlo. Estos son algunos ejemplos basados en Java:

  • Los números que muestra la API en una aplicación de Java llegan como objetos java.math.BigDecimal, y es posible que necesiten convertirse en tipos Doubles o int según sea necesario.
  • Si la función de Apps Script muestra un arreglo de strings, 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 arreglo de Bytes, puede resultarte útil codificar el arreglo como una string base64 dentro de la función Apps Script y, en su lugar, mostrar esa string:

    return Utilities.base64Encode(myByteArray); // returns a String.
    

En los ejemplos de código de ejemplo a continuación, se ilustran las formas de interpretar la respuesta de la API.

Procedimiento general

A continuación, se describe el procedimiento general para usar la API de Apps Script a fin de ejecutar funciones de Apps Script:

Paso 1: Configura el proyecto común de Cloud

La secuencia de comandos y la aplicación que realiza la llamada deben compartir el mismo proyecto de Cloud. Este proyecto de Cloud puede ser uno existente o uno nuevo creado con este fin. Una vez que tengas un proyecto de Cloud, deberás cambiar tu proyecto de secuencia de comandos para usarlo.

Paso 2: Implementa la secuencia de comandos como un ejecutable de la API

  1. Abre el proyecto de Apps Script con las funciones que deseas usar.
  2. En la esquina superior derecha, haz clic en Implementar > Nueva implementación.
  3. En el cuadro de diálogo que se abre, haz clic en Habilitar tipos de implementación > API ejecutable.
  4. En el menú desplegable "Quién tiene acceso", selecciona los usuarios que pueden llamar a las funciones de la secuencia de comandos mediante la API de Apps Script.
  5. Haga 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 credenciales de OAuth para poder usarla. Para hacer esto, debes tener acceso al proyecto de Cloud.

  1. Configura el proyecto de Cloud que usan la aplicación y la secuencia de comandos de llamadas. Para ello, sigue estos pasos:
    1. Habilita la API de Apps Script en el proyecto de Cloud.
    2. Configura la pantalla de consentimiento de OAuth.
    3. Crear credenciales OAuth
  2. Abre el proyecto de secuencia de comandos. A la izquierda, haz clic en Descripción general .
  3. En Alcances de OAuth del proyecto, registra todos los permisos que requiere la secuencia de comandos.
  4. En el código de la aplicación que realiza la llamada, genera un token de acceso OAuth de secuencia de comandos para la llamada a la API. Este no es un token que la API usa, sino uno que la secuencia de comandos necesita cuando se ejecuta. Debe compilarse 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 contribuir en gran medida a la creación de este token y a la administración de OAuth para las aplicaciones, lo que, en general, te permite compilar un objeto de "credenciales" de nivel superior mediante 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 alcances.

Paso 4: Realiza la solicitud script.run

Una vez que se configura la aplicación que realiza la llamada, puedes realizar llamadas scripts.run. Cada llamada a la API consta de los siguientes pasos:

  1. Crea una solicitud a la API con el ID de la secuencia de comandos, el nombre de la función y cualquier parámetro requerido.
  2. Realiza la llamada scripts.run y, además, incluye el token de OAuth de secuencia de comandos que creaste en el encabezado (si usas una solicitud POST básica) o usa un objeto de credencial que creaste con los alcances de la secuencia de comandos.
  3. Permita que la secuencia de comandos termine de ejecutarse. Las secuencias de comandos pueden tardar hasta seis minutos de ejecución, por lo que la aplicación debe permitirlo.
  4. Cuando finalice, la función de la secuencia de comandos puede mostrar un valor, que la API entrega a la aplicación si el valor es un tipo admitido.

Puedes encontrar ejemplos de llamadas a la API de script.run a continuación.

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 lenguajes, 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 debe especificarse cuando se indique con ENTER_YOUR_SCRIPT_ID_HERE. Los ejemplos se basan en las bibliotecas cliente de la API de Google para sus respectivos lenguajes.

Secuencia de comandos de destino

La función en 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 llaman deben enviar credenciales de OAuth que incluyan el siguiente alcance de Drive:

  • https://www.googleapis.com/auth/drive

En las aplicaciones de ejemplo de este documento, se usan las bibliotecas cliente de Google a fin de 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

/**
 * 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

from __future__ import print_function

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}."
                          f"{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:

  1. Un proyecto común de Cloud La secuencia de comandos que se está llamando y la aplicación que realiza la llamada deben compartir un proyecto de Cloud. El proyecto de Cloud debe ser un proyecto estándar de Cloud; los proyectos predeterminados creados para proyectos de Apps Script no son suficientes. El proyecto de Cloud estándar puede ser uno nuevo o uno existente.

  2. Tipos básicos y tipos de datos que se muestran. La API no puede pasar ni mostrar objetos específicos de Apps Script (como Documentos, BLOB, Calendarios, Archivos de Drive, etc.) a la aplicación. Solo se pueden pasar y mostrar tipos básicos como strings, arreglos, objetos, números y booleanos.

  3. 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 autorización de uno o más servicios.

  4. Sin activadores. La API no puede crear activadores de Apps Script.