Esta página foi traduzida pela API Cloud Translation.

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 de gravação comuns 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, se você quiser copiar um intervalo de células de uma planilha para outra, substituindo 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 valores simples, é mais fácil usar o método spreadsheets.values.update ou o spreadsheets.values.batchUpdate.

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

Nesses exemplos, o marcador de posição SPREADSHEET_ID indica onde você deve fornecer o ID da planilha, que pode ser descoberto pelo URL da planilha. Os intervalos para gravação são especificados usando a notação A1. Um exemplo de intervalo é Planilha1!A1:D5.

Gravar um único intervalo

Começando com uma planilha nova e 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 organizadas por linhas. Os valores no intervalo de destino são substituídos.

Confira o protocolo da solicitação abaixo.

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 tem esta aparência:

	A	B	C	D
1	Item	Custo	Estoque	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3	Porta	US$ 15	2	15/03/2016
4	Mecanismo	US$ 100	1	20/03/2016
5	Total	US$ 135,5	7	20/03/2016

Gravar seletivamente em um intervalo

Ao gravar valores em um intervalo, é possível evitar a alteração de algumas células definindo os elementos de matriz correspondentes como null. Também é possível limpar uma célula gravando 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 seletivamente 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.

Confira o protocolo da solicitação abaixo.

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 alterações feitas em cada coluna do intervalo. A primeira matriz indica que a célula B1 não deve ser alterada (devido ao elemento de matriz null), enquanto B4 deve ser limpa (string vazia). Os valores de B2 e B3 foram atualizados. A terceira matriz realiza 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 tem esta aparência:

	A	B	C	D
1	Item	Custo	Estoque	Data de envio
2	Wheel	US$ 1,00	4	01/04/2016
3	Porta	US$ 2	2	15/04/2016
4	Mecanismo		1
5	Total	US$ 3,00	7	15/04/2016

A linha "Totals", embora não seja diretamente alterada por essa solicitação, sofre mudanças porque as células dela 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 atuais 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 correspondentes a cada intervalo gravado. O campo majorDimension determina se as matrizes incluídas são interpretadas como matrizes de colunas ou linhas.

Confira o protocolo da solicitação abaixo.

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 das células atualizadas e uma matriz de objetos UpdateValuesResponse, um 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 tem esta aparência:

	A	B	C	D
1	Item	Custo	Estoque	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3	Porta
4	Mecanismo
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 impedir que as strings gravadas sejam analisadas como fórmulas, booleanos ou números. Elas aparecem como strings, e o alinhamento do texto é justificado na planilha.

Confira o protocolo da solicitação abaixo.

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 tem esta aparência:

	A	B	C	D	E
1	Dados	123,45	VERDADEIRO	=MÁXIMO(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 porque é uma string. A fórmula não é analisada e também aparece como uma string.

Acrescentar valores

Comece com uma página semelhante à tabela abaixo:

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

O exemplo de código spreadsheets.values.append abaixo 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.

Confira o protocolo da solicitação abaixo.

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 tem esta aparência:

	A	B	C	D
1	Item	Custo	Estoque	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3	Porta	US$ 15	2	15/03/2016
4	Mecanismo	US$ 100	1	20/03/2016
5