Method: scripts.run

Esegue una funzione in un progetto Apps Script. È necessario eseguire il deployment del progetto di script affinché possa essere utilizzato con l'API Apps Script e l'applicazione chiamante deve condividere lo stesso progetto della piattaforma Cloud.

Questo metodo richiede l'autorizzazione con un token OAuth 2.0 che includa almeno uno degli ambiti elencati nella sezione Autorizzazione. Questa API non consente di eseguire progetti di script che non richiedono l'autorizzazione. 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 Cloud Platform utilizzato per autorizzare la richiesta non è uguale a quello 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. Trova l'ID script nella pagina Impostazioni progetto, nella sezione "ID".

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 per 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 di tipi primitivi come string, number, array, object o boolean. (Facoltativo)
sessionState

string

Obsoleta. Da utilizzare solo con 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 con uno stato di sessione, acquisisce i privilegi di uno script legato, ovvero può accedere a informazioni come la posizione attuale 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"). (Facoltativo)
devMode

boolean

Se true e l'utente sono proprietari dello script, lo script viene eseguito nella versione salvata più di recente anziché in quella 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:

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 runtime di esecuzione massimo è elencato nella guida alle quote di Apps Script.

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

  • Se la funzione script viene restituita correttamente, il campo response contiene un oggetto ExecutionResponse con il valore restituito dalla funzione nel campo result dell'oggetto.
  • Se la funzione script (o lo stesso Apps Script) 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 è stata ancora completata, il campo done è false e non sono presenti né i campi response né error.
  • Se la chiamata run non va a buon fine (ad esempio a causa di una richiesta con formato non valido o di un errore di autorizzazione), il metodo restituisce un codice di risposta HTTP 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 from che è stata eseguita.
Campo unione result. Il risultato dell'operazione, che può essere un valore error o un valore response valido. Se done == false, non sono impostati né error né response. Se done == true, può essere impostato 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 di script (o lo stesso Apps Script) 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 viene restituita correttamente, questo campo contiene un oggetto ExecutionResponse con il valore restituito della 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 di script (o lo stesso Apps Script) 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:

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

string

Un messaggio di errore rivolto agli sviluppatori, in inglese. Qualsiasi messaggio di errore rivolto agli utenti viene localizzato e inviato nel campo details oppure viene localizzato dal client.
details[]

object

Un array che contiene 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" }.