API di Google Sheets: guida passo passo per principianti

Google Sheets è spesso il posto in cui i team archiviano e condividono i dati. Ma quando aggiorni continuamente lo stesso foglio, copiare e incollare a mano fa perdere tempo.

L'API di Google Sheets ti consente di aggiornare e gestire i fogli in automatico dalle tue app e dai tuoi script. Puoi importare dati, inviare aggiornamenti e mantenere i report sempre aggiornati senza farlo manualmente.

In questa guida vedremo passo dopo passo come configurarla, leggere, scrivere, formattare e automatizzare le attività comuni sui fogli di calcolo.

Primi passi con l'API di Google Sheets

Per iniziare a usare l'API di Google Sheets, ti serve un progetto Google Cloud e un modo per autenticare la tua app. Vediamo in sintesi come impostare tutto. 

Creare un progetto Google Cloud

Tutte le API di Google funzionano all'interno di un progetto Google Cloud. Questo progetto contiene le tue credenziali, le impostazioni dell'API e i limiti di utilizzo.

Ecco come creare il tuo primo progetto: 

• Vai a la Google Cloud Console.
• Clicca su Seleziona un progetto in alto.
• Appare un nuovo pop-up Seleziona un progetto. Da qui, clicca su Nuovo progetto.
• Nella finestra successiva, inserisci un nome per il progetto.
• Clicca su Crea.

Crea un nuovo progetto in Google Console. Immagine dell'autore.

Una volta pronto il progetto, abilita le API necessarie: 

• Apri il tuo progetto.
• Clicca sulle tre linee in alto a sinistra. 
• Vai su API e servizi > API e servizi abilitati.
• Clicca su + Abilita API e servizi.

Vai su Abilita API e servizi per abilitare l'API. Immagine dell'autore.

• Ora si apre la finestra Libreria API. Nella barra di ricerca, cerca Google Sheets API e cliccaci sopra.
• Clicca su Abilita.

Abilita la Google Sheets API. Immagine dell'autore.

Se la tua applicazione deve creare, spostare o gestire file di fogli di calcolo, abilita anche la Google Drive API: 

• Cerca Google Drive API.
• Clicca su Abilita.

Autenticazione e autorizzazione

L'API di Google Sheets supporta tre metodi principali di autenticazione. Quale usare dipende da come funziona la tua app.

OAuth 2.0

Usalo quando utenti reali effettuano l'accesso e lavorano con i propri fogli. Consente agli utenti di approvare l'accesso e la tua app può fare solo ciò che viene autorizzato.

Supponiamo che tu stia creando un'app web che permette agli utenti di collegare i loro account Google così che la tua app possa leggere o aggiornare i loro fogli personali. In questo caso, scegli OAuth 2.0. 

Ecco come fare:

• Nella Google Console, vai a Menu di navigazione (tre linee in alto a sinistra) > API e servizi > Schermata di consenso OAuth

Vai alla schermata di consenso OAuth. Immagine dell'autore.

• Ora compila i dettagli: 
• Inserisci il nome dell'app che richiede il consenso nel campo Nome app
• Inserisci l'email di supporto in modo che gli utenti possano inviare domande e clicca su Avanti
• Ora seleziona il tipo di pubblico Esterno e clicca su Avanti
• Poi inserisci le informazioni di contatto (indirizzo email) affinché Google possa notificarti eventuali modifiche al progetto. Quindi clicca su Avanti
• Accetta l'informativa selezionando la casella e clicca su Continua

• Clicca su Salva. Apparirà un messaggio con Configurazione OAuth creata!

Ora, per autenticare gli utenti finali e accedere ai loro dati di Google Sheets, crea le credenziali client OAuth 2.0. Un client ID identifica in modo univoco la tua applicazione ai server OAuth di Google.

Ecco come fare: 

• Clicca su Menu di navigazione > API e servizi > Credenziali.
• Nella finestra Credenziali, clicca su + Crea credenziali e seleziona ID client OAuth.

Vai a ID client OAuth. Immagine dell'autore.

• Ora seleziona Applicazione web dal menu a tendina Tipo di applicazione.
• Inserisci il nome del client OAuth 2.0 per l'identificazione nella console.
• In URI di reindirizzamento autorizzati, clicca su Aggiungi URI
• Inserisci l'URL di reindirizzamento a cui Google invierà la risposta di autorizzazione. Deve corrispondere esattamente all'URI di reindirizzamento configurato nella tua applicazione (ad esempio, l'endpoint di callback OAuth)
• Clicca su Crea
• Copia e conserva Client ID e Client Secret. 

Chiavi API

Le chiavi API identificano il tuo progetto, non un utente. Funzionano solo con fogli pubblici e non possono modificare file privati.

Per questo dovresti usarle solo quando vuoi leggere dati da un Google Sheet pubblico per visualizzarli su un sito o testare uno script semplice.

Ecco come generare la tua chiave API: 

• Vai su Menu di navigazione > API e servizi > Credenziali.

Vai a Chiavi API. Immagine dell'autore.

• Clicca su + Crea credenziali, poi seleziona Chiave API.
• Scorri in basso, seleziona la casella Limita chiave e poi scegli dal menu a tendina le API con cui questa chiave può essere usata. 
• Clicca su Crea.
• Copia e salva la chiave generata.

Salva la chiave API generata. Immagine dell'autore.

Account di servizio

Gli account di servizio consentono alla tua app di funzionare in autonomia, senza accesso dell'utente. Condividi specifici fogli di calcolo con l'email dell'account di servizio e controlla cosa può fare.

Se vuoi eseguire uno script pianificato che aggiorna un report ogni notte o sincronizza dati da un database in un Google Sheet condiviso, gli account di servizio sono l'opzione migliore. 

Vediamo come crearli e configurarli: 

Creazione e configurazione degli account di servizio

Ecco come fare: 

• Clicca su Google Sheets API che abbiamo abilitato prima. 
• In alto a sinistra, clicca sul pulsante Crea credenziali.

Crea credenziali in Google Sheets API. Immagine dell'autore.

• Nella finestra Crea credenziali, assicurati che Google Sheets API sia selezionata nel campo Seleziona un'API. Ora scegli il tipo di dati a cui vuoi accedere. Poiché stai usando un account di servizio, seleziona Dati dell'applicazione e clicca su Avanti.

Inserisci credenziali. Immagine dell'autore.

• Ora appare una nuova finestra Crea account di servizio:
• Aggiungi Nome account di servizio, ID account di servizio e Descrizione account di servizio. 
• Clicca su Crea e continua.

Apparirà un pop-up con Account di servizio creato.

Crea un account di servizio nella Google Sheets API. Immagine dell'autore.

Un account di servizio non usa login o schermata di consenso. Si autentica invece tramite una chiave privata archiviata in un file di chiave JSON. Questo file consente al server dell'applicazione di provare la propria identità a Google e richiedere automaticamente token di accesso.

Ora, per generare un file di chiave: 

• Apri l'account di servizio. (Puoi trovarlo anche in IAM e amministrazione > Account di servizio) 
• Vai alla scheda Chiavi.
• Clicca su Aggiungi chiave > Crea nuova chiave.
• Scegli JSON e clicca su Crea.

Ora, il file inizierà a scaricarsi. 

Genera un file di chiave JSON per la Google Sheets API. Immagine dell'autore.

Condividere Google Sheets con gli account di servizio

Gli account di servizio non hanno automaticamente accesso ai tuoi fogli. Devi condividere ogni file con l'email dell'account di servizio.

Per farlo: 

• Apri il file che abbiamo scaricato e cerca il client_email. Oppure clicca sull'account di servizio che abbiamo creato nel menu Account di servizio, quindi cerca l'Email. Sono lo stesso indirizzo email. 
• Ora, copia quell'email. 

Copia l'email del client dal file di chiave JSON. Immagine dell'autore.

• Apri il Google Sheet.
• Vai all'opzione Condividi in alto a destra. 
• Incolla nel campo di condivisione l'email che abbiamo copiato prima.
• Scegli l'accesso Lettore (consente lettura e scrittura dei dati) o Editor (consente solo lettura) . 
• Clicca su Invia per condividere l'accesso. 

Condividi l'accesso dell'account di servizio tramite Google Sheets. Immagine dell'autore.

Installare le librerie client

Google fornisce librerie client ufficiali che semplificano il lavoro con la Sheets API. Gestiscono per te autenticazione, formattazione delle richieste e retry. Di fatto è più semplice e sicuro che inviare richieste HTTP grezze.

Ecco esempi di installazione per i linguaggi più diffusi:

Python

pip install google-api-python-client google-auth google-auth-oauthlibOfferto da

Node.js

npm install googleapisOfferto da

Java (aggiungi la libreria client con Maven)

<dependency>
  <groupId>com.google.apis</groupId>
  <artifactId>google-api-services-sheets</artifactId>
</dependency>Offerto da

Nota: Le librerie client fanno risparmiare tempo di configurazione e riducono gli errori man mano che il progetto cresce.

Operazioni principali sui dati

L'API di Google Sheets si usa principalmente per leggere, scrivere, aggiornare e formattare i dati di un foglio di calcolo. Vediamole: 

Lettura dei dati dai fogli di calcolo

Per leggere dati da un Google Sheet, ti servono due cose: l'ID del foglio di calcolo e l'intervallo di celle a cui vuoi accedere.

Lo spreadsheet ID si trova nell'URL di Google Sheets. È la lunga stringa tra /d/ e /edit. Indica all'API da quale foglio leggere.

Ad esempio, se l'URL del mio Sheet è: https://docs.google.com/spreadsheets/d/1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI/edit?gid=0#gid=0  

In questo caso, lo Spreadsheet ID è: 1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI

ID del foglio di calcolo. Immagine dell'autore.

L'intervallo si scrive in notazione A1, che descrive le celle con le lettere delle colonne e i numeri delle righe. Ad esempio:

• A1 legge una singola cella

• A1:C10 legge un blocco di celle

• Sheet1!A:A legge un'intera colonna

• Sheet1!1:1 legge un'intera riga

Per recuperare i valori, l'API offre due metodi principali:

• spreadsheets.values.get legge i dati da un singolo intervallo. Usalo quando sai esattamente quale tabella o blocco ti serve. 

• spreadsheets.values.batchGet legge dati da più intervalli in un'unica richiesta. Usalo quando vuoi dati da più punti in una volta sola, ad esempio totali da un foglio e dettagli da un altro.

La lettura non modifica il foglio: restituisce solo i valori per usarli altrove nella tua app. Puoi impiegarla per alimentare dashboard, esportare dati per analisi e generare report automatici.

Scrittura dei dati nei fogli di calcolo

La scrittura funziona in modo simile alla lettura. Ti servono ancora l'ID del foglio e un intervallo, ma questa volta invii anche i valori da scrivere.

L'API di Google Sheets offre due metodi principali:

• spreadsheets.values.update: Usalo quando vuoi scrivere dati in un intervallo specifico e sovrascrivere ciò che c'è già. Ad esempio, se vuoi sostituire la riga d'intestazione di una tabella con nuovi nomi di colonna, update è la scelta giusta. I valori inviati sostituiranno le celle esistenti in quell'intervallo.

• spreadsheets.values.append: Usalo quando vuoi aggiungere nuove righe senza toccare i dati esistenti. È utile quando i tuoi dati crescono nel tempo, ad esempio per registrare metriche giornaliere, aggiungere nuovi record o archiviare risposte di moduli. L'API inserisce automaticamente i nuovi valori dopo l'ultima riga non vuota.

Opzioni di input dei valori

Quando scrivi dati, devi anche scegliere come Google Sheets deve trattare i valori inviati. Questo è controllato da ValueInputOption.

• RAW memorizza il valore esattamente come lo invii

• USER_ENTERED tratta il valore come se fosse digitato nel foglio

Ad esempio, se invii =SUM(1,2):

• Con RAW, viene salvato come testo semplice

• Con USER_ENTERED, viene valutato come formula

Sovrascrivere vs. aggiungere dati

La scelta tra update e append dipende da come è strutturato il tuo foglio.

Usa update quando:

• La posizione dei dati è fissa
• Stai sostituendo intestazioni o celle note

Usa append quando:

• I dati crescono nel tempo
• Vuoi evitare di sovrascrivere le righe esistenti

Operazioni in batch

Le operazioni in batch ti permettono di raggruppare più modifiche in un'unica richiesta API. Questo riduce il numero di chiamate e aiuta a rimanere entro i limiti di utilizzo.

Ci sono due modelli comuni di batch nella Google Sheets API.

Per lavorare con i valori, puoi usare:

• spreadsheets.values.batchGet per leggere più intervalli in una volta

• spreadsheets.values.batchUpdate per scrivere su più intervalli in un'unica richiesta

Per modifiche strutturali e di formattazione, usa spreadsheets.batchUpdate. È il metodo di batch più utile e supporta molte azioni in una singola richiesta.

Con spreadsheets.batchUpdate puoi combinare modifiche come:

• Creare o eliminare fogli
• Rinominare un foglio di calcolo o una scheda
• Bloccare le righe d'intestazione
• Modificare le larghezze delle colonne
• Applicare formattazioni
• Aggiornare più intervalli contemporaneamente

Ad esempio, invece di inviare richieste separate per rinominare un foglio di calcolo e creare una nuova scheda, puoi fare entrambe le cose in una sola chiamata batchUpdate. È più veloce e più semplice da gestire quando i flussi di lavoro crescono.

Puoi usare le operazioni in batch per impostare report, applicare formattazioni coerenti o apportare modifiche su larga scala a un foglio.

Aggiornare ed eliminare dati

Aggiornare i dati significa sostituire i valori in celle o intervalli specifici. Di solito si fa quando vuoi aggiornare numeri, KPI o sovrascrivere un'area di output fissa nel foglio.

Per aggiornare valori esistenti, usa spreadsheets.values.update. Qui specifichi l'intervallo di destinazione e invii i nuovi valori, e i dati esistenti in quell'intervallo vengono sostituiti.

Svuotare vs. eliminare dati

Svuotare i dati ed eliminarli non è la stessa cosa:

Svuotare rimuove i valori nelle celle ma mantiene foglio, layout e formattazione intatti. Usa spreadsheets.values.clear quando vuoi svuotare un intervallo senza toccare la struttura.

Esempio: svuotare una sezione di un vecchio report prima di scrivere nuovi dati nelle stesse celle.

Eliminare rimuove un'intera scheda. Si fa usando spreadsheets.batchUpdate con una richiesta deleteSheet. Eliminare una scheda rimuove in modo permanente i suoi dati e la sua struttura.

Poiché l'eliminazione è irreversibile, è meglio usarla con parsimonia e solo quando sei certo che i dati non servono più.

Funzionalità avanzate

Oltre a leggere e scrivere dati, l'API di Google Sheets ti permette di controllare l'aspetto e il comportamento dei fogli. Questo rende possibile automatizzare formattazioni e regole visive su larga scala.

Formattazione e formattazione condizionale

L'API di Google Sheets ti consente di applicare la formattazione delle celle via codice invece che dall'interfaccia. Questo include stili del testo, colori, formati numerici e modifiche al layout.

Tutte le modifiche di formattazione vengono inviate come richieste JSON usando spreadsheets.batchUpdate. Ogni richiesta descrive cosa cambiare e dove applicarlo.

Attività di formattazione comuni includono:

• Mettere in grassetto le righe di intestazione
• Applicare formati numerici per valuta o percentuali
• Regolare le larghezze delle colonne
• Impostare colori di sfondo per intervalli specifici

Ad esempio, una richiesta di formattazione può prendere di mira la prima riga di un foglio e renderla in grassetto con un colore di sfondo chiaro. La richiesta usa indici a partire da zero, dove la riga 0 rappresenta la prima riga.

Formattazione condizionale

La formattazione condizionale ti consente di stilizzare automaticamente le celle in base ai loro valori. Se vuoi che Sheets evidenzi i dati importanti senza revisione manuale, la formattazione condizionale può aiutare. 

Usando l'API, le regole di formattazione condizionale sono definite in JSON e applicate tramite spreadsheets.batchUpdate.

Puoi usarla per:

• Evidenziare in rosso i valori negativi
• Segnalare valori sopra o sotto una soglia
• Stilizzare automaticamente le righe che soddisfano certe condizioni

Ad esempio, puoi definire una regola che evidenzia qualsiasi valore inferiore a 0 in una colonna specifica. Una volta applicata, la formattazione si aggiorna automaticamente al variare dei dati.

Tabelle pivot e aggregazione dei dati

L'API di Google Sheets può creare e aggiornare tabelle pivot tramite codice. Le pivot riassumono grandi dataset senza modificare i dati originali, utile per report e analisi.

Devi solo definire le tabelle pivot con richieste JSON e applicarle con spreadsheets.batchUpdate. Queste richieste descrivono come i dati vanno raggruppati, riassunti e mostrati.

Tramite l'API puoi:

• Scegliere quali colonne diventano etichette di riga
• Selezionare metodi di aggregazione come somma, conteggio o media
• Controllare dove appare la tabella pivot
• Aggiornare o modificare le pivot quando si aggiungono nuovi dati

Ad esempio, puoi raggruppare le righe per parola chiave e calcolare automaticamente clic e impression totali. Al variare dei dati di base, la pivot si aggiorna automaticamente.

Connected Sheets e integrazione con BigQuery

Connected Sheets permette a Google Sheets di lavorare direttamente con BigQuery. BigQuery gestisce grandi dataset, mentre Sheets viene usato per analisi e report. 

Invece di copiare milioni di righe in un foglio, Connected Sheets esegue query su BigQuery e mostra i risultati. Mantiene i fogli veloci e reattivi anche con dataset molto grandi.

La connessione si crea da dentro Google Sheets. L'API di Google Sheets non viene usata per configurarla.

Ecco come funziona:

• I dati risiedono in una tabella BigQuery
• Colleghi un Google Sheet a quella tabella
• Sheets esegue query e mostra i risultati
• I dati possono essere aggiornati senza esportare file

Una volta connesso, puoi creare tabelle pivot, applicare formule e creare report direttamente in Sheets.

Autenticazione e autorizzazioni

L'accesso a Connected Sheets è controllato tramite Google Cloud Identity and Access Management.

L'account che collega Sheets a BigQuery deve avere:

• Autorizzazione BigQuery Data Viewer
• Autorizzazione BigQuery Job User
• Accesso al Google Sheet

L'autenticazione è gestita automaticamente dall'interfaccia di Google Sheets.

Tieni però presenti alcuni limiti. Sebbene la Sheets API possa leggere dati da Connected Sheets e applicare formattazioni o costruire pivot, non può modificare la query BigQuery sottostante né scrivere dati negli intervalli supportati da BigQuery.

Per questo Connected Sheets è ideale per analisi e reporting, non per inserire o modificare dati grezzi.

Uso di strumenti di integrazione no-code

Non tutti i flussi di lavoro richiedono codice personalizzato. Vari strumenti no-code e low-code si connettono direttamente alla Google Sheets API e gestiscono per te i dettagli tecnici. Le tre opzioni più popolari includono:

• Apipheny
• Supermetrics
• Funnel

Questi strumenti offrono interfacce visive per selezionare sorgenti dati, impostare pianificazioni e inviare risultati a Google Sheets. Gestiscono in background autenticazione, richieste API e gestione degli errori.

Sono quindi adatti a marketer e analisti che necessitano di pipeline dati affidabili senza scrivere codice. Inoltre riducono i tempi di configurazione per casi d'uso comuni di reportistica e dashboard.

Prezzi e limiti dell'API

Per la maggior parte dei progetti, puoi usare l'API di Google Sheets gratuitamente. La cosa principale è capire come funzionano i limiti di utilizzo.

Panoramica dei prezzi dell'API

Google non addebita per richiesta o per azione sul foglio. L'uso è regolato da quote. 

Finché il tuo progetto rimane entro tali limiti, puoi usare l'API senza costi. Se li superi, le richieste vengono temporaneamente bloccate finché l'uso non diminuisce o i limiti non vengono aumentati.

Limiti di utilizzo e quote

La Google Sheets API impone limiti per mantenere la stabilità delle prestazioni e prevenire abusi. Questi limiti si applicano di solito per progetto e, in alcuni casi, per utente.

La maggior parte dei progetti incontra due tipi principali di limiti:

1. Richieste al minuto: Questo limite controlla quante chiamate API il tuo progetto può inviare in poco tempo. Troppe richieste piccole inviate tutte insieme possono generare errori temporanei.

Per impostazione predefinita, la Google Sheets API consente:

I limiti riguardano soprattutto quante richieste mandi al minuto, non il totale giornaliero.

Per rimanere entro i limiti ed evitare problemi:

• Raggruppa più aggiornamenti in un'unica richiesta
• Evita letture ripetute per piccoli cambiamenti
• Esegui caching dei dati invece di riscaricarli
• Monitora l'utilizzo nella Google Cloud Console e intervieni per tempo

Ottimizzazione delle prestazioni e gestione delle quote

Quando automatizzi Google Sheets, i problemi di prestazioni derivano di solito dall'invio di troppe richieste troppo rapidamente. Quindi è importante capire come funzionano le quote. 

Comprendere quote e rate limit dell'API

Google applica quote per limitare quante richieste il tuo progetto può inviare in un determinato periodo. Alcuni limiti si applicano per progetto, altri per utente.

Questi limiti influiscono direttamente sui flussi automatizzati. Se il tuo script invia troppe richieste troppo in fretta, l'API inizia a restituire errori e il flusso si interrompe. Succede spesso quando gli script:

• Aggiornano le righe una alla volta
• Leggono ripetutamente grandi intervalli
• Vengono eseguiti troppo spesso senza batching

Monitorare l'uso aiuta a individuare presto i problemi. Nella Google Cloud Console puoi vedere quanto il tuo progetto è vicino ai suoi limiti e individuare picchi improvvisi di attività. Ecco come:

• Apri il tuo progetto.
• Vai su API e servizi > API e servizi abilitati 
• Clicca su Google Sheets API.
• Apri Quote e limiti di sistema.

Se noti picchi improvvisi, di solito indicano pattern di richieste inefficienti.

Quote e limiti di sistema. Immagine dell'autore.

Implementare l'exponential backoff

Anche script ben scritti possono incontrare errori API temporanei. I più comuni sono facili da individuare:

• Gli errori 429 significano che sono state inviate troppe richieste in poco tempo
• Gli errori 5xx indicano un problema temporaneo del server dell'API

Questi errori spesso si risolvono da soli. Ritentare subito può peggiorare il problema.

L'exponential backoff è lo standard per ritentare in modo sicuro. Invece di riprovare subito, lo script aspetta prima di riprovare. Il tempo di attesa aumenta dopo ogni fallimento.

Un semplice schema di backoff è questo:

• Invia una richiesta
• Se ricevi un errore 429 o 5xx, attendi un secondo
• Riprova
• Se fallisce ancora, attendi due secondi, poi quattro, poi otto
• Interrompi dopo un tempo massimo di attesa o un numero massimo di retry

Questo approccio riduce la pressione sull'API e aumenta le probabilità di un retry riuscito.

Exponential backoff in pratica

Ecco un semplice esempio in Python che ritenta una richiesta usando l'exponential backoff:

import time
from googleapiclient.errors import HttpError

def run_with_backoff(callable_request, max_retries=5):
    delay = 1

    for attempt in range(max_retries):
        try:
            return callable_request()
        except HttpError as e:
            status = getattr(e.resp, "status", None)

            if status in [429, 500, 502, 503, 504]:
                time.sleep(delay)
                delay = min(delay * 2, 32)
                continue

            raise

    raise RuntimeError("Request failed after retries.")Offerto da

Puoi quindi incapsulare qualsiasi chiamata API con questo helper:

result = run_with_backoff(
    lambda: service.spreadsheets().values().get(
        spreadsheetId=spreadsheet_id,
        range="Report!A1:E100"
    ).execute()
)Offerto da

In questo modo il tuo script non fallisce subito quando il problema è temporaneo, rendendo i flussi più affidabili.

Strategie di ottimizzazione

Le prestazioni migliorano quando invii meno richieste e mantieni i payload piccoli. I rallentamenti avvengono spesso quando gli script fanno troppo lavoro in una sola chiamata.

Ecco le tecniche più efficaci per prevenire rallentamenti:

Richieste in batch

I metodi batch come spreadsheets.values.batchGet, spreadsheets.values.batchUpdate e spreadsheets.batchreadsheets.batchUpdate ti permettono di combinare molte azioni in un'unica richiesta. È il maggior guadagno in termini di prestazioni.

Caching

Leggere ripetutamente gli stessi dati fa perdere tempo e quota. Recupera una volta i metadati del foglio o gli ID dei fogli e riutilizzali durante l'esecuzione dello script.

Paginazione

Alcune risposte dell'API restituiscono dati in pagine. Elabora una pagina alla volta invece di caricare tutto in una volta. Evita timeout e problemi di memoria con dataset grandi.

Compressione gzip

La maggior parte delle librerie client di Google e dei client HTTP supportano automaticamente la compressione gzip. La compressione riduce la dimensione quando le risposte sono grandi, ad esempio leggendo intervalli ampi o recuperando metadati del foglio.

Risposte parziali

Quando disponibile, richiedi solo i campi necessari invece dell'intera risorsa. Risposte più piccole sono più veloci e usano meno banda.

Ridurre la dimensione del payload

Evita di scrivere una cella alla volta. Scrivi intervalli completi. Salta gli aggiornamenti di formattazione se nulla è cambiato e non reinviare dati inutilmente.

Una regola semplice funziona bene: se uno script scorre le righe e fa una chiamata API dentro quel ciclo, non scalerà. Raggruppa il lavoro, riduci il numero di richieste e mantieni i payload piccoli.

Gestione errori e troubleshooting

Gli errori fanno parte del lavoro con qualsiasi API. Quindi vediamo come risolvere velocemente i problemi e mantenere l'automazione affidabile. 

Problemi comuni di autenticazione

I problemi di autenticazione sono la fonte più comune di errori quando si inizia con la Google Sheets API. Nella maggior parte dei casi derivano dalla configurazione, non da bug nel codice.

Problemi comuni includono:

• Errori di permessi negati: il foglio non è stato condiviso con l'email dell'account di servizio, oppure l'utente non ha concesso gli scope OAuth richiesti
• Credenziali non valide o file non trovato: il percorso del file di chiave JSON è errato o il nome del file non corrisponde
• API non abilitata: la Google Sheets API non è abilitata nello stesso progetto Google Cloud delle credenziali

I problemi con OAuth spesso si verificano quando gli scope non corrispondono all'azione che vuoi eseguire. Ad esempio, gli scope di sola lettura non consentono scritture.

I problemi con gli account di servizio di solito derivano da condivisioni mancanti. Un account di servizio non può vedere alcun foglio se non è esplicitamente condiviso con il suo indirizzo email.

Errori di formattazione dei dati e delle richieste

Gli errori di richiesta di solito accadono quando i dati inviati non corrispondono a quanto atteso dall'API. I messaggi di errore sono spesso descrittivi, ma possono essere comunque spiazzanti all'inizio.

Cause comuni includono:

• Notazione A1 non valida: nomi dei fogli scritti male o intervalli inesistenti

• Struttura dati errata: i valori devono essere inviati come array bidimensionali, anche per una singola riga

• Incongruenze di tipo: numeri, date e formule si comportano in modo diverso a seconda di valueInputOption

Quando fai troubleshooting, leggi sempre l'intera risposta d'errore perché le API di Google in genere indicano il campo esatto che non ha superato la validazione.

Disponibilità del servizio e sfide di performance

Come qualsiasi servizio cloud, la Google Sheets API può occasionalmente restituire errori del server come 503 Service Unavailable durante picchi di carico o interruzioni temporanee.

Questi errori sono di solito temporanei. Ma non ritentare subito perché può peggiorare le cose.

Per gestire meglio l'affidabilità:

• Ritenta solo per errori transitori come risposte 429 e 5xx
• Usa l'exponential backoff tra i tentativi
• Esegui richieste in batch per ridurre il traffico
• Monitora l'uso delle quote per evitare di raggiungere i limiti

Un'integrazione resiliente presume che alcune richieste falliranno. Retry corretti, batching e monitoraggio consentono agli script di riprendersi automaticamente e continuare a funzionare senza intervento manuale.

Best practice e sicurezza

La Google Sheets API è facile da usare, ma l'affidabilità a lungo termine dipende da come progettiamo e mettiamo in sicurezza la configurazione.

Strumenti e risorse per lo sviluppo

Google fornisce strumenti e risorse ufficiali per rendere lo sviluppo più sicuro e semplice:

• Il Google Workspace APIs Explorer ti permette di testare le richieste della Sheets API direttamente dal browser. Puoi sperimentare gli endpoint, vedere i parametri richiesti e ispezionare le risposte senza scrivere codice. 
• Le guide quickstart della Sheets API illustrano le configurazioni di base per diversi linguaggi. Mostrano l'autenticazione, una semplice chiamata di lettura o scrittura e i passaggi comuni di configurazione. 
• La documentazione ufficiale riflette il comportamento attuale e i limiti noti.
• Un foglio di prova ti consente di sperimentare senza rischiare i dati di produzione o sovrascrivere report live.

Uso di librerie client e SDK

Google mantiene librerie client ufficiali per la Sheets API. Queste librerie gestiscono autenticazione, retry e formattazione delle richieste. Con le librerie supportate riduciamo gli errori e risparmiamo tempo. Inoltre si adattano meglio agli aggiornamenti dell'API rispetto al codice HTTP personalizzato.

I linguaggi supportati sono Python, JavaScript con Node.js, Java e Go.

Ogni libreria segue la stessa struttura core dell'API, ma alcune offrono helper specifici per linguaggio. Python e Node.js sono spesso preferiti per l'automazione grazie alla configurazione più semplice e all'ampio supporto della community.

Le librerie client si integrano bene anche con altre API di Google, utile quando un flusso coinvolge Drive, BigQuery o Gmail.

Gestione delle credenziali e sicurezza

Le credenziali controllano l'accesso ai tuoi dati, quindi gestiscile correttamente seguendo queste best practice:

• Non fare mai commit dei file di chiave nel controllo versione

• Conserva le chiavi fuori da repository pubblici

• Usa variabili d'ambiente o secret manager in produzione

• Concedi solo i permessi necessari

• Preferisci ruoli granulari rispetto a quelli troppo ampi

• Limita l'accesso degli account di servizio a compiti specifici

• Controlla picchi insoliti o pattern di accesso sconosciuti

• Ruota regolarmente le chiavi e revoca e sostituisci subito quelle esposte

Considerazioni finali 

Il miglior prossimo passo è automatizzare un'attività piccola che già fai a mano. Scegli un foglio che controlli, leggi un intervallo, poi scrivi o aggiungi dati. Una volta che funziona, pianificalo e lascialo girare da solo.

È lì che l'API di Google Sheets inizia a ripagare. 

Non ti serve da subito un sistema complesso. Un solo flusso affidabile basta per risparmiare tempo, e rende molto più facile costruire il successivo. Se vuoi affinare quelle competenze insieme all'automazione, dai un'occhiata al nostro percorso Google Sheets Fundamentals o ai corsi Introduzione a Google Sheets e Google Sheets intermedio per ottenere più valore da ogni flusso di lavoro che automatizzi.