I fogli di lavoro possono avere più fogli e ogni foglio può avere un numero qualsiasi di righe o colonne. Una cella è un punto all'intersezione di una determinata riga e colonna e potrebbe contenere un valore di dati. L'API Fogli Google fornisce la risorsa spreadsheets.values
per abilitare la lettura e la scrittura dei valori.
In questa pagina vengono descritte le nozioni di base per l'utilizzo della risorsa spreadsheets.values
. Se devi inserire righe o aggiornare la formattazione e altre proprietà in 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 la lettura e la scrittura di valori, ciascuno per un'attività
specifica:
Accesso a un intervallo | Risorse | Scrittura |
---|---|---|
Intervallo singolo | spreadsheets.values.get |
spreadsheets.values.update |
Più intervalli | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Aggiunta | spreadsheets.values.append |
In generale, è consigliabile combinare più letture o aggiornamenti con i metodi batchGet
e batchUpdate
(rispettivamente), per migliorare 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 della panoramica degli esempi.
Leggi
Per leggere i valori dei dati da un foglio, sono necessari l'ID foglio di lavoro e la notazione A1
per l'intervallo. Se specifichi l'intervallo senza l'ID foglio (A1:B2
), la richiesta viene eseguita sul primo foglio del foglio di lavoro. Per ulteriori informazioni sugli ID dei 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 singolare 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
.
Leggi più intervalli
Per leggere più intervalli di valori discontinui da un foglio di lavoro, utilizza una richiesta spreadsheets.values.batchGet
che consente 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
che contiene spreadsheetId
e un elenco di oggetti ValueRange
.
Scrivi
Per scrivere in un foglio, sono necessari l'ID 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 dei fogli di lavoro e sulla notazione A1, consulta la panoramica dell'API Fogli Google.
Gli aggiornamenti richiedono un parametro ValueInputOption
valido.
Per gli aggiornamenti singoli, questo è un parametro di query obbligatorio. Per aggiornamenti batch,
questo parametro è obbligatorio nel corpo della richiesta. L'elemento ValueInputOption
stabilisce la modalità di interpretazione dei dati di input 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 nella cella la stringa e non la formula "=1+2". I valori non stringa come i valori booleani o i 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. Possono anche essere dedotti i formati, in modo che "100,15 $" diventi un numero con la 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. Nel ValueRange
, puoi specificare se vuoi
il majorDimension
.
Per impostazione predefinita, viene utilizzato ROWS
. Se viene specificato COLUMNS
, 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 ("").
Scrivi 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 dati range
, majorDimension
e 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. Nel ValueRange
, puoi specificare se vuoi
il majorDimension
.
Per impostazione predefinita, viene utilizzato ROWS
. Se viene specificato COLUMNS
, 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 di quell'intervallo. I valori vengono aggiunti alla riga successiva della tabella, a partire dalla prima colonna. 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 inizieranno da B7
per tutti i seguenti input range
:
Sheet1
, perché esaminerà tutti i dati del foglio e determinerà che la tabella all'indirizzoB4:D6
è l'ultima tabella.B4
oC5:D5
, perché si trovano 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 nell'intervallo è la tabellaB4:D6
(anche se inizia prima e finisce dopo).
I seguenti input range
non inizieranno a scrivere in B7
:
A1
inizierà a scrivere conA3
, perché è nella tabellaA1:C2
.E4
inizierà a scrivere conE4
, perché non è presente in nessuna tabella. AncheA4
inizierà a scrivere suA4
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 saperne di più sui limiti di celle e righe in Fogli, vedi File archiviabili su Google Drive.