Method: scripts.run

Esegue una funzione in un progetto Apps Script. È necessario eseguire il deployment del progetto di script per utilizzarlo con l'API Apps Script e l'applicazione chiamante deve condividere lo stesso progetto Cloud Platform.

Questo metodo richiede l'autorizzazione con un token OAuth 2.0 che includa almeno uno degli ambiti elencati nella sezione Autorizzazione. I progetti di script che non richiedono l'autorizzazione non possono essere eseguiti tramite questa API. Per trovare gli ambiti corretti da includere nel token di autenticazione, apri la pagina Panoramica del progetto di script e scorri verso il basso fino ad "Ambiti OAuth del progetto".

L'errore 403, PERMISSION_DENIED: The caller does not have permission indica che il progetto della piattaforma Cloud utilizzato per autorizzare la richiesta non è lo stesso utilizzato dallo script.

Richiesta HTTP

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
scriptId

string

L'ID dello script da eseguire. Individua l'ID dello script nella sezione "ID" della pagina Impostazioni progetto.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Campi
function

string

Il nome della funzione da eseguire nello script specificato. Il nome non include parentesi o parametri. Può fare riferimento a una funzione in una libreria inclusa come Library.libFunction1.

parameters[]

value (Value format)

I parametri da passare alla funzione in esecuzione. Il tipo di oggetto di ogni parametro deve corrispondere al tipo previsto in Apps Script. I parametri non possono essere tipi di oggetti specifici di Apps Script (ad esempio Document o Calendar); possono essere solo tipi primitivi come string, number, array, object o boolean. Campo facoltativo.

sessionState

string

Obsoleta. Da utilizzare solo con i componenti aggiuntivi Android. Un ID che rappresenta la sessione corrente dell'utente nell'app per Android per Documenti o Fogli Google, incluso come dati aggiuntivi nell'intent che avvia il componente aggiuntivo. Quando un componente aggiuntivo Android viene eseguito in uno stato sessione, ottiene i privilegi di uno script associato, ovvero può accedere a informazioni come la posizione corrente del cursore dell'utente (in Documenti) o la cella selezionata (in Fogli). Per recuperare lo stato, chiama Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Campo facoltativo.

devMode

boolean

Se true e l'utente è un proprietario dello script, lo script viene eseguito all'ultima versione salvata anziché alla versione di cui è stato eseguito il deployment per l'utilizzo con l'API Apps Script. Facoltativo; il valore predefinito è false.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Una rappresentazione di un'esecuzione di una funzione Apps Script iniziata con run. La risposta di esecuzione non arriva fino al termine dell'esecuzione della funzione. Il tempo di esecuzione massimo è elencato nella guida alle quote di Apps Script.

Una volta avviata, l'esecuzione può avere uno di questi quattro risultati:

  • Se la funzione script restituisce correttamente, il campo response contiene un oggetto ExecutionResponse con il valore restituito dalla funzione nel campo result dell'oggetto.
  • Se la funzione script (o Apps Script stesso) genera un'eccezione, il campo error contiene un oggetto Status. Il campo details dell'oggetto Status contiene un array con un singolo oggetto ExecutionError che fornisce informazioni sulla natura dell'errore.
  • Se l'esecuzione non è ancora stata completata, il campo done è false e non sono presenti né i campi responseerror.
  • Se la chiamata a run non va a buon fine (ad esempio, a causa di una richiesta non corretta o di un errore di autorizzazione), il metodo restituisce un codice di risposta HTTP compreso nell'intervallo 4XX con un formato diverso per il corpo della risposta. Le librerie client convertono automaticamente una risposta 4XX in una classe di eccezione.

Rappresentazione JSON
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Campi
done

boolean

Questo campo indica se l'esecuzione dello script è stata completata. Un'esecuzione completata ha un campo response compilato contenente la funzione ExecutionResponse della funzione eseguita.

Campo di unione result. Il risultato dell'operazione, che può essere un error o un response valido. Se done == false, non è impostato né errorresponse. Se done == true, è possibile impostare esattamente un valore tra error o response. Alcuni servizi potrebbero non fornire il risultato. result può essere solo uno dei seguenti:
error

object (Status)

Se una chiamata run ha esito positivo, ma la funzione script (o Apps Script stesso) genera un'eccezione, questo campo contiene un oggetto Status. Il campo details dell'oggetto Status contiene un array con un singolo oggetto ExecutionError che fornisce informazioni sulla natura dell'errore.

response

object

Se la funzione script restituisce correttamente, questo campo contiene un oggetto ExecutionResponse con il valore restituito dalla funzione.

Un oggetto che contiene campi di tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

Per ulteriori informazioni, consulta la Panoramica di OAuth 2.0.

Stato

Se una chiamata run ha esito positivo, ma la funzione script (o Apps Script stesso) genera un'eccezione, il campo error del corpo della risposta contiene questo oggetto Status.

Rappresentazione JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campi
code

integer

Il codice di stato. Per questa API, il valore indicato è:

  • 10, che indica un errore SCRIPT_TIMEOUT,
  • 3, che indica un errore INVALID_ARGUMENT oppure
  • 1, che indica un'esecuzione di CANCELLED.

message

string

Un messaggio di errore rivolto agli sviluppatori in inglese. Tutti i messaggi di errore rivolti agli utenti vengono localizzati e inviati nel campo details oppure dal client.

details[]

object

Un array contenente un singolo oggetto ExecutionError che fornisce informazioni sulla natura dell'errore.

Un oggetto che contiene campi di tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.