L'API Fogli Google consente di scrivere valori e formule in celle, intervalli, set di intervalli e interi fogli. Gli esempi in questa pagina illustrano come eseguire alcune
operazioni di scrittura comuni con la risorsa
spreadsheets.values
dell'API Fogli.
Tieni presente che è anche possibile scrivere valori delle celle utilizzando il metodo spreadsheet.batchUpdate
, che può essere utile se vuoi aggiornare contemporaneamente la formattazione delle celle o altre proprietà non interessate dalla risorsa spreadsheets.values
. Ad esempio, se vuoi copiare un intervallo di celle da
un foglio a un altro sovrascrivendo sia la formula di cella sia la
formattazione della cella, puoi utilizzare il metodo
UpdateCellsRequest
con un elemento
spreadsheet.batchUpdate
.
Tuttavia, per le scritture di valori semplici, è più semplice utilizzare il metodo spreadsheets.values.update
o spreadsheets.values.batchUpdate
.
Questi esempi sono presentati sotto forma di richieste HTTP per essere indipendenti dal linguaggio. Per scoprire come implementare le scritture in diversi linguaggi utilizzando le librerie client dell'API di Google, consulta Lettura e scrittura dei 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
Partendo da un nuovo foglio di lavoro vuoto, il seguente esempio di codice spreadsheets.values.update
mostra come scrivere i valori in un intervallo. Il parametro di query ValueInputOption
è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data).
Il corpo della richiesta è un oggetto ValueRange
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 è composta da un oggetto UpdateValuesResponse
, come questo:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}
Il foglio risultante ha il seguente aspetto:
A | B | C | G | |
1 | Articolo | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 € | 4 | 1/03/2016 |
3 | Porta | 15 HKD | 2 | 15/03/2016 |
4 | Engine | 100 $ | 1 | 20/03/2016 |
5 | Totali | 135,5 $ | 7 | 20/03/2016 |
Scrivere in modo selettivo in un intervallo
Quando si scrivono valori in un intervallo, è possibile evitare di modificare alcune celle esistenti impostando gli elementi array corrispondenti su null
. Puoi anche cancellare una cella scrivendo una stringa vuota (""
).
Partendo da un foglio contenente gli stessi dati prodotti dall'esempio
sopra, il seguente esempio di codice
spreadsheets.values.update
mostra come scrivere i valori nell'intervallo B1:D4, lasciando selettivamente
alcune celle invariate e cancellandone altre. Il parametro di query ValueInputOption
è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data).
Il corpo della richiesta è un oggetto ValueRange
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
qui 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). B2 e B3 hanno i loro valori
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 è composta da un oggetto UpdateValuesResponse
come questo:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}
Il foglio risultante ha il seguente aspetto:
A | B | C | G | |
1 | Articolo | Costo | Disponibile | Data di spedizione |
2 | Ruota | 1,00 $ | 4 | 1/04/2016 |
3 | Porta | $ 2 | 2 | 15/04/2016 |
4 | Engine | 1 | ||
5 | Totali | 3 $ | 7 | 15/04/2016 |
Tieni presente che la riga "Totali", sebbene non sia stata modificata direttamente da questa richiesta, cambia perché le sue celle contengono formule che dipendono dalle celle alterate.
Scrittura su più intervalli
Partendo da un foglio vuoto, il seguente esempio di codice spreadsheets.values.batchUpdate
mostra come scrivere i valori negli intervalli Fogli1!A1:A4 e Fogli1!B1:D2. I valori esistenti nell'intervallo target vengono sovrascritti. Il corpo della richiesta è composto da un oggetto ValueInputOption
che mostra come interpretare i dati di input e da un array di oggetti ValueRange
corrispondente a ogni intervallo scritto. Il campo majorDimension
determina se gli array inclusi sono 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 è composta da un oggetto che elenca le statistiche aggiornate della cella 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 ha il seguente aspetto:
A | B | C | G | |
1 | Articolo | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 € | 4 | 1/03/2016 |
3 | Porta | |||
4 | Engine | |||
5 |
Scrivi valori senza analizzarli
Partendo da un foglio vuoto, il seguente esempio di codice spreadsheets.values.update
mostra come scrivere i valori nell'intervallo Sheet1!A1:E1, ma utilizza il parametro di query RAW
ValueInputOption
per impedire che le stringhe scritte vengano analizzate come formule, booleani o numeri. Vengono visualizzati come stringhe e l'allineamento del testo è giustificato nel foglio.
Il corpo della richiesta è un oggetto ValueRange
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 è composta da un oggetto UpdateValuesResponse
come questo:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}
Il foglio risultante ha il seguente aspetto:
A | B | C | D | E | |
1 | Dati | 123,45 | TRUE | =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.
Aggiungi valori
Inizia con un foglio come quello della tabella seguente:
A | B | C | G | |
1 | Articolo | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 € | 4 | 1/03/2016 |
3 |
Il seguente esempio di codice spreadsheets.values.append
mostra come aggiungere due nuove righe di valori a partire dalla riga 3. Il parametro di query ValueInputOption
è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data).
Il corpo della richiesta è un oggetto ValueRange
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 è composta da un oggetto AppendValuesResponse
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 ha il seguente aspetto:
A | B | C | G | |
1 | Articolo | Costo | Disponibile | Data di spedizione |
2 | Ruota | 20,50 € | 4 | 1/03/2016 |
3 | Porta | 15 HKD | 2 | 15/03/2016 |
4 | Engine | 100 $ | 1 | 20/03/2016 |
5 |