Servizi Google avanzati

I servizi avanzati in Apps Script consentono agli sviluppatori esperti di connettersi a determinate API pubbliche di Google con meno configurazione rispetto all'utilizzo delle relative interfacce HTTP. I servizi avanzati sono essenzialmente wrapper leggeri che incapsulano queste API Google. Funzionano in modo molto simile ai servizi integrati di Apps Script, ad esempio offrono il completamento automatico e Apps Script gestisce automaticamente il flusso di autorizzazione. Tuttavia, devi abilitare un servizio avanzato prima di poterlo utilizzare in uno script.

Per vedere quali API di Google sono disponibili come servizi avanzati, cerca la sezione Servizi Google avanzati nella Guida di riferimento. Se vuoi utilizzare un'API Google che non è disponibile come servizio avanzato, connettiti come a qualsiasi altra API esterna.

Servizi avanzati o HTTP?

Ciascuno dei servizi Google avanzati è associato a un'API Google pubblica. In Apps Script, puoi accedere a queste API tramite servizi avanzati o semplicemente effettuando le richieste API direttamente utilizzando UrlFetch.

Se utilizzi il metodo del servizio avanzato, Apps Script gestisce il flusso di autorizzazione e offre il supporto del completamento automatico. Tuttavia, devi abilitare il servizio avanzato prima di poterlo utilizzare. Inoltre, alcuni servizi avanzati forniscono solo un sottoinsieme delle funzionalità disponibili nell'API.

Se utilizzi il metodo UrlFetch per accedere direttamente all'API, consideri essenzialmente l'API Google come un'API esterna. Con questo metodo, è possibile utilizzare tutti gli aspetti dell'API. Tuttavia, richiede di gestire personalmente l'autorizzazione API. Devi anche creare le intestazioni necessarie e analizzare le risposte dell'API.

In generale, è più facile utilizzare un servizio avanzato, se possibile, e utilizzare il metodo UrlFetch solo quando il servizio avanzato non fornisce la funzionalità di cui hai bisogno.

Requisiti

Prima di poter utilizzare un servizio avanzato, devi soddisfare i seguenti requisiti:

  1. Devi attivare il servizio avanzato nel tuo progetto di script.

  2. Devi assicurarti che l'API corrispondente al servizio avanzato sia attivata nel progetto Google Cloud (GCP) utilizzato dallo script.

    Se il progetto di script utilizza un progetto GCP predefinito creato a partire dall'8 aprile 2019, l'API viene abilitata automaticamente dopo l'abilitazione del servizio avanzato e il salvataggio del progetto di script. Se non l'hai ancora fatto, potrebbe esserti chiesto di accettare anche i Termini di servizio di Google Cloud e delle API di Google.

    Se il tuo progetto di script utilizza un progetto GCP standard o un progetto GCP predefinito precedente, devi attivare manualmente l'API corrispondente del servizio avanzato nel progetto GCP. Per apportare questa modifica, devi disporre dell'accesso in modifica al progetto Google Cloud.

Per ulteriori informazioni, consulta Progetti Cloud Platform.

Attivare i servizi avanzati

Per utilizzare un servizio Google avanzato, segui queste istruzioni:

  1. Apri il progetto Apps Script.
  2. A sinistra, fai clic su Editor .
  3. A sinistra, accanto a Servizi, fai clic su Aggiungi un servizio .
  4. Seleziona un servizio Google avanzato e fai clic su Aggiungi.

Dopo aver attivato un servizio avanzato, questo sarà disponibile nel completamento automatico.

Come vengono determinate le firme dei metodi

I servizi avanzati in genere utilizzano gli stessi oggetti, nomi di metodi e parametri delle API pubbliche corrispondenti, anche se le firme dei metodi vengono tradotte per l'utilizzo in Apps Script. La funzione di completamento automatico dell'editor di script di solito fornisce informazioni sufficienti per iniziare, ma le regole riportate di seguito spiegano in che modo Apps Script genera la firma di un metodo da un'API Google pubblica.

Le richieste alle API di Google possono accettare vari tipi di dati, inclusi parametri di percorso, parametri di query, un corpo della richiesta e/o un allegato di caricamento di contenuti multimediali. Alcuni servizi avanzati possono accettare anche intestazioni di richieste HTTP specifiche (ad esempio, il servizio avanzato Calendar).

La firma del metodo corrispondente in Google Apps Script ha i seguenti argomenti:

  1. Il corpo della richiesta (di solito una risorsa), come oggetto JavaScript.
  2. Percorso o parametri obbligatori, come argomenti individuali.
  3. L'allegato di caricamento dei contenuti multimediali, come argomento Blob.
  4. Parametri facoltativi, come un oggetto JavaScript che mappa i nomi dei parametri ai valori.
  5. Intestazioni delle richieste HTTP, come un oggetto JavaScript che mappa i nomi delle intestazioni ai valori delle intestazioni.

Se il metodo non ha elementi in una determinata categoria, questa parte della firma viene omessa.

Esistono alcune eccezioni speciali da tenere presenti:

  • Per i metodi che accettano il caricamento di contenuti multimediali, il parametro uploadType viene impostato automaticamente.
  • I metodi denominati delete nell'API Google sono denominati remove in Apps Script, poiché delete è una parola riservata in JavaScript.
  • Se un servizio avanzato è configurato per accettare le intestazioni delle richieste HTTP e imposti un oggetto JavaScript delle intestazioni delle richieste, devi impostare anche l'oggetto JavaScript dei parametri facoltativi (su un oggetto vuoto se non utilizzi parametri facoltativi).

Supporto per i servizi avanzati

I servizi avanzati sono solo wrapper leggeri che consentono l'utilizzo di un'API Google in Apps Script. Pertanto, qualsiasi problema riscontrato durante l'utilizzo è in genere un problema con l'API sottostante, non con Apps Script stesso.

Se riscontri un problema durante l'utilizzo di un servizio avanzato, devi segnalarlo seguendo le istruzioni di assistenza per l'API sottostante. I link a queste istruzioni di assistenza sono forniti in ogni guida ai servizi avanzati nella sezione Riferimento di Apps Script.