Method: scripts.run

Esegue una funzione in un progetto Apps Script. Il progetto di script deve essere implementato per l'utilizzo 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 a "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 è lo stesso utilizzato dallo script.

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
deploymentId

string

L'ID deployment per il deployment dell'API eseguibile. Trova l'ID deployment in Deploy > Manage deployments (Esegui il deployment > Gestisci deployment) nell'editor di script.

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, ad esempio 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 (come Document o Calendar); possono essere solo tipi primitivi come string, number, array, object o boolean. Facoltativo.
sessionState

string

Deprecato. Da utilizzare solo con i componenti aggiuntivi per Android. Un ID che rappresenta la sessione attuale dell'utente nell'app per Android di Documenti o Fogli Google, incluso come dati aggiuntivi nell'intent che avvia il componente aggiuntivo. Quando un componente aggiuntivo per Android viene eseguito con uno stato della sessione, acquisisce 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"). Facoltativo.
devMode

boolean

Se true e l'utente è proprietario dello script, lo script viene eseguito nella versione salvata più di recente anziché nella 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 dell'esecuzione di una funzione Apps Script avviata con run. La risposta all'esecuzione non arriva finché la funzione non termina l'esecuzione. Il tempo di esecuzione massimo è elencato nella guida alle quote di Apps Script.

Una volta avviata l'esecuzione, può avere uno dei seguenti quattro risultati:

  • Se la funzione dello 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 dello 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 i campi response e error.
  • Se la chiamata 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 nell'intervallo 4XX con un formato diverso per il corpo della risposta. Le librerie client convertono automaticamente una risposta 4XX in una classe di eccezioni.

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 il ExecutionResponse della funzione eseguita.
Campo unione result. Il risultato dell'operazione, che può essere un error o una response valida. Se done == false, né error né response vengono impostati. Se done == true, può essere impostato esattamente uno 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 va a buon fine, ma la funzione dello 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 dello script viene restituita correttamente, questo campo contiene un oggetto ExecutionResponse con il valore restituito dalla funzione.

Un oggetto contenente campi di un 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 saperne di più, consulta la panoramica di OAuth 2.0.

Stato

Se una chiamata run ha esito positivo, ma la funzione dello 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, questo valore:

  • 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. Qualsiasi messaggio di errore rivolto all'utente viene localizzato e inviato nel campo details o localizzato dal client.
details[]

object

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

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