As planilhas podem ter várias folhas, com cada uma
com qualquer número de linhas ou colunas. Uma célula é um local na interseção de uma determinada linha e coluna 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 os conceitos básicos do uso do recurso spreadsheets.values
. Se você precisar inserir linhas ou atualizar a formatação e outras propriedades em uma planilha, use o método spreadsheets.batchUpdate
descrito em Atualizar planilhas.
Métodos
O recurso spreadsheets.values
fornece os métodos abaixo para ler e gravar valores, cada um para uma
tarefa específica:
Acesso ao intervalo | leitura | 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, para melhorar a eficiência.
Confira exemplos de cada um desses métodos nas páginas de exemplos Leitura básica e Gravação básica. Para ver todas as amostras, consulte a página de visão geral.
Ler
Para ler os valores de dados de uma planilha, você precisa do ID da planilha e da notação A1
para o intervalo. Especificar o intervalo sem o ID da página (A1:B2
) significa que a solicitação será 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 |
Observe que você só deverá usar dateTimeRenderOption
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. Linhas e colunas vazias à direita são omitidas.
Os métodos "get" individuais e em lote são descritos abaixo. Para amostras 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 descontínuos em 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
.
Escrever
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 únicas, 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 sem string, como booleanos ou números, sempre são processados como RAW . |
USER_ENTERED |
A entrada é analisada exatamente como se tivesse sido inserida na interface do app Planilhas. Por exemplo, "1 de março de 2016" se torna uma data, e "=1+2" se torna uma fórmula. Os formatos também podem ser inferidos.Assim, "$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 amostras 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. Na ValueRange
, há a opção de especificar
o
majorDimension
.
Por padrão, ROWS
é usado. Se COLUMNS
for especificado, cada matriz interna será gravada em uma coluna, em vez de em uma linha.
Durante a atualização, valores sem dados são ignorados. Para limpar os dados, use uma string vazia ("").
Gravar vários intervalos
Para 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 os próprios
range
, majorDimension
e dados de entrada.
Anexar valores
Para anexar dados após uma tabela de dados 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. Na ValueRange
, há a opção de especificar
o
majorDimension
.
Por padrão, ROWS
é usado. Se COLUMNS
for especificado, cada matriz interna será gravada em uma coluna, em vez de em uma linha.
O intervalo de entrada é usado para pesquisar dados atuais e encontrar uma "tabela" dentro desse intervalo. Os valores são anexados na próxima linha da tabela, começando pela primeira coluna. Por exemplo, considere Sheet1
com esta aparência:
R | 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 tabela.B4
ouC5:D5
, porque ambos estão na tabelaB4:D6
.B2:D4
, porque a última tabela do intervalo éB4:D6
(apesar de ela também conter a tabelaA1:C2
).A3:G10
, porque a última tabela do intervalo éB4:D6
(apesar de começar antes e terminar depois dela).
As entradas range
a seguir não começariam a ser gravadas em B7
:
A1
começaria a ser gravado emA3
, porque isso está na tabelaA1:C2
.E4
começaria a ser gravado emE4
, porque não está em nenhuma tabela. A gravação deA4
também começaria a ser feita 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 o
InsertDataOption
e especifique insertDataOption=INSERT_ROWS
.
Para saber mais sobre limites de células e linhas no Planilhas, consulte Arquivos que você pode armazenar no Google Drive.