A Google Sheets API permite que você grave valores e fórmulas em células, intervalos,
conjuntos de intervalos e páginas inteiras. Os exemplos nesta página ilustram como
operações de gravação comuns podem ser realizadas
spreadsheets.values
da API Sheets.
Também é possível escrever valores de células usando a função
spreadsheet.batchUpdate
, o que pode ser útil se você deseja atualizar simultaneamente a formatação da célula
ou outras propriedades que
spreadsheets.values
recurso não afeta. Por exemplo, se você quiser copiar um intervalo de células
de uma planilha para outra, substituindo a fórmula da célula e a célula
e a formatação, use o
UpdateCellsRequest
com um
spreadsheet.batchUpdate
.
No entanto, para gravações de valor simples, é mais fácil usar o
spreadsheets.values.update
ou o
spreadsheets.values.batchUpdate
.
Esses exemplos são apresentados na forma de solicitações HTTP para serem neutras. Para saber como implementar gravações em diferentes idiomas usando bibliotecas de clientes da API do Google, consulte Leia e gravar célula de imagem.
Nesses exemplos, o marcador SPREADSHEET_ID
indica
na qual você deve fornecer a planilha
ID, que pode ser descoberto na
URL da planilha. Os intervalos para gravar são especificados usando A1
. Um exemplo de intervalo é Sheet1!A1:D5.
Gravar um único intervalo
Começando com uma nova planilha em branco,
spreadsheets.values.update
exemplo de código mostra como gravar os valores em um intervalo. O
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
ValueRange
objeto que descreve os valores do intervalo a serem gravados. O
Campo majorDimension
indica que as matrizes são listas de valores organizadas por linhas. 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
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 | 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 | 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 alguns valores
células definindo os elementos de matriz correspondentes como null
. Também é possível
para limpar uma célula escrevendo uma string vazia (""
) nela.
Começar com uma página que contenha os mesmos dados produzidos pelos requisitos acima
exemplo, os seguintes
spreadsheets.values.update
exemplo de código mostra como gravar os valores no intervalo B1:D4, seletivamente
deixando algumas células inalteradas e limpando outras. O
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
ValueRange
objeto que descreve os valores do intervalo a serem gravados. O
Campo majorDimension
indica que as matrizes são listas de valores organizadas 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. O
a primeira matriz indica que a célula B1 não deve ser alterada (devido à matriz null
)
), enquanto B4 deve ser apagado (string vazia). B2 e B3 têm seus valores
atualizado. A terceira matriz executa as mesmas operações na coluna D, enquanto a
a segunda matriz vazia indica que a coluna C não deve ser alterada.
A resposta consiste em um
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 | 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 |
Os "Totais" linha, embora não seja diretamente alterada por esta solicitação, não ser alterado porque suas células contêm fórmulas que dependem das células alteradas.
Gravar em vários intervalos
Começando com uma folha em branco,
spreadsheets.values.batchUpdate
exemplo de código 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. A solicitação
corpo é composto por
O objeto ValueInputOption
que
mostra como interpretar os dados de entrada e uma matriz de
ValueRange
objetos que correspondem 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
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:
A | B | C | D | |
1 | Item | Custo | Armazenado | 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 folha em branco,
spreadsheets.values.update
exemplo de código mostra como gravar os valores no intervalo Sheet1!A1:E1, mas usa
o RAW
ValueInputOption
parâmetro de consulta 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 planilha.
O corpo da solicitação é um
ValueRange
objeto que descreve os valores do intervalo a serem gravados. O
Campo majorDimension
indica que as matrizes são listas de valores organizadas por linhas. 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
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 | VERDADEIRO | =MÁXIMO(D2:D4) | 10 |
2 |
Observe que "TRUE" é centralizado e é um valor booleano, enquanto "123,45" está certo justificada por ser um número, e "10" é justificada à esquerda porque é uma fio. A fórmula não é analisada e também aparece como uma string.
Anexar valores
Comece com uma planilha como a da tabela abaixo:
A | B | C | D | |
1 | Item | Custo | Armazenado | Data de envio |
2 | Wheel | US$ 20,50 | 4 | 01/03/2016 |
3 |
O seguinte
spreadsheets.values.append
exemplo de código mostra como adicionar duas novas linhas de valores a partir da linha 3. O
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
ValueRange
objeto que descreve os valores do intervalo a serem gravados. O
Campo majorDimension
indica que as matrizes são listas de valores organizadas 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
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 | 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 |