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 in remoto una funzione in uno dei tuoi progetti di script e ricevere una risposta.
Requisiti
Devi soddisfare i seguenti requisiti prima che un'applicazione di chiamata possa utilizzare il metodo scripts.run. Devi:
Esegui il deployment del progetto di script come eseguibile dell'API. Puoi eseguire il deployment dei progetti, annullarne il deployment e ripeterne il deployment in base alle tue esigenze.
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 al metodo.
Assicurati che lo script e il client OAuth2 dell'applicazione di chiamata 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
Il metodo scripts.run richiede informazioni che consentono l'identificazione della chiave per poter eseguire:
- L'ID del progetto di script.
- Il nome della funzione da eseguire.
- L'elenco di parametri richiesti dalla funzione (se presenti).
In via facoltativa, 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. Per farlo, 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 prevede in genere 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 valori solo con tipi di base: stringhe, array, oggetti, numeri e booleani. Sono simili ai tipi di base in JavaScript. L'API non può trasferire oggetti Apps Script più complessi come Document o Sheet.
Quando l'applicazione di chiamata è scritta in un linguaggio di tipo forte come Java, trasmette i parametri sotto forma di elenco o array di oggetti generici corrispondenti a questi tipi di base. In molti casi, puoi applicare
automaticamente conversioni di tipo semplice. Ad esempio, a una funzione che accetta un parametro numerico è possibile assegnare come parametro un oggetto Java Double, Integer o Long senza ulteriore gestione.
Quando l'API restituisce la risposta della funzione, spesso devi trasmettere il valore restituito al tipo corretto prima di poterlo utilizzare. Ecco alcuni esempi basati su Java:
- I numeri restituiti dall'API a un'applicazione Java arrivano come oggetti
java.math.BigDecimale potrebbero dover essere convertiti ai tipiDoublesoint, 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 utile codificare l'array come stringa base64 all'interno della funzione Apps Script e restituire invece quella stringa:return Utilities.base64Encode(myByteArray); // returns a String.
Gli esempi di codice di esempio riportati di seguito illustrano come interpretare la risposta dell'API.
Procedura generale
Di seguito viene descritta la procedura generale per l'esecuzione delle funzioni di Apps Script con l'API Apps Script:
Passaggio 1: configura il progetto Cloud comune
Sia lo script che l'applicazione di chiamata devono condividere lo stesso progetto Cloud. Può trattarsi di un progetto esistente o un nuovo progetto creato a questo scopo. Una volta creato un progetto Cloud, devi cambiare il progetto di script per utilizzarlo.
Passaggio 2: esegui il deployment dello script come eseguibile API
- Apri il progetto Apps Script con le funzioni che vuoi utilizzare.
- In alto a destra, fai clic su Esegui il deployment > Nuovo deployment.
- Nella finestra di dialogo che si apre, fai clic su Abilita tipi di deployment
> Eseguibile API. - Nel menu a discesa "Chi ha accesso", seleziona gli utenti autorizzati a chiamare le funzioni dello script utilizzando l'API Apps Script.
- Fai clic su Esegui il deployment.
Passaggio 3: configura l'applicazione di chiamata
L'applicazione di chiamata deve attivare l'API Apps Script e stabilire le credenziali OAuth prima di poter essere utilizzata. Per farlo, devi avere accesso al progetto Cloud.
- Configura il progetto Cloud utilizzato dall'applicazione e dallo script di chiamata. Per farlo, segui questi passaggi:
- Apri il progetto di script e fai clic su Panoramica
a sinistra. - In Ambiti OAuth del progetto, registra tutti gli ambiti richiesti dallo script.
Nel codice dell'applicazione chiamante, genera un token di accesso OAuth di script per la chiamata API. Non si tratta di un token utilizzato dall'API stessa, ma di uno richiesto dallo script durante l'esecuzione. Deve essere creato utilizzando l'ID client del progetto Cloud e gli ambiti di script che hai registrato.
Le librerie client di Google possono essere di grande aiuto nella creazione di questo token e nella gestione di OAuth per l'applicazione, consentendo in genere di creare un oggetto "credenziali" di livello superiore utilizzando gli ambiti degli script. Consulta le guide rapide dell'API Apps Script per alcuni 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 di chiamata, puoi effettuare
chiamate a scripts.run. Ogni chiamata API prevede i seguenti passaggi:
- Crea una richiesta API utilizzando l'ID script, il nome della funzione ed eventuali parametri obbligatori.
- Effettua la chiamata a
scripts.rune includi il token OAuth dello script che hai creato nell'intestazione (se utilizzi una richiestaPOSTdi base) oppure utilizza un oggetto delle credenziali creato con gli ambiti degli script. - Consenti il completamento dell'esecuzione dello script. L'esecuzione degli script può richiedere fino a sei minuti, pertanto l'applicazione dovrebbe consentire questa operazione.
- Al termine, la funzione script potrebbe restituire un valore, che l'API restituisce all'applicazione se il valore è un 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 vari linguaggi, chiamando una funzione Apps Script per stampare un elenco di cartelle nella directory radice 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 di destinazione
La funzione in questo script utilizza l'API Drive.
Devi abilitare l'API Drive nel progetto che ospita lo script.
Inoltre, le applicazioni di chiamata devono inviare credenziali OAuth che includono il seguente ambito di Drive:
https://www.googleapis.com/auth/drive
Le applicazioni di esempio qui utilizzano le librerie client di Google per creare oggetti 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:
Un progetto Cloud comune. Lo script chiamato e l'applicazione chiamata 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.
Tipi di parametri di base e restituiti. L'API non può passare o restituire oggetti specifici di Apps Script (come Documenti, Blob, Calendari, file di Drive e così via) all'applicazione. Possono essere trasmessi e restituiti solo tipi di base come stringhe, array, oggetti, numeri e booleani.
Ambiti OAuth. L'API può eseguire solo script che hanno 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.
Nessun trigger.L'API non può creare attivatori Apps Script.