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 consentire 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 al poligono | Lettura | 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), in quanto ciò migliora
l'efficienza.
Puoi trovare esempi di ciascuno di questi metodi nelle pagine di esempio Lettura di base e Scrittura di base. Per visualizzare tutti gli esempi, consulta la pagina di panoramica degli esempi.
Leggi
Per leggere i valori dei dati da un foglio, devi disporre dell'ID foglio di lavoro e della 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 foglio 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 di recupero singolo e batch sono descritti di seguito. Per esempi di operazioni di lettura di base, consulta la sezione Lettura di base.
Lettura di 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
spreadsheets.values.batchGet
richiesta che ti consente di specificare più 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 disporre dell'ID foglio di lavoro, dell'intervallo di celle nella notazione A1 e dei dati da scrivere all'interno di un oggetto corpo della richiesta appropriato. Per saperne di più sugli ID foglio di lavoro e sulla notazione A1, consulta la panoramica dell'API Google Sheets.
Gli aggiornamenti richiedono un parametro
ValueInputOption
valido.
Per gli aggiornamenti singoli, questo è un parametro di query obbligatorio. Per gli aggiornamenti batch,
questo parametro è obbligatorio nel corpo della richiesta. I controlli ValueInputOption
determinano 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, 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. I formati possono anche essere dedotti, quindi "100,15 $" diventa un numero con la formattazione della valuta. |
Di seguito sono descritti i metodi di aggiornamento singolo e batch. Per esempi di operazioni di scrittura di base, consulta la sezione 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. Nel ValueRange
, puoi specificare facoltativamente
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 ("").
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 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 viene specificato range
, deve corrispondere all'intervallo nell'URL. Nel ValueRange
, puoi specificare facoltativamente
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 questo 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 |
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 nel 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 nell'intervallo è la tabellaB4:D6
(nonostante contenga anche la tabellaA1:C2
).A3:G10
, perché l'ultima tabella nell'intervallo è la tabellaB4:D6
(nonostante inizi prima e finisca dopo).
I seguenti input range
non inizieranno a essere scritti alle ore 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 alleA4
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.