Scrittura di base

L'API Fogli Google consente di scrivere valori e formule in celle, intervalli, insiemi di intervalli e interi fogli. Gli esempi in questa pagina mostrano come eseguire alcune operazioni di scrittura comuni con la risorsa spreadsheets.values dell'API Fogli.

Tieni presente che è anche possibile scrivere i valori delle celle utilizzando il metodo spreadsheet.batchUpdate, 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 all'altro, sovrascrivendo sia la formula della cella che la formattazione della cella, puoi utilizzare il metodo UpdateCellsRequest con un elemento spreadsheet.batchUpdate.

Tuttavia, per la scrittura 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 neutrali dal linguaggio. Per scoprire come implementare le scritture in diversi linguaggi utilizzando le librerie client dell'API di Google, consulta Lettura e scrittura di valori delle celle.

In questi esempi, il segnaposto SPREADSHEET_ID indica dove dovresti fornire l'ID del foglio di lavoro, che può essere rilevato dall'URL del foglio di lavoro. Gli intervalli in cui scrivere sono specificati utilizzando la notazione A1. Un intervallo di esempio è Foglio1!A1:D5.

Scrivere un singolo intervallo

Iniziando con un nuovo foglio di lavoro vuoto, il seguente esempio di codice di 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 o meno 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 target 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	D
1	Elemento	Costo	A disposizione	Data di spedizione
2	Ruota	20,50 $	4	1/03/2016
3	Porta	15 HKD	2	15/03/2016
4	Motore	100 $	1	20/03/2016
5	Totali	135,5 $	7	20/03/2016

Scrivere in modo selettivo fino a un intervallo

Quando scrivi valori in un intervallo, puoi 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 esempio di codice spreadsheets.values.update mostra come scrivere i valori nell'intervallo B1:D4, lasciando invariate 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 o meno 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 ciascuna colonna nell'intervallo. Il primo array indica che B1 deve essere lasciato invariato (a causa dell'elemento dell'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 è 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	D
1	Elemento	Costo	A disposizione	Data di spedizione
2	Ruota	1,00 $	4	1/04/2016
3	Porta	$ 2	2	15/04/2016
4	Motore		1
5	Totali	3 $	7	15/04/2016

Tieni presente che la riga "Totali", sebbene non sia modificata direttamente da questa richiesta, cambia perché le sue celle contengono formule che dipendono dalle celle modificate.

Scrivi in più intervalli

A partire da un foglio vuoto, il seguente esempio di codice di 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 è 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 è composta da un oggetto che elenca le statistiche aggiornate delle celle e 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	D
1	Elemento	Costo	A disposizione	Data di spedizione
2	Ruota	20,50 $	4	1/03/2016
3	Porta
4	Motore
5

Scrivere valori senza analisi

A partire da un foglio vuoto, il seguente esempio di codice di spreadsheets.values.update mostra come scrivere i valori nell'intervallo Sheet1!A1:E1, ma utilizza il parametro di query RAW ValueInputOption per evitare che le stringhe scritte vengano analizzate come formule, booleani o numeri. Vengono visualizzate 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 target 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 nella tabella seguente:

	A	B	C	D
1	Elemento	Costo	A disposizione	Data di spedizione
2	Ruota	20,50 $	4	1/03/2016
3

Il seguente esempio di codice di 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 o meno 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	D
1	Elemento	Costo	A disposizione	Data di spedizione
2	Ruota	20,50 $	4	1/03/2016
3	Porta	15 HKD	2	15/03/2016
4	Motore	100 $	1	20/03/2016
5