L'API Fogli Google ti consente di scrivere valori e formule in celle, intervalli,
set di intervalli e interi fogli. Gli esempi in questa pagina mostrano come alcune operazioni di scrittura comuni possono essere eseguite con la risorsa spreadsheets.values
dell'API Fogli.
Tieni presente che è anche possibile scrivere i valori delle celle utilizzando il metodo
spreadsheet.batchUpdate
, che può essere utile se vuoi aggiornare contemporaneamente la formattazione delle celle
o altre proprietà che la risorsa
spreadsheets.values
non influisce. Ad esempio, se vuoi copiare un intervallo di celle da un foglio all'altro sovrascrivendo sia la formula della cella sia la formattazione della cella, puoi utilizzare il metodo UpdateCellsRequest
con un spreadsheet.batchUpdate
.
Tuttavia, per le scritture di valori semplici è più facile utilizzare il metodo
spreadsheets.values.update
o il metodo
spreadsheets.values.batchUpdate
.
Questi esempi sono presentati sotto forma di richieste HTTP per essere indipendenti dalla lingua. Per scoprire come implementare le scritture in diversi linguaggi utilizzando le librerie client delle API di Google, consulta Leggere e scrivere valori delle celle.
In questi esempi, il segnaposto SPREADSHEET_ID
indica dove fornire l'ID del foglio di lavoro, che può essere rilevato dall'URL del foglio di lavoro. Gli intervalli in cui scrivere vengono specificati utilizzando la notazione A1. Un intervallo di esempio è Foglio1!A1:D5.
Scrivere un singolo intervallo
A partire da un nuovo foglio di lavoro vuoto, il seguente
spreadsheets.values.update
esempio di codice mostra come scrivere i valori in un intervallo. Il parametro query ValueInputOption
è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data o meno).
Il corpo della richiesta è un
ValueRange
oggetto che descrive i valori dell'intervallo da scrivere. Il
campo
majorDimension
indica che gli array sono elenchi di valori organizzati per righe. I valori esistenti
nell'intervallo di destinazione vengono sovrascritti.
Il protocollo di richiesta è mostrato di seguito.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "3/1/2016"], ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "3/20/2016"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
La risposta è costituita da un oggetto
UpdateValuesResponse
, come questo:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}
Il foglio risultante sarà simile al seguente:
A | B | C | D | |
1 | Elemento | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 $ | 4 | 1/3/2016 |
3 | Porta | 15 $ | 2 | 15/03/2016 |
4 | Motore | 100 $ | 1 | 20/03/2016 |
5 | Totali | 135,5 $ | 7 | 20/03/2016 |
Scrivere in modo selettivo in un intervallo
Quando scrivi valori in un intervallo, è possibile evitare di modificare alcune celle esistenti impostando gli elementi dell'array corrispondenti su null
. È anche possibile cancellare una cella scrivendo una stringa vuota (""
).
A partire da un foglio contenente gli stessi dati prodotti dall'esempio precedente, il seguente
spreadsheets.values.update
codice di esempio mostra come scrivere i valori nell'intervallo B1:D4, lasciando in modo selettivo alcune celle invariate e cancellando altre. Il parametro query ValueInputOption
è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data o meno).
Il corpo della richiesta è un
ValueRange
oggetto che descrive i valori dell'intervallo da scrivere. Il campo
majorDimension
indica che gli array sono elenchi di valori organizzati per colonna.
Il protocollo di richiesta è mostrato di seguito.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!B1", "majorDimension": "COLUMNS", "values": [ [null,"$1","$2", ""], [], [null,"4/1/2016", "4/15/2016", ""] ] }
Il campo values
elenca le modifiche apportate a ogni colonna dell'intervallo. Il primo array indica che B1 deve essere lasciato invariato (a causa dell'elemento array null
), mentre B4 deve essere cancellato (stringa vuota). I valori di B2 e B3 sono stati aggiornati. Il terzo array esegue le stesse operazioni sulla colonna D, mentre il
secondo array vuoto indica che la colonna C deve essere lasciata invariata.
La risposta è costituita da un
UpdateValuesResponse
oggetto come questo:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}
Il foglio risultante sarà simile al seguente:
A | B | C | D | |
1 | Elemento | Costo | Disponibile | Data di spedizione |
2 | Ruota | 1,00 $ | 4 | 1/4/2016 |
3 | Porta | $ 2 | 2 | 15/04/2016 |
4 | Motore | 1 | ||
5 | Totali | $ 3,00 | 7 | 15/04/2016 |
Tieni presente che la riga "Totali", anche se non viene modificata direttamente da questa richiesta, cambia perché le sue celle contengono formule che dipendono dalle celle modificate.
Scrivere in più intervalli
A partire da un foglio vuoto, il seguente
spreadsheets.values.batchUpdate
esempio di codice mostra come scrivere i valori negli intervalli Foglio1!A1:A4 e
Foglio1!B1:D2. I valori esistenti nell'intervallo di destinazione vengono sovrascritti. Il corpo della richiesta è costituito da un oggetto ValueInputOption
che mostra come interpretare i dati di input e da un array di oggetti ValueRange
corrispondenti a ogni intervallo scritto. Il campo
majorDimension
determina se gli array inclusi vengono interpretati come array di colonne o righe.
Il protocollo di richiesta è mostrato di seguito.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values:batchUpdate
{ "valueInputOption": "VALUE_INPUT_OPTION", "data": [ { "range": "Sheet1!A1:A4", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door", "Engine"] ] }, { "range": "Sheet1!B1:D2", "majorDimension": "ROWS", "values": [ ["Cost", "Stocked", "Ship Date"], ["$20.50", "4", "3/1/2016"] ] } ] }
La risposta è costituita da un oggetto che elenca le statistiche delle celle aggiornate e da un array di oggetti UpdateValuesResponse
, uno per ogni intervallo aggiornato. Ad esempio:
{ "spreadsheetId":SPREADSHEET_ID
, "totalUpdatedRows": 4, "totalUpdatedColumns": 4, "totalUpdatedCells": 10, "totalUpdatedSheets": 1, "responses": [ { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!A1:A4", "updatedRows": 4, "updatedColumns": 1, "updatedCells": 4, }, { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!B1:D2", "updatedRows": 2, "updatedColumns": 3, "updatedCells": 6, } ], }
Il foglio risultante sarà simile al seguente:
A | B | C | D | |
1 | Elemento | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 $ | 4 | 1/3/2016 |
3 | Porta | |||
4 | Motore | |||
5 |
Scrivere valori senza analisi
A partire da un foglio vuoto, il seguente
spreadsheets.values.update
codice di esempio mostra come scrivere i valori nell'intervallo Foglio1!A1:E1, ma utilizza
RAW
ValueInputOption
come parametro di query per impedire l'analisi delle stringhe scritte come formule,
booleani o numeri. Vengono visualizzati come stringhe e l'allineamento del testo è giustificato nel foglio.
Il corpo della richiesta è un
ValueRange
oggetto che descrive i valori dell'intervallo da scrivere. Il
campo
majorDimension
indica che gli array sono elenchi di valori organizzati per righe. I valori esistenti
nell'intervallo di destinazione vengono sovrascritti.
Il protocollo di richiesta è mostrato di seguito.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:E1?valueInputOption=RAW
{ "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Data", 123.45, true, "=MAX(D2:D4)", "10"] ], }
La risposta è costituita da un
UpdateValuesResponse
oggetto come questo:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}
Il foglio risultante sarà simile al seguente:
A | B | C | D | E | |
1 | Dati | 123,45 | VERO | =MAX(D2:D4) | 10 |
2 |
Tieni presente che "TRUE" è centrato ed è un valore booleano, mentre "123, 45" è giustificato a destra perché è un numero e "10" è giustificato a sinistra perché è una stringa. La formula non viene analizzata e viene visualizzata anche come stringa.
Aggiungere valori
Inizia con un foglio come la tabella seguente:
A | B | C | D | |
1 | Elemento | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 $ | 4 | 1/3/2016 |
3 |
Il seguente
spreadsheets.values.append
esempio di codice mostra come aggiungere due nuove righe di valori a partire dalla riga 3. Il parametro query ValueInputOption
è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data o meno).
Il corpo della richiesta è un
ValueRange
oggetto che descrive i valori dell'intervallo da scrivere. Il
campo
majorDimension
indica che gli array sono elenchi di valori organizzati per righe.
Il protocollo di richiesta è mostrato di seguito.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "3/20/2016"], ], }
La risposta è costituita da un
AppendValuesResponse
oggetto come questo:
{ "spreadsheetId":SPREADSHEET_ID
, "tableRange": "Sheet1!A1:D2", "updates": { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!A3:D4", "updatedRows": 2, "updatedColumns": 4, "updatedCells": 8, } }
Il foglio risultante sarà simile al seguente:
A | B | C | D | |
1 | Elemento | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 $ | 4 | 1/3/2016 |
3 | Porta | 15 $ | 2 | 15/03/2016 |
4 | Motore | 100 $ | 1 | 20/03/2016 |
5 |