Servizi Google avanzati

I servizi avanzati di Apps Script consentono agli sviluppatori esperti di connettersi a determinate API di Google pubbliche con una configurazione minore rispetto all'utilizzo delle loro interfacce HTTP. I servizi avanzati sono essenzialmente wrapper sottile attorno alle API di Google. Funzionano in modo molto simile ai servizi integrati di Apps Script: ad esempio, offrono il completamento automatico e Apps Script gestisce il flusso di autorizzazione automaticamente. 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 avanzati di Google nel Riferimento. Se vuoi utilizzare un'API di Google che non è disponibile come servizio avanzato, connettiti come per qualsiasi altra API esterna.

Servizi avanzati o HTTP?

Ciascuno dei servizi avanzati di Google è associato a un'API di 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 di servizio avanzato, Apps Script gestisce il flusso di autorizzazione e offre il supporto per il completamento automatico. Tuttavia, devi abilitare il servizio avanzato per 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, in pratica l'API di Google viene considerata come API esterna. Questo metodo consente di usare tutti gli aspetti dell'API. Tuttavia, richiede che tu gestisca personalmente l'autorizzazione API. Devi inoltre creare le intestazioni necessarie e analizzare le risposte dell'API.

In generale, è più facile utilizzare un servizio avanzato, ove 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 abilitare il servizio avanzato nel progetto di script.

  2. Devi assicurarti che l'API corrispondente al servizio avanzato sia abilitata nel progetto Cloud Platform (Google Cloud) utilizzato dal tuo script.

    Se il progetto di script utilizza un progetto Google Cloud predefinito creato a partire dall'8 aprile 2019, l'API viene abilitata automaticamente dopo l'attivazione del servizio avanzato e il salvataggio del progetto di script. Se non l'hai ancora fatto, è possibile che ti venga richiesto di accettare anche i Termini di servizio di Google Cloud e delle API di Google.

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

Per ulteriori informazioni, consulta i progetti della piattaforma Cloud.

Abilita 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.

Una volta abilitato, il servizio avanzato è 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 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 diversi tipi di dati, tra cui parametri di percorso, parametri di query, corpo della richiesta e/o un allegato per il caricamento di 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 ha 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 del caricamento di 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, quella parte della firma viene omessa.

Ci sono alcune eccezioni speciali di cui tenere conto:

  • Per i metodi che accettano un caricamento di contenuti multimediali, il parametro uploadType viene impostato automaticamente.
  • I metodi denominati delete nell'API di 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 per le intestazioni delle richieste, devi impostare anche 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 thin che consente l'utilizzo di un'API di Google in Apps Script. Di conseguenza, qualsiasi problema riscontrato durante l'utilizzo è di solito un problema con l'API sottostante, non con Apps Script stesso.

Se si verifica un problema durante l'utilizzo di un servizio avanzato, è necessario segnalarlo seguendo le istruzioni di assistenza per l'API sottostante. I link a queste istruzioni di assistenza sono forniti nella sezione Riferimento di Apps Script nella guida di servizio avanzata.