I fogli di lavoro possono avere più fogli e ogni foglio contiene un numero qualsiasi di righe o colonne. Una cella è una posizione all'intersezione di una determinata riga e colonna e potrebbe contenere un valore dei dati. L'API Fogli Google fornisce la risorsa spreadsheets.values
per consentire la lettura e la scrittura di valori.
In questa pagina vengono descritte le nozioni di base sull'utilizzo della risorsa spreadsheets.values
. Se devi inserire righe o aggiornare la formattazione e altre proprietà di un foglio, devi utilizzare il metodo spreadsheets.batchUpdate
descritto in Aggiornare i fogli di lavoro.
Metodi
La risorsa spreadsheets.values
fornisce i seguenti metodi per leggere e scrivere valori, ciascuno per un'attività specifica:
Accesso all'intervallo | Lettura | Scrittura |
---|---|---|
Intervallo singolo | spreadsheets.values.get |
spreadsheets.values.update |
Intervalli multipli | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Aggiunta | spreadsheets.values.append |
In generale, è una buona idea combinare più letture o aggiornamenti con i metodi batchGet
e batchUpdate
(rispettivamente), poiché ciò migliora l'efficienza.
Puoi trovare esempi di ognuno di questi metodi nelle pagine di esempio Lettura di base e Scrittura di base. Per visualizzare tutti gli esempi, consulta la pagina di riepilogo degli esempi.
Letto
Per leggere i valori dei dati da un foglio, sono necessari l'ID del foglio di lavoro e la notazione A1 per l'intervallo. Se specifichi l'intervallo senza ID foglio (A1:B2
), la richiesta viene eseguita sul primo foglio del foglio di lavoro. Per ulteriori informazioni sugli ID fogli di lavoro e sulla notazione A1, consulta la Panoramica dell'API Fogli Google.
Diversi parametri di query facoltativi controllano il formato dell'output:
Parametro formato | Valore predefinito |
---|---|
majorDimension |
RIGHE |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Tieni presente che devi usare dateTimeRenderOption
solo se valueRenderOption
non è FORMATTED_VALUE
.
Non esiste un limite esplicito alla quantità di dati restituiti. Gli errori non restituiscono dati. Le righe e le colonne finali vuote vengono omesse.
Di seguito sono descritti i metodi singolo e batch get. Per esempi di operazioni di lettura di base, consulta Lettura di base.
Leggi un singolo intervallo
Per leggere un singolo intervallo di valori da un foglio di lavoro, utilizza una richiesta spreadsheets.values.get
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
La risposta a questa richiesta viene restituita come oggetto ValueRange
.
Lettura di più intervalli
Per leggere più intervalli di valori discontinui da un foglio di lavoro, utilizza una richiesta spreadsheets.values.batchGet
che ti consenta di specificare diversi intervalli da recuperare:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
La risposta a questa richiesta viene restituita come oggetto BatchGetValuesResponse
contenente spreadsheetId
e un elenco di oggetti ValueRange
.
Scrittura
Per scrivere in un foglio sono necessari l'ID del foglio di lavoro, l'intervallo di celle nella notazione A1 e i dati che vuoi scrivere all'interno di un oggetto corpo della richiesta appropriato. Per ulteriori informazioni sugli ID fogli di lavoro e sulla notazione A1, consulta la panoramica dell'API Fogli Google.
Gli aggiornamenti richiedono un parametro ValueInputOption
valido.
Per gli aggiornamenti singolari, questo è un parametro di query obbligatorio. Per gli aggiornamenti batch, questo parametro è obbligatorio nel corpo della richiesta. L'elemento ValueInputOption
controlla
il modo in cui i dati di input devono essere interpretati e se le stringhe di input
vengono analizzate o meno, come descritto nella seguente tabella:
ValueInputOption |
Descrizione |
---|---|
RAW |
L'input non viene analizzato e viene inserito come stringa. Ad esempio, l'input "=1+2" inserisce la stringa, non la formula, "=1+2" nella cella. I valori non stringa, come booleani o numeri, vengono sempre gestiti come RAW . |
USER_ENTERED |
L'input viene analizzato esattamente come se fosse stato inserito nell'interfaccia utente di Fogli. Ad esempio, "1 marzo 2016" diventa una data e "=1+2" diventa una formula. È anche possibile dedurre i formati, quindi "100,15 $" diventa un numero con formattazione della valuta. |
Di seguito sono descritti i metodi di aggiornamento singolare e batch. Per esempi di operazioni di scrittura di base, consulta Scrittura di base.
Scrivere in un singolo intervallo
Per scrivere dati in un singolo intervallo, utilizza una richiesta spreadsheets.values.update
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Il corpo della richiesta di aggiornamento deve essere un oggetto ValueRange
, anche se l'unico campo obbligatorio è values
. Se range
è specificato, deve corrispondere all'intervallo nell'URL. In ValueRange
, puoi specificare facoltativamente majorDimension
.
Per impostazione predefinita, viene utilizzato il criterio ROWS
. Se COLUMNS
è specificato, ogni array interno viene scritto in una colonna anziché in una riga.
Durante l'aggiornamento, i valori senza dati vengono ignorati. Per cancellare i dati, utilizza una stringa vuota ("").
Scrivere più intervalli
Se vuoi scrivere più intervalli discontinui, puoi utilizzare una richiesta spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Il corpo della richiesta di aggiornamento batch deve essere un oggetto BatchUpdateValuesRequest
, che contiene un ValueInputOption
e un elenco di oggetti ValueRange
(uno per ogni intervallo scritto). Ogni oggetto ValueRange
specifica i propri
range
, majorDimension
e i propri dati di input.
Aggiungi valori
Per aggiungere dati dopo una tabella di dati in un foglio, utilizza una richiesta spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Il corpo della richiesta di aggiornamento deve essere un oggetto ValueRange
, anche se l'unico campo obbligatorio è values
. Se range
è specificato, deve corrispondere all'intervallo nell'URL. In ValueRange
, puoi specificare facoltativamente majorDimension
.
Per impostazione predefinita, viene utilizzato il criterio ROWS
. Se COLUMNS
è specificato, ogni array interno viene scritto in una colonna anziché in una riga.
L'intervallo di input viene utilizzato per cercare dati esistenti e trovare una "tabella" all'interno
dell'intervallo. I valori vengono aggiunti alla riga successiva della tabella, a partire dalla prima colonna della tabella. Ad esempio, considera Sheet1
che ha il seguente aspetto:
A | B | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
Nel foglio sono presenti due tabelle: A1:C2
e B4:D6
. I valori aggiunti iniziano da B7
per tutti i seguenti input range
:
Sheet1
, perché esaminerà tutti i dati del foglio e determinerà che la tabella inB4:D6
è l'ultima.B4
oC5:D5
, perché entrambi nella tabellaB4:D6
.B2:D4
, perché l'ultima tabella nell'intervallo è la tabellaB4:D6
(nonostante contenga anche la tabellaA1:C2
).A3:G10
, perché l'ultima tabella dell'intervallo è la tabellaB4:D6
(nonostante inizi prima e finisca dopo).
I seguenti input di range
non inizieranno a scrivere in B7
:
A1
inizierà a scrivere alle oreA3
, perché è nella tabellaA1:C2
.E4
inizierà a scrivere alle oreE4
, perché non è presente in nessuna tabella. (A4
inizierebbe a scrivere anche aA4
per gli stessi motivi).
Inoltre, puoi scegliere se sovrascrivere i dati esistenti dopo una tabella o inserire nuove righe per i nuovi dati. Per impostazione predefinita, l'input
sovrascrive i dati dopo la tabella. Per scrivere i nuovi dati in nuove righe, utilizza InsertDataOption
e specifica insertDataOption=INSERT_ROWS
.
Per scoprire di più sui limiti di celle e righe in Fogli, consulta File archiviabili su Google Drive.