I fogli di lavoro possono avere più fogli e ogni foglio può avere un numero qualsiasi di righe
o colonne. Una cella è una posizione nell'area
intersezione di una determinata riga e colonna e potrebbe contenere un valore di dati. La
L'API Fogli Google fornisce
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
devi utilizzare
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
per un'attività specifica:
Accesso a un intervallo | 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
batchGet
e batchUpdate
(rispettivamente), mentre questo migliora
efficienza operativa.
Puoi trovare esempi di ognuno di questi metodi nella Guida di base reading e Nozioni di base e scrivere pagine di esempio. Per visualizzare tutti gli esempi, consulta alla pagina Panoramica degli esempi.
Leggi
Per leggere i valori dei dati da un foglio, sono necessari l'ID del foglio di lavoro e l'A1
notazione per l'intervallo. Specifica dell'intervallo senza l'ID foglio (A1:B2
)
significa che la richiesta viene eseguita sul primo foglio del foglio di lavoro. Per ulteriori informazioni
informazioni sugli ID dei fogli di lavoro e sulla notazione A1, consulta l'articolo sull'API Fogli Google
Panoramica.
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 modelli per le operazioni di lettura, consulta Lettura di base.
Leggi un singolo intervallo
Per leggere un singolo intervallo di valori da un foglio di lavoro, utilizza un
spreadsheets.values.get
richiesta:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
La risposta a questa richiesta viene restituita come
ValueRange
.
Leggi più intervalli
Per leggere più intervalli di valori non consecutivi da un foglio di lavoro, utilizza un
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
BatchGetValuesResponse
che contiene spreadsheetId
e un elenco di
ValueRange
di oggetti strutturati.
Scrittura
Per scrivere in un foglio, ti serve l'ID foglio di lavoro, l'intervallo di celle in A1 e i dati che vuoi scrivere nel corpo di una richiesta appropriata . Per ulteriori informazioni sugli ID dei fogli di lavoro e sulla notazione A1, consulta Panoramica dell'API Fogli Google.
Gli aggiornamenti richiedono un valore
ValueInputOption
.
Per gli aggiornamenti singolari, questo è un parametro di query obbligatorio. Per gli aggiornamenti batch,
è obbligatorio specificare questo parametro
nel corpo della richiesta. I controlli di ValueInputOption
il modo in cui i dati di input devono essere interpretati e se le stringhe di input vengono analizzate
non come descritto nella tabella seguente:
ValueInputOption |
Descrizione |
---|---|
RAW |
L'input non viene analizzato e viene inserito come stringa. Ad esempio, l'input "=1+2" posiziona la stringa, non la formula "=1+2" nella cella. 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 mar 2016" diventa una data e "=1+2" diventa una formula. Possono anche essere dedotti i formati, quindi "$ 100,15" diventa un numero con la formattazione della valuta. |
Di seguito sono descritti i metodi di aggiornamento singolare e batch. Per esempi di modelli per le operazioni di scrittura, consulta Scrittura di base.
Scrivere in un singolo intervallo
Per scrivere dati in un singolo intervallo, utilizza un
spreadsheets.values.update
richiesta:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Il corpo della richiesta di aggiornamento deve essere un
ValueRange
, sebbene l'unico campo obbligatorio sia values
. Se range
è specificato,
deve corrispondere all'intervallo dell'URL. Nel ValueRange
, puoi specificare se vuoi
le sue
majorDimension
Per impostazione predefinita, viene utilizzato ROWS
. Se COLUMNS
è specificato, ogni array interno viene
vengono scritte in una colonna anziché in una riga.
Durante l'aggiornamento, i valori senza dati vengono ignorati. Per cancellare i dati, utilizza un campo stringa ("").
Scrivi più intervalli
Se vuoi scrivere più intervalli discontinui, puoi utilizzare un
spreadsheets.values.batchUpdate
richiesta:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Il corpo della richiesta di aggiornamento batch deve essere un
BatchUpdateValuesRequest
che contiene un ValueInputOption
e un elenco di
ValueRange
oggetti (uno per ogni intervallo scritto). Ogni oggetto ValueRange
specifica il proprio
range
, majorDimension
e dati di input.
Aggiungi valori
Per aggiungere dati dopo una tabella di dati di un foglio, utilizza un
spreadsheets.values.append
richiesta:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Il corpo della richiesta di aggiornamento deve essere un
ValueRange
, sebbene l'unico campo obbligatorio sia values
. Se range
è specificato,
deve corrispondere all'intervallo dell'URL. Nel ValueRange
, puoi specificare se vuoi
le sue
majorDimension
Per impostazione predefinita, viene utilizzato ROWS
. Se COLUMNS
è specificato, ogni array interno viene
vengono scritte in una colonna anziché in una riga.
L'intervallo di input viene utilizzato per cercare dati esistenti e trovare una "tabella" entro
quell'intervallo. I valori vengono aggiunti alla riga successiva della tabella, iniziando con
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 verranno
iniziano da B7
per tutti i seguenti input range
:
Sheet1
, perché esaminerà tutti i dati del foglio e determinerà che la tabellaB4:D6
è l'ultima.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
(nonostante iniziare prima e finire 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 un
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 il metodo
InsertDataOption
e specifica insertDataOption=INSERT_ROWS
.
Per saperne di più sui limiti di celle e righe in Fogli, vedi File archiviabili su Google Drive.