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 para atualizar simultaneamente a formatação da célula
ou outras propriedades que o recurso
spreadsheets.values
não afeta. Por exemplo, se você quiser copiar um intervalo de células de
uma página para outra enquanto substitui 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 o método
spreadsheets.values.update
ou
spreadsheets.values.batchUpdate
.
Esses exemplos são apresentados na forma de solicitações HTTP para serem de linguagem neutra. 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élulas.
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 os dados serão gravados são especificados com 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 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 vai ficar assim:
R | B | C | D | |
1 | Item | Custo | Armazenado | Data de envio |
2 | Roda gigante | US$ 20,50 | 4 | 01/03/2016 |
3 | Porta | US$ 15 | 2 | 15/03/2016 |
4 | Mecanismo | US$ 100 | 1 | 20/03/2016 |
5 | Valores totais | R$ 135,50 | 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
existentes definindo os elementos de matriz correspondentes como null
. 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
de forma seletiva. 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 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 no intervalo. A
primeira matriz indica que a célula B1 não deve ser alterada (devido ao elemento de matriz null
)
e a B4 precisa ser limpa (string vazia). B2 e B3 têm seus 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:
R | B | C | D | |
1 | Item | Custo | Armazenado | Data de envio |
2 | Roda gigante | US$ 1,00 | 4 | 01/04/2016 |
3 | Porta | US$ 2 | 2 | 15/04/2016 |
4 | Mecanismo | 1 | ||
5 | Valores totais | US$ 3,00 | 7 | 15/04/2016 |
Observe que a linha "Totais", embora não seja alterada diretamente por essa solicitação, é alterada porque suas 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 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 de célula 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 vai ficar assim:
R | B | C | D | |
1 | Item | Custo | Armazenado | Data de envio |
2 | Roda gigante | 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
abaixo 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. Eles 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 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 vai ficar assim:
R | B | C | D | E | |
1 | Dados | 123,45 | TRUE | =MÁXIMO(D2:D4) | 10 |
2 |
Observe que "TRUE" está centralizado e é um valor booleano, enquanto "123, 45" é justificado à direita por ser 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 da tabela abaixo:
R | 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 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 vai ficar assim:
R | B | C | D | |
1 | Item | Custo | Armazenado | Data de envio |
2 | Roda gigante | US$ 20,50 | 4 | 01/03/2016 |
3 | Porta | US$ 15 | 2 | 15/03/2016 |
4 | Mecanismo | US$ 100 | 1 | 20/03/2016 |
5 |