Redação básica

Com a API Google Sheets, você pode gravar valores e fórmulas em células, intervalos, conjuntos de intervalos e páginas inteiras. Os exemplos nesta página ilustram como algumas operações comuns de gravação podem ser realizadas com o recurso spreadsheets.values da API Sheets.

Também é possível gravar valores de células usando o método spreadsheet.batchUpdate, que pode ser útil se você quiser atualizar simultaneamente a formatação de células ou outras propriedades que o recurso spreadsheets.values não afeta. Por exemplo, para copiar um intervalo de células de uma página para outra e substituir a fórmula e a formatação da célula, use o método UpdateCellsRequest com um spreadsheet.batchUpdate.

No entanto, para gravações de valor simples, é mais fácil usar os métodos spreadsheets.values.update ou spreadsheets.values.batchUpdate.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em relação à linguagem. Para saber como implementar gravações em diferentes linguagens usando as bibliotecas de cliente da API do Google, consulte Ler e gravar valores de célula.

Nesses exemplos, o marcador SPREADSHEET_ID indica onde você forneceria o ID da planilha, que pode ser descoberto no URL da planilha. Os intervalos em que a gravação é feita são especificados usando a notação A1. Um exemplo de intervalo é Sheet1!A1:D5.

Gravar um único intervalo

Começando com uma nova planilha em branco, o exemplo de código spreadsheets.values.update a seguir mostra como gravar os valores em um intervalo. O parâmetro de consulta ValueInputOption é obrigatório e determina se os valores gravados são analisados. Por exemplo, se uma string é ou não convertida em uma data.

O corpo da solicitação é um objeto ValueRange que descreve os valores de intervalo a serem gravados. O campo majorDimension indica que as matrizes são listas de valores organizados por linhas. Os valores atuais no intervalo de destino são substituídos.

Confira abaixo o protocolo da solicitação.

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)"]
  ],
}

A resposta consiste em um objeto UpdateValuesResponse, como este:

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

A página resultante vai ficar assim:

A B C D
1 Item Custo Armazenado Data de envio
2 Roda gigante US$ 20,50 4 01/03/2016
3 Porta $15 2 15/03/2016
4 Engine US$ 100 1 20/03/2016
5 Total $135.5 7 20/03/2016

Gravar seletivamente em um intervalo

Ao gravar valores em um intervalo, é possível definir os elementos da matriz correspondentes como null para evitar a mudança de algumas células. Também é possível limpar uma célula escrevendo uma string vazia ("") nela.

Começando com uma página que contém os mesmos dados produzidos pelo exemplo acima, o exemplo de código spreadsheets.values.update a seguir mostra como gravar os valores no intervalo B1:D4, deixando algumas células inalteradas e limpando outras. O parâmetro de consulta ValueInputOption é obrigatório e determina se os valores gravados são analisados. Por exemplo, se uma string é ou não convertida em uma data.

O corpo da solicitação é um objeto ValueRange que descreve os valores de intervalo a serem gravados. O campo majorDimension indica que as matrizes são listas de valores organizados por coluna.

Confira abaixo o protocolo da solicitação.

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", ""]
  ]
}

O campo values lista as mudanças feitas em cada coluna no intervalo. A primeira matriz indica que B1 não deve ser alterada (devido ao elemento de matriz null), enquanto B4 deve ser apagada (string vazia). B2 e B3 têm os valores atualizados. A terceira matriz executa as mesmas operações na coluna D, enquanto a segunda matriz vazia indica que a coluna C não deve ser alterada.

A resposta consiste em um objeto UpdateValuesResponse como este:

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

A página resultante vai ficar assim:

A B C D
1 Item Custo Armazenado Data de envio
2 Roda gigante $1.00 4 01/04/2016
3 Porta $2 2 4/15/2016
4 Engine 1
5 Total $3.00 7 4/15/2016

Observe que a linha "Totais", embora não seja alterada diretamente por essa solicitação, é alterada porque as células contêm fórmulas que dependem das células alteradas.

Gravar em vários intervalos

Começando com uma página em branco, o exemplo de código spreadsheets.values.batchUpdate a seguir mostra como gravar os valores nos intervalos Sheet1!A1:A4 e Sheet1!B1:D2. Os valores existentes no intervalo de destino são substituídos. O corpo da solicitação consiste em um objeto ValueInputOption que mostra como interpretar os dados de entrada e uma matriz de objetos ValueRange correspondente a cada intervalo gravado. O campo majorDimension determina se as matrizes incluídas são interpretadas como matrizes de colunas ou linhas.

Confira abaixo o protocolo da solicitação.

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"]
      ]
    }
  ]
}

A resposta consiste em um objeto que lista as estatísticas atualizadas da célula e uma matriz de objetos UpdateValuesResponse, uma para cada intervalo atualizado. Exemplo:

{
  "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,
    }
  ],
}

A página resultante vai ficar assim:

A B C D
1 Item Custo Armazenado Data de envio
2 Roda gigante US$ 20,50 4 01/03/2016
3 Porta
4 Engine
5

Gravar valores sem analisar

Começando com uma página em branco, o exemplo de código spreadsheets.values.update a seguir mostra como gravar os valores no intervalo Sheet1!A1:E1, mas usa o parâmetro de consulta RAW ValueInputOption para evitar que as strings gravadas sejam analisadas como fórmulas, booleanos ou números. Elas aparecem como strings e o alinhamento do texto é justificado na página.

O corpo da solicitação é um objeto ValueRange que descreve os valores de intervalo a serem gravados. O campo majorDimension indica que as matrizes são listas de valores organizados por linhas. Os valores atuais no intervalo de destino são substituídos.

Confira abaixo o protocolo da solicitação.

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"]
  ],
}

A resposta consiste em um objeto UpdateValuesResponse como este:

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

A página resultante vai ficar assim:

A B C D E
1 Dados 123.45 TRUE =MAX(D2:D4) 10
2

Observe que "TRUE" está centralizado e é um valor booleano, enquanto "123,45" é justificado à direita porque é um número, e "10" é justificado à esquerda por ser uma string. A fórmula não é analisada e também aparece como uma string.

Anexar valores

Comece com uma planilha como a tabela abaixo:

A B C D
1 Item Custo Armazenado Data de envio
2 Roda gigante US$ 20,50 4 01/03/2016
3

O exemplo de código spreadsheets.values.append a seguir mostra como adicionar duas novas linhas de valores começando pela linha 3. O parâmetro de consulta ValueInputOption é obrigatório e determina se os valores gravados são analisados. Por exemplo, se uma string é ou não convertida em uma data.

O corpo da solicitação é um objeto ValueRange que descreve os valores de intervalo a serem gravados. O campo majorDimension indica que as matrizes são listas de valores organizados por linhas.

Confira abaixo o protocolo da solicitação.

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"],
  ],
}

A resposta consiste em um objeto AppendValuesResponse como este:

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

A página resultante vai ficar assim:

A B C D
1 Item Custo Armazenado Data de envio
2 Roda gigante US$ 20,50 4 01/03/2016
3 Porta $15 2 15/03/2016
4 Engine US$ 100 1 20/03/2016
5