Servizi Google avanzati

I servizi avanzati di Apps Script consentono agli sviluppatori esperti di connettersi a determinate API Google pubbliche con meno configurazioni rispetto alle interfacce HTTP. I servizi avanzati sono essenzialmente wrapper sottili intorno a tali API di Google. Funzionano molto come i servizi integrati di Apps Script, ad esempio offrono il completamento automatico e Apps Script gestisce automaticamente il flusso di autorizzazione. Tuttavia, devi attivare 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 sezione Riferimenti. Se vuoi utilizzare un'API di Google che non è disponibile come servizio avanzato, collegala come 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 i servizi avanzati o semplicemente inviando le richieste API direttamente utilizzando UrlFetch.

Se utilizzi il metodo di servizio avanzato, Apps Script gestisce il flusso di autorizzazione e offre il supporto di completamento automatico. Tuttavia, devi attivare 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, stai trattando l'API Google come un'API esterna. Con questo metodo, è possibile utilizzare tutti gli aspetti dell'API. Tuttavia, è necessario che tu gestisca l'autorizzazione dell'API. Devi anche costruire le intestazioni necessarie e analizzare le risposte dell'API.

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

Requisiti

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

  1. Devi attivare il servizio avanzato nel progetto dello script.
  2. Devi assicurarti che l'API corrispondente al servizio avanzato sia attivata nel progetto Cloud Platform (GCP) utilizzato dallo script.

    Se il tuo progetto di script utilizza un progetto GCP predefinito creato a partire dall'8 aprile 2019, l'API viene attivata automaticamente dopo aver abilitato il servizio avanzato e aver salvato il progetto di script. Se non l'hai già fatto, ti potrebbe anche essere chiesto di accettare i Termini di servizio di Google Cloud Platform e delle API di Google.

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

Per ulteriori informazioni, consulta la pagina dei progetti di Cloud Platform.

Abilita 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 è disponibile nel completamento automatico.

Come vengono stabilite le firme dei metodi

In genere, i servizi avanzati utilizzano gli stessi oggetti, nomi di metodi e parametri delle API pubbliche corrispondenti, anche se le firme di metodo vengono tradotte per essere utilizzate in Apps Script. La funzione di completamento automatico dell'editor di script di solito fornisce informazioni sufficienti per iniziare, ma le regole seguenti spiegano in che modo Apps Script genera una firma del metodo da un'API pubblica di Google.

Le richieste alle API di Google possono accettare una varietà di tipi di dati diversi, tra cui parametri del percorso, parametri di ricerca, un corpo della richiesta e/o un allegato di caricamento dei contenuti multimediali. Alcuni servizi avanzati possono anche accettare intestazioni di richieste HTTP specifiche (ad esempio, il servizio avanzato di Calendar).

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

  1. Il corpo della richiesta (di solito una risorsa) come oggetto JavaScript.
  2. Percorso o parametri obbligatori, come singoli argomenti.
  3. L'allegato di caricamento dei contenuti multimediali, come argomento Blob.
  4. Parametri facoltativi, come 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, la parte della firma viene omessa.

Esistono alcune eccezioni speciali da tenere presenti:

  • Per i metodi che accettano un caricamento multimediale, 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 anche impostare l'oggetto JavaScript dei parametri facoltativi (su un oggetto vuoto se non utilizzi parametri facoltativi).

Assistenza per servizi avanzati

I servizi avanzati sono semplicemente wrapper che consentono l'utilizzo di un'API Google all'interno di Apps Script. Di conseguenza, i problemi riscontrati durante il loro utilizzo sono di solito un problema dell'API sottostante, non di Apps Script.

Se riscontri un problema durante l'utilizzo di un servizio avanzato, ti consigliamo di segnalarlo utilizzando le istruzioni per l'assistenza relative all'API sottostante. I link a queste istruzioni per l'assistenza sono disponibili in ogni guida avanzata ai servizi nella sezione Riferimento di Apps Script.