Servizi Google avanzati

I servizi avanzati in Apps Script ti consentono di connetterti a determinate API Google pubbliche con meno configurazione rispetto all'utilizzo delle relative interfacce HTTP. I servizi avanzati sono 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.

Attivare i servizi avanzati

Per utilizzare un servizio Google avanzato, segui queste istruzioni:

Passaggio 1: attiva il servizio avanzato

Puoi abilitare un servizio avanzato utilizzando l'editor Apps Script o modificando il manifest.

Metodo A: utilizzare l'editor

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

Metodo B: utilizzo del manifest

Puoi attivare i servizi avanzati modificando il file manifest. Ad esempio, per attivare il servizio avanzato Google Drive, aggiungi il campo enabledAdvancedServices all'oggetto dependencies:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

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

Passaggio 2: abilita l'API Google Cloud (solo progetti Google Cloud standard)

Se utilizzi un progetto Google Cloud predefinito (creato automaticamente da Apps Script), puoi ignorare questo passaggio. L'API viene abilitata automaticamente quando aggiungi il servizio nel passaggio 1.

Se utilizzi un progetto Google Cloud standard, devi anche attivare manualmente l'API corrispondente al servizio avanzato. Per abilitare l'API manualmente:

1. Apri il progetto Cloud associato allo script nella ** console Google Cloud**.

2. Nella parte superiore della console, fai clic sulla barra di ricerca e digita parte del nome dell'API (ad esempio "Calendar"), quindi fai clic sul nome quando lo vedi.

3. Fai clic su Abilita API.

4. Chiudi la console Google Cloud e torna all'editor di script.

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 che seguono spiegano come Apps Script genera una firma del 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 o un allegato di caricamento multimediale. 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. Se il metodo richiede più parametri di percorso, questi vengono visualizzati nell'ordine in cui sono elencati nell'URL dell'endpoint API.
3. L'allegato di caricamento dei contenuti multimediali, come argomento Blob.
4. Parametri facoltativi (in genere parametri di query), 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, 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).

Esempio: Calendar.Events.insert

Supponiamo che tu voglia creare un evento di Calendar. La documentazione dell'API Google Calendar mostra la struttura della richiesta HTTP corrispondente:

• Verbo HTTP: POST
• URL richiesta: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

• Corpo della richiesta: una risorsa Event.

• Parametri di query: sendUpdates, supportsAttachments e così via.

In Apps Script, la firma del metodo è determinata dal riordino di questi input:

1. Body: la risorsa evento (oggetto JavaScript).
2. Percorso: il calendarId (stringa).
3. Parametri facoltativi: i parametri di query (oggetto JavaScript).

La chiamata al metodo risultante ha il seguente aspetto:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

Servizi avanzati o HTTP?

Ciascuno dei servizi Google avanzati è associato a un'API Google pubblica. In Apps Script, puoi accedere a queste API utilizzando i servizi avanzati o 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.

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 la gestione dell'autorizzazione API.

La seguente tabella mette a confronto i due metodi:

Confronto del codice

Gli esempi di codice mostrano la differenza di complessità tra la creazione di un evento di calendario utilizzando il servizio avanzato e l'utilizzo di UrlFetchApp.

Servizio avanzato:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

Ti consigliamo di utilizzare un servizio avanzato, se possibile, e di utilizzare il metodo UrlFetch solo quando il servizio avanzato non è disponibile o non fornisce la funzionalità di cui hai bisogno.

Supporto per i servizi avanzati

Poiché i servizi avanzati sono wrapper leggeri che incapsulano le API di Google, qualsiasi problema riscontrato durante il loro utilizzo è in genere un problema con l'API sottostante, non con Apps Script.

Se riscontri un problema durante l'utilizzo di un servizio avanzato, devi segnalarlo seguendo le istruzioni di assistenza per l'API sottostante.