As planilhas podem ter várias páginas, cada uma com um número ilimitado de linhas ou colunas. Uma célula é um local na intersecção de uma linha e coluna específicas e pode conter um valor de dados. A API Google Sheets fornece o recurso spreadsheets.values
para ativar a leitura e a gravação de valores.
Esta página descreve as noções básicas do uso do recurso spreadsheets.values
. Se você precisar inserir linhas ou atualizar a formatação e outras propriedades em uma página, use o método spreadsheets.batchUpdate
descrito em Atualizar planilhas.
Métodos
O recurso spreadsheets.values
fornece os seguintes métodos para ler e gravar valores, cada um para uma
tarefa específica:
Acesso ao intervalo | Reading | Gravação |
---|---|---|
Intervalo único | spreadsheets.values.get |
spreadsheets.values.update |
Vários intervalos | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Como anexar | spreadsheets.values.append |
Em geral, é recomendável combinar várias leituras ou atualizações com os
métodos batchGet
e batchUpdate
(respectivamente), já que isso melhora a
eficiência.
Você encontra exemplos de cada um desses métodos nas páginas de amostra Leitura básica e Gravação básica. Para acessar todas as amostras, consulte a página de visão geral de amostras.
Ler
Para ler valores de dados de uma página, você precisa do ID da planilha e da notação A1 do intervalo. Especificar o intervalo sem o ID da página (A1:B2
) significa que a solicitação é executada na primeira página da planilha. Para mais informações sobre IDs de planilhas e notação A1, consulte Visão geral da API Google Sheets.
Vários parâmetros de consulta opcionais controlam o formato da saída:
Parâmetro de formato | Valor padrão |
---|---|
majorDimension |
ROWS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Use dateTimeRenderOption
apenas se valueRenderOption
não for FORMATTED_VALUE
.
Não há um limite explícito para a quantidade de dados retornados. Os erros não retornam dados. As linhas e colunas vazias à direita são omitidas.
Os métodos "get" individuais e em lote são descritos abaixo. Para ver exemplos de operações básicas de leitura, consulte Leitura básica.
Ler um único intervalo
Para ler um único intervalo de valores de uma planilha, use uma solicitação spreadsheets.values.get
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
A resposta a essa solicitação é retornada como um objeto ValueRange
.
Ler vários intervalos
Para ler vários intervalos de valores não contínuos de uma planilha, use uma solicitação
spreadsheets.values.batchGet
que permite especificar vários intervalos a serem recuperados:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
A resposta a essa solicitação é retornada como um objeto
BatchGetValuesResponse
que contém o spreadsheetId
e uma lista de
objetos
ValueRange
.
Gravar
Para gravar em uma planilha, você precisa do ID da planilha, do intervalo de células na notação A1 e dos dados que quer gravar em um objeto de corpo de solicitação apropriado. Para mais informações sobre IDs de planilhas e notação A1, consulte Visão geral da API Google Sheets.
As atualizações exigem um parâmetro
ValueInputOption
válido.
Para atualizações individuais, esse é um parâmetro de consulta obrigatório. Para atualizações em lote, esse parâmetro é obrigatório no corpo da solicitação. O ValueInputOption
controla
como os dados de entrada precisam ser interpretados e se as strings de entrada são analisadas
ou não, conforme descrito na tabela abaixo:
ValueInputOption |
Descrição |
---|---|
RAW |
A entrada não é analisada e é inserida como uma string. Por exemplo, a entrada "=1+2" coloca a string, não a fórmula, "=1+2" na célula. Valores que não sejam strings, como booleanos ou números, são sempre tratados como RAW . |
USER_ENTERED |
A entrada é analisada exatamente como se tivesse sido inserida na interface do Planilhas. Por exemplo, "1 de março de 2016" torna-se uma data e "=1+2" se torna uma fórmula. Os formatos também podem ser inferidos, portanto, "$100.15" se torna um número com formatação de moeda. |
Os métodos de atualização singular e em lote são descritos abaixo. Para ver exemplos de operações básicas de gravação, consulte Gravação básica.
Gravar em um único intervalo
Para gravar dados em um único intervalo, use uma solicitação spreadsheets.values.update
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
O corpo da solicitação de atualização precisa ser um objeto ValueRange
, embora o único campo obrigatório seja values
. Se range
for especificado, ele
precisará corresponder ao intervalo no URL. No ValueRange
, você tem a opção de especificar
o
majorDimension
dele.
Por padrão, ROWS
é usado. Se COLUMNS
for especificado, cada matriz interna será gravada em uma coluna, em vez de uma linha.
Durante a atualização, os valores sem dados são ignorados. Para limpar os dados, use uma string vazia ("").
Gravar vários intervalos
Se você quiser gravar vários intervalos não contínuos, use uma
solicitação
spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
O corpo da solicitação de atualização em lote precisa ser um objeto BatchUpdateValuesRequest
, que contém um ValueInputOption
e uma lista de objetos ValueRange
(um para cada intervalo gravado). Cada objeto ValueRange
especifica o próprio
range
, majorDimension
e dados de entrada.
Anexar valores
Para anexar dados após uma tabela em uma página, use uma
solicitação
spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
O corpo da solicitação de atualização precisa ser um objeto ValueRange
, embora o único campo obrigatório seja values
. Se range
for especificado, ele
precisará corresponder ao intervalo no URL. No ValueRange
, você tem a opção de especificar
o
majorDimension
dele.
Por padrão, ROWS
é usado. Se COLUMNS
for especificado, cada matriz interna será gravada em uma coluna, em vez de uma linha.
O intervalo de entrada é usado para pesquisar dados e encontrar uma "tabela" dentro
desse intervalo. Os valores são anexados à próxima linha da tabela, começando com a primeira coluna da tabela. Por exemplo, considere a Sheet1
como esta:
A | B | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
Há duas tabelas na página: A1:C2
e B4:D6
. Os valores anexados
começariam em B7
para todas as entradas range
a seguir:
Sheet1
, porque ele examinará todos os dados na planilha e determinará que a tabela emB4:D6
é a última.B4
ouC5:D5
, porque ambos estão na tabelaB4:D6
.B2:D4
, porque a última tabela no intervalo é aB4:D6
(apesar de também conter a tabelaA1:C2
).A3:G10
, porque a última tabela no intervalo é aB4:D6
(apesar de começar antes e terminar depois dela).
As seguintes entradas range
não começariam a ser gravadas em B7
:
A1
começaria a gravar emA3
, porque ela está na tabelaA1:C2
.E4
começaria a ser gravado emE4
, porque não está em nenhuma tabela. (A4
também começaria a ser gravado emA4
pelos mesmos motivos.)
Além disso, você pode escolher se quer substituir os dados atuais após uma tabela ou inserir novas linhas para os novos dados. Por padrão, a entrada substitui os dados após a tabela. Para gravar os novos dados em novas linhas, use
InsertDataOption
e especifique insertDataOption=INSERT_ROWS
.
Para saber mais sobre os limites de células e linhas no Planilhas, consulte Arquivos que você pode armazenar no Google Drive.