Eseguire Functions con l'API Apps Script

L'API Google Apps Script fornisce un metodo scripts.run che esegue da remoto una funzione Apps Script specificata. Puoi utilizzare questo metodo in un'applicazione di chiamata per eseguire una funzione in uno dei tuoi progetti di script da remoto e ricevere una risposta.

Requisiti

Prima che un'applicazione di chiamata possa utilizzare il metodo scripts.run, devi soddisfare i seguenti requisiti. Devi:

  • Esegui il deployment del progetto di script come eseguibile API. Puoi eseguire il deployment, il ritiro e il nuovo deployment dei progetti in base alle necessità.

  • Fornisci un token OAuth con ambito corretto per l'esecuzione. Questo token OAuth deve coprire tutti gli ambiti utilizzati dallo script, non solo quelli utilizzati dalla funzione chiamata. Consulta l'elenco completo degli ambiti di autorizzazione nel riferimento del metodo.

  • Assicurati che lo script e il client OAuth2 dell'applicazione chiamante condividano un progetto Google Cloud comune. Il progetto Cloud deve essere un progetto Cloud standard. I progetti predefiniti creati per i progetti Apps Script non sono sufficienti. Puoi utilizzare un nuovo progetto Cloud standard o uno esistente.

  • Abilita l'API Google Apps Script nel progetto Cloud.

Il metodo scripts.run

Per poter essere eseguito, il metodo scripts.run richiede informazioni di identificazione chiave:

Facoltativamente, puoi configurare lo script in modo che venga eseguito in modalità di sviluppo. Questa modalità viene eseguita con la versione salvata più recente del progetto di script anziché con la versione di cui è stato eseguito il deployment più di recente. A questo scopo, imposta il valore booleano devMode nel corpo della richiesta su true. Solo il proprietario dello script può eseguirlo in modalità di sviluppo.

Gestione dei tipi di dati dei parametri

L'utilizzo del metodo scripts.run dell'API Apps Script solitamente prevede l'invio di dati ad Apps Script come parametri di funzione e il recupero dei dati come valori restituiti dalla funzione. L'API può accettare e restituire solo valori con tipi di base: stringhe, array, oggetti, numeri e booleani. Questi sono simili ai tipi di base in JavaScript. Gli oggetti Apps Script più complessi, come Document o Sheet, non possono essere passati al progetto di script o da questo dall'API.

Quando l'applicazione chiamante è scritta in un linguaggio fortemente tipizzato come Java, i parametri vengono passati come elenco o array di oggetti generici corrispondenti a questi tipi di base. In molti casi, puoi applicare automaticamente le conversioni di tipo semplice. Ad esempio, a una funzione che accetta un parametro numerico può essere assegnato un oggetto Double, Integer o Long di Java come parametro senza ulteriore gestione.

Quando l'API restituisce la risposta della funzione, spesso è necessario eseguire il casting del valore restituito al tipo corretto prima che possa essere utilizzato. Ecco alcuni esempi basati su Java:

  • I numeri restituiti dall'API a un'applicazione Java arrivano come oggetti java.math.BigDecimal e potrebbero dover essere convertiti in tipi Doubles o int, se necessario.
  • Se la funzione Apps Script restituisce un array di stringhe, un'applicazione Java trasmette la risposta in un oggetto List<String>:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • Se vuoi restituire un array di Bytes, potresti trovare conveniente codificare l'array come stringa base64 all'interno della funzione di Apps Script e restituire la stringa:

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

Gli esempi di codice riportati di seguito illustrano alcuni modi per interpretare la risposta dell'API.

Procedura generale

Di seguito è descritta la procedura generale per utilizzare l'API Apps Script per eseguire le funzioni di Apps Script:

Passaggio 1: configura il progetto Cloud comune

Sia lo script sia l'applicazione chiamante devono condividere lo stesso progetto Cloud. Questo progetto Cloud può essere un progetto esistente o un nuovo progetto creato a questo scopo. Una volta creato un progetto Cloud, devi passare al progetto di script per utilizzarlo.

Passaggio 2: esegui il deployment dello script come API eseguibile

  1. Apri il progetto Apps Script con le funzioni che vuoi utilizzare.
  2. In alto a destra, fai clic su Esegui il deployment > Nuovo deployment.
  3. Nella finestra di dialogo visualizzata, fai clic su Abilita tipi di deployment > Eseguibile API.
  4. Nel menu a discesa "Chi ha accesso", seleziona gli utenti che sono autorizzati a chiamare le funzioni dello script utilizzando l'API Apps Script.
  5. Fai clic su Esegui il deployment.

Passaggio 3: configura l'applicazione per le chiamate

L'applicazione chiamante deve abilitare l'API Apps Script e stabilire le credenziali OAuth prima di poter essere utilizzata. Per farlo, devi avere accesso al progetto Cloud.

  1. Configura il progetto Cloud utilizzato dall'applicazione e dallo script di chiamata. Per farlo, segui questi passaggi:
    1. Abilita l'API Apps Script nel progetto Cloud.
    2. Configura la schermata per il consenso OAuth.
    3. Crea le credenziali OAuth.
  2. Apri il progetto di script e fai clic su Panoramica a sinistra.
  3. In Ambiti OAuth del progetto, registra tutti gli ambiti richiesti dallo script.
  4. Nel codice dell'applicazione chiamante, genera un token di accesso OAuth dello script per la chiamata all'API. Non si tratta di un token utilizzato dall'API stessa, ma di uno richiesto dall'interprete dello script durante l'esecuzione. Deve essere creato utilizzando l'ID cliente del progetto Cloud e gli ambiti dello script che hai registrato.

    Le librerie client di Google possono essere di grande aiuto per creare questo token e gestire OAuth per l'applicazione, solitamente consentendo di creare un oggetto "credentials" di livello superiore utilizzando gli ambiti dello script. Consulta le iniziative rapide dell'API Apps Script per esempi di creazione di un oggetto delle credenziali da un elenco di ambiti.

Passaggio 4: effettua la richiesta script.run

Una volta configurata l'applicazione per le chiamate, puoi effettuare chiamate scripts.run. Ogni chiamata API è composta dai seguenti passaggi:

  1. Crea una richiesta API utilizzando l'ID script, il nome della funzione e gli eventuali parametri obbligatori.
  2. Esegui la chiamata scripts.run e includi il token OAuth dello script che hai creato nell'header (se utilizzi una richiesta POST di base) oppure utilizza un oggetto delle credenziali che hai creato con gli ambiti dello script.
  3. Attendi il completamento dell'esecuzione dello script. Gli script possono richiedere fino a sei minuti di tempo di esecuzione, quindi la tua applicazione deve consentire questo tempo.
  4. Al termine, la funzione dello script può restituire un valore, che l'API restituisce all'applicazione se il valore è di tipo supportato.

Di seguito puoi trovare esempi di chiamate API script.run.

Esempi di richieste API

Gli esempi riportati di seguito mostrano come effettuare una richiesta di esecuzione dell'API Apps Script in varie lingue, chiamando una funzione di Apps Script per stampare un elenco di cartelle nella home directory dell'utente. L'ID script del progetto Apps Script contenente la funzione eseguita deve essere specificato dove indicato con ENTER_YOUR_SCRIPT_ID_HERE. Gli esempi si basano sulle librerie client delle API di Google per i rispettivi linguaggi.

Script target

La funzione in questo script utilizza l'API Drive.

Devi abilitare l'API Drive nel progetto che ospita lo script.

Inoltre, le applicazioni chiamanti devono inviare credenziali OAuth che includono il seguente ambito Drive:

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

Le applicazioni di esempio riportate di seguito utilizzano le librerie client di Google per creare oggetti delle credenziali per OAuth utilizzando questo ambito.

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

Limitazioni

L'API Apps Script presenta diverse limitazioni:

  1. Un progetto Cloud comune. Lo script chiamato e l'applicazione chiamante devono condividere un progetto Cloud. Il progetto Cloud deve essere un progetto Cloud standard. I progetti predefiniti creati per i progetti Apps Script non sono sufficienti. Il progetto Cloud standard può essere un progetto nuovo o esistente.

  2. Parametri di base e tipi restituiti. L'API non può passare o restituire all'applicazione oggetti specifici di Apps Script (ad esempio Documenti, Blob, Calendari, File di Drive e così via). È possibile passare e restituire solo tipi di base come stringhe, array, oggetti, numeri e valori booleani.

  3. Ambiti OAuth. L'API può eseguire solo script con almeno un ambito obbligatorio. Ciò significa che non puoi utilizzare l'API per chiamare uno script che non richiede l'autorizzazione di uno o più servizi.

  4. Nessun trigger.L'API non può creare trigger di Apps Script.