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 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 sapere quali API di Google sono disponibili come servizi avanzati, cerca la sezione Servizi Google avanzati nella sezione Documentazione. Se vuoi utilizzare un'API Google che non è disponibile come servizio avanzato, connettiti come faresti con 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 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, in pratica l'API di Google viene considerata come un'API esterna. Questo metodo consente di usare
tutti gli aspetti dell'API. Tuttavia, devi gestire autonomamente l'autorizzazione
dell'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:
- Devi abilitare il servizio avanzato nel progetto di script.
Devi assicurarti che l'API corrispondente al servizio avanzato sia attivata nel progetto Cloud (Google Cloud) utilizzato dallo script.
Se il progetto di script utilizza un progetto Google Cloud predefinito creato a partire dall'8 aprile 2019, l'API viene attivata automaticamente dopo aver attivato il servizio avanzato e salvato il progetto di script. Se non l'hai ancora fatto, ti potrebbe anche essere chiesto di accettare i Termini di servizio di Google Cloud e delle API Google.
Se il progetto di script utilizza un progetto Google Cloud standard o un progetto Google Cloud predefinito precedente, devi attivare 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 Progetti Cloud Platform.
Attivare i servizi avanzati
Per utilizzare un servizio Google avanzato, segui queste istruzioni:
- Apri il progetto Apps Script.
- A sinistra, fai clic su Editor .
- A sinistra, accanto a Servizi, fai clic su Aggiungi un servizio .
- 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 solitamente fornisce informazioni sufficienti per iniziare, ma le regole riportate di seguito spiegano come Apps Script genera una firma del metodo da un'API Google pubblica.
Le richieste alle API di Google possono accettare diversi tipi di dati, tra cui parametri di percorso, parametri di query, un corpo della richiesta e/o un allegato per il caricamento di contenuti multimediali. Alcuni servizi avanzati possono anche accettare intestazioni specifiche delle richieste HTTP (ad esempio il servizio avanzato di Calendar).
La firma del metodo corrispondente in Google Apps Script ha i seguenti parametri:
- Il corpo della richiesta (di solito una risorsa) come oggetto JavaScript.
- Percorso o parametri obbligatori come singoli argomenti.
- L'allegato del caricamento di contenuti multimediali, come argomento
Blob. - Parametri facoltativi, come un oggetto JavaScript che mappa i nomi dei parametri ai valori.
- Intestazioni di richiesta HTTP, come oggetto JavaScript che mappa i nomi delle intestazioni ai valori.
Se il metodo non contiene elementi in una determinata categoria, quella parte della firma viene omessa.
Esistono alcune eccezioni speciali da tenere presenti:
- Per i metodi che accettano il caricamento di contenuti multimediali, il parametro
uploadTypeviene impostato automaticamente. - I metodi denominati
deletenell'API Google sono denominatiremovein Apps Script, poichédeleteè una parola riservata in JavaScript. - Se un servizio avanzato è configurato per accettare intestazioni di richiesta HTTP e imposti un oggetto JavaScript di intestazioni di richiesta, 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 semplici wrapper che consentono l'utilizzo di API Google all'interno di Apps Script. Di conseguenza, qualsiasi problema riscontrato durante l'utilizzo è solitamente correlato all'API sottostante, non ad Apps Script stesso.
Se riscontri un problema durante l'utilizzo di un servizio avanzato, deve essere segnalato utilizzando 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 Documentazione di Apps Script.