Oltre ai dati dei valori contenuti nelle celle, un foglio di lavoro include molti altri tipi di dati, ad esempio:
- Dimensioni
- Formati delle celle e bordi
- Intervalli denominati
- Intervalli protetti
- Formattazione condizionale
Questi sono alcuni dei molti tipi di dati che controllano l'aspetto e il funzionamento di un foglio di lavoro. Il metodo spreadsheets.batchUpdate
ti consente di aggiornare uno qualsiasi di questi dettagli del foglio di lavoro. Le modifiche vengono raggruppate in batch in modo che, se una richiesta non va a buon fine, non venga scritta nessuna delle altre modifiche (potenzialmente dipendenti).
In questa pagina vengono descritte le nozioni di base per l'utilizzo del metodo spreadsheets.batchUpdate
. Se devi leggere e scrivere i dati dei valori delle celle, puoi anche utilizzare la risorsa spreadsheets.values
descritta in Lettura e scrittura dei valori delle celle.
Categorie di operazioni
Le specifiche operazioni supportate da spreadsheets.batchUpdate
possono essere raggruppate
nelle seguenti ampie categorie:
Categoria | Descrizione |
---|---|
Aggiungi (e Duplica) | Aggiungi nuovi oggetti (a volte basati su vecchi oggetti, come nelle richieste duplicate). |
Update (e Set) | Aggiorna determinate proprietà di un oggetto, di solito lasciando invariate le vecchie proprietà (mentre una richiesta Set sovrascrive i dati precedenti). |
Elimina | Rimuovi oggetti. |
Queste categorie vengono utilizzate nella prossima sezione per descrivere il comportamento di operazioni specifiche.
Operazioni di aggiornamento batch
Il metodo spreadsheets.batchUpdate
utilizza uno o più oggetti Request, ognuno dei quali specifica un singolo tipo di richiesta da eseguire. Esistono molti tipi diversi di richieste. Ecco un'analisi dei tipi di richieste
raggruppati in diverse categorie.
Esistono anche alcune richieste aggiuntive che imitano le azioni degli utenti per manipolare i dati:
- AutoFillRequest
- CutPasteRequest
- CopyPasteRequest
- FindReplaceRequest
- PasteDataRequest
- TextToColumnsRequest
- SortRangeRequest
Limiti
Per saperne di più sui limiti di celle e righe in Fogli Google, vedi File archiviabili su Google Drive.
Maschere dei campi
Molte delle richieste di "aggiornamento" richiedono maschere dei campi. Si tratta di un elenco di campi delimitati da virgole per aggiornare solo alcuni campi di un oggetto, lasciando invariati gli altri campi. Una maschera di campo *
viene trattata come
un carattere jolly ed è un'abbreviazione per specificare ogni campo di un messaggio, il che significa che
un campo potrebbe tornare allo stato predefinito se non specifichi un valore nella richiesta.
Per ulteriori informazioni sulle maschere di campo, consulta Utilizzare le maschere di campo.
Nell'esempio seguente viene utilizzato UpdateSpreadsheetPropertiesRequest
per aggiornare solo il titolo di un foglio di lavoro:
Richiesta:
POST .../v4/spreadsheets/spreadsheetId:batchUpdate
Corpo della richiesta:
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}
Sostituisci TITLE con il nuovo titolo del foglio di lavoro.
Risposte
Quando aggiorni un foglio di lavoro, alcuni tipi di richieste potrebbero restituire risposte. Questi vengono restituiti in un array e ogni risposta occupa lo stesso indice della richiesta corrispondente. Alcune richieste non hanno risposte e per queste la risposta è vuota.
In genere, le richieste "add" hanno risposte che restituiscono informazioni come l'ID dell'oggetto aggiunto. Per l'elenco delle risposte supportate, vedi Risposte.
Esempio
Il seguente esempio di codice esegue queste azioni:
- Aggiorna il titolo del foglio di lavoro utilizzando la variabile
title
. - Trova e sostituisci i valori delle celle nel foglio di lavoro utilizzando le variabili
find
ereplacement
.