Scrittura di base

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

Tieni presente che è anche possibile scrivere i valori delle celle utilizzando il spreadsheet.batchUpdate metodo, che può essere utile se vuoi aggiornare contemporaneamente la formattazione delle celle o altre proprietà che la spreadsheets.values risorsa non influenza. Ad esempio, se vuoi copiare un intervallo di celle da un foglio a un altro sovrascrivendo sia la formula che la formattazione delle celle, puoi utilizzare il UpdateCellsRequest metodo con un spreadsheet.batchUpdate.

Tuttavia, per le semplici scritture di valori è più facile utilizzare il spreadsheets.values.update metodo o il spreadsheets.values.batchUpdate metodo.

Questi esempi vengono presentati sotto forma di richieste HTTP per essere indipendenti dal linguaggio. Per scoprire come implementare le scritture in lingue diverse utilizzando le librerie client delle API di Google, consulta Leggere e scrivere i valori delle celle.

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

Scrivere un singolo intervallo

Partendo da un nuovo foglio di lavoro vuoto, il seguente spreadsheets.values.update esempio di codice mostra come scrivere i valori in un intervallo. Il ValueInputOption parametro di query è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data).

Il corpo della richiesta è un ValueRange oggetto che descrive i valori dell'intervallo da scrivere. Il majorDimension campo indica che gli array sono elenchi di valori organizzati per righe. I valori esistenti nell'intervallo di destinazione vengono sovrascritti.

Di seguito è riportato il protocollo della richiesta.

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 UpdateValuesResponse oggetto, come il seguente:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

Il foglio risultante è simile al seguente:

Scrivere selettivamente in 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 ("") al suo interno.

Partendo da un foglio contenente gli stessi dati prodotti dall'esempio precedente, il seguente spreadsheets.values.update esempio di codice mostra come scrivere i valori nell'intervallo B1:D4, lasciando selettivamente alcune celle invariate e cancellandone altre. Il ValueInputOption parametro di query è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data).

Il corpo della richiesta è un ValueRange oggetto che descrive i valori dell'intervallo da scrivere. Il majorDimension campo indica che gli array sono elenchi di valori organizzati per colonne.

Di seguito è riportato il protocollo della richiesta.

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 rimanere invariato (a causa dell'elemento dell'array null), mentre B4 deve essere cancellato (stringa vuota). I valori di B2 e B3 vengono aggiornati. Il terzo array esegue le stesse operazioni sulla colonna D, mentre il secondo array vuoto indica che la colonna C deve rimanere invariata.

La risposta è costituita da un UpdateValuesResponse oggetto come il seguente:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

Il foglio risultante è simile al seguente:

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 modificate.

Scrivere in più intervalli

Partendo da un foglio vuoto, il seguente spreadsheets.values.batchUpdate esempio di codice mostra come scrivere i valori negli intervalli Sheet1!A1:A4 e Sheet1!B1:D2. I valori esistenti nell'intervallo di destinazione vengono sovrascritti. Il corpo della richiesta è costituito da un ValueInputOption oggetto che mostra come interpretare i dati di input e da un array di ValueRange oggetti corrispondenti a ogni intervallo scritto. Il campo determina se gli array inclusi vengono interpretati come array di colonne o righe.majorDimension

Di seguito è riportato il protocollo della richiesta.

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 UpdateValuesResponse oggetti, 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 è simile al seguente:

Scrivere valori senza analisi

Partendo da un foglio vuoto, il seguente spreadsheets.values.update esempio di codice 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, valori booleani o numeri. Vengono visualizzate 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 majorDimension campo indica che gli array sono elenchi di valori organizzati per righe. I valori esistenti nell'intervallo di destinazione vengono sovrascritti.

Di seguito è riportato il protocollo della richiesta.

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 il seguente:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

Il foglio risultante è simile al seguente:

Tieni presente che "VERO" è 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 simile alla tabella riportata di seguito:

Il seguente spreadsheets.values.append esempio di codice mostra come aggiungere due nuove righe di valori a partire dalla riga 3. Il ValueInputOption parametro di query è obbligatorio e determina se i valori scritti vengono analizzati (ad esempio, se una stringa viene convertita in una data).

Il corpo della richiesta è un ValueRange oggetto che descrive i valori dell'intervallo da scrivere. Il majorDimension campo indica che gli array sono elenchi di valori organizzati per righe.

Di seguito è riportato il protocollo della richiesta.

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 il seguente:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

Il foglio risultante è simile al seguente: