I fogli di lavoro possono avere più fogli, ciascuno con un numero qualsiasi di righe o colonne. Una cella è una posizione all'intersezione di una riga e una colonna specifiche e può contenere un valore di dati. L'API Google Sheets fornisce la risorsa spreadsheets.values
per abilitare la lettura e la scrittura dei valori.
Questa pagina descrive le nozioni di base sull'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 leggere e scrivere valori, ciascuno per un'attività specifica:
Accesso alla gamma | Lettura | Scrittura |
---|---|---|
Intervallo singolo | spreadsheets.values.get |
spreadsheets.values.update |
Più intervalli | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Aggiunta | spreadsheets.values.append |
In generale, è buona norma combinare più letture o aggiornamenti con i metodi batchGet
e batchUpdate
(rispettivamente), in quanto ciò migliora l'efficienza.
Puoi trovare esempi di ciascuno di questi metodi nelle pagine di esempi di Lettura di base e Scrittura di base. Per visualizzare tutti i campioni, consulta la pagina di panoramica dei campioni.
Leggi
Per leggere i valori dei dati da un foglio, devi avere l'ID del 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 Google Sheets.
Diversi parametri di query facoltativi controllano il formato dell'output:
Parametro di formato | Valore predefinito |
---|---|
majorDimension |
RIGHE |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Tieni presente che devi utilizzare 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.
I metodi get singolari e batch sono descritti di seguito. Per esempi di operazioni di lettura di base, consulta Lettura di base.
Leggere 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
.
Leggere più intervalli
Per leggere più intervalli di valori discontinui da un foglio di lavoro, utilizza una richiesta
spreadsheets.values.batchGet
che ti 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
.
Scrittura
Per scrivere in un foglio, devi avere l'ID del foglio di lavoro, l'intervallo di celle in notazione A1 e i dati da scrivere in un oggetto del corpo della richiesta appropriato. Per saperne di più sugli ID dei fogli di lavoro e sulla notazione A1, consulta la Panoramica dell'API Google Sheets.
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. Il parametro ValueInputOption
controlla come devono essere interpretati i dati di input e se le stringhe di input vengono analizzate o meno, come descritto nella tabella seguente:
ValueInputOption |
Descrizione |
---|---|
RAW |
L'input non viene analizzato e viene inserito come stringa. Ad esempio, l'input "=1+2" inserisce nella cella la stringa "=1+2", non la formula. I valori non stringa, come i valori booleani o numerici, vengono sempre gestiti come RAW . |
USER_ENTERED |
L'input viene analizzato esattamente come se fosse inserito nell'interfaccia utente di Fogli. Ad esempio, "1 mar 2016" diventa una data e "=1+2" diventa una formula. I formati possono anche essere dedotti, quindi "100,15 $" diventa un numero con il formato valuta. |
I metodi di aggiornamento singolo e collettivo sono descritti di seguito. 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 viene specificato range
, deve corrispondere all'intervallo nell'URL. In ValueRange
, puoi specificare facoltativamente il suo 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 ("").
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 collettivo deve essere un oggetto
BatchUpdateValuesRequest
che contiene un ValueInputOption
e un elenco di
ValueRange
oggetti (uno per ogni intervallo scritto). Ogni oggetto ValueRange
specifica i propri range
, majorDimension
e dati di input.
Aggiungere valori
Per accodare i 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 viene specificato range
, deve corrispondere all'intervallo nell'URL. In ValueRange
, puoi specificare facoltativamente il suo 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 i dati esistenti e trovare una "tabella" all'interno di questo 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 |
Il foglio contiene 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 inB4:D6
è l'ultima.B4
oC5:D5
, perché sono entrambi nella tabellaB4:D6
.B2:D4
, perché l'ultima tabella dell'intervallo è la tabellaB4:D6
(anche se contiene anche la tabellaA1:C2
).A3:G10
, perché l'ultima tabella dell'intervallo è la tabellaB4:D6
(anche se inizia prima e termina dopo).
I seguenti input range
non hanno iniziato a scrivere a B7
:
A1
inizierà a scrivere aA3
, perché si trova nella tabellaA1:C2
.E4
inizierà a scrivere aE4
, perché non è presente in nessuna tabella. AncheA4
inizierà a scrivere alle oreA4
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.