Com a API Google Sheets, você pode ler valores de células, intervalos, conjuntos de intervalos e páginas inteiras. Os exemplos nesta página ilustram algumas operações
de leitura comuns com o
recurso
spreadsheets.values
. Também é possível ler valores de célula usando o método
spreadsheets.get
, mas
geralmente
spreadsheets.values.get
ou
spreadsheets.values.batchGet
é mais fácil.
Esses exemplos são apresentados na forma de solicitações HTTP para serem de linguagem neutra. Para saber como implementar leituras em diferentes idiomas 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 dela. Os intervalos de leitura são especificados usando a notação A1 no URL da solicitação. Um exemplo de intervalo é Sheet1!A1:D5.
Dados de origem
Para esses exemplos, suponha que a planilha que está sendo lida tenha os seguintes dados de origem na primeira página ("Sheet1"). As strings na primeira linha são rótulos para as colunas individuais. Para ver exemplos de como ler outras páginas na sua planilha, consulte Notação A1.
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 |
Ler um único intervalo
O exemplo de código spreadsheets.values.get
a seguir mostra como ler os valores do intervalo Sheet1!A1:D5 e os retornar na resposta. Linhas e colunas vazias à direita são omitidas.
O protocolo da solicitação é mostrado aqui.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
A resposta consiste em um objeto
ValueRange
que descreve os valores do intervalo. O campo majorDimension
indica que as matrizes são listas de valores organizados por linhas.
{ "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", "30/20/2016"], ["Totals", "$135.5", "7", "3/20/2016"] ], }
Ler um único intervalo agrupado por coluna
O exemplo de código spreadsheets.values.get
a seguir mostra como ler os valores do intervalo Sheet1!A1:D3 e os retornar na resposta, mas agrupados por coluna. Linhas e colunas vazias à direita são
omitidas.
O protocolo da solicitação é mostrado aqui.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
A resposta consiste em um objeto
ValueRange
que descreve os valores do intervalo. O campo majorDimension
indica que as matrizes são listas de valores organizados por colunas.
{ "range": "Sheet1!A1:D3", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door"], ["Cost", "$20.50", "$15"], ["Stocked", "4", "2"], ["Ship Date", "3/1/2016", "3/15/2016"] ], }
Ler um único intervalo com opções de renderização
O exemplo de código
spreadsheets.values.get
a seguir mostra como ler os valores do intervalo Sheet1!A1:D5 e os retornar
na resposta, mas usa opções de renderização para gerenciar como essas informações
são retornadas. A configuração
ValueRenderOption
de FORMULA
indica que as fórmulas precisam ser retornadas em vez do
valor calculado, e a configuração
DateTimeRenderOption
de SERIAL_NUMBER
indica que as datas precisam ser retornadas como números.
Outras configurações também são possíveis. Linhas e colunas vazias à direita são
omitidas.
O protocolo da solicitação é mostrado aqui.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5? valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER
A resposta consiste em um objeto
ValueRange
que descreve os valores do intervalo. O campo majorDimension
indica que as matrizes são listas de valores organizados por linhas.
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "42430"], ["Door", "$15", "2", "42444"], ["Engine", "$100", "1", "42449"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
Ler vários intervalos
O exemplo de código spreadsheets.values.batchGet
a seguir mostra como ler valores dos intervalos Sheet1!B:B e Sheet1!D:D e os retorna na resposta. A configuração
ValueRenderOption
de UNFORMATTED_VALUE
indica que os valores são calculados, mas não formatados
na resposta. Linhas e colunas vazias à direita são omitidas.
O protocolo da solicitação é mostrado aqui.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet? ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
A resposta a essa chamada de método consiste em um objeto com o ID da planilha
e uma matriz de objetos
ValueRange
correspondentes a cada intervalo solicitado, listados na ordem em que foram
solicitados. O campo majorDimension
indica que as matrizes são listas de valores organizados por colunas. Exemplo:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!B1:B1000", "majorDimension": "COLUMNS", "values": [ ["Cost",20.5,15,100,135.5] ] }, { "range": "Sheet1!D1:D1000", "majorDimension": "COLUMNS", "values": [ ["Ship Date",42430,42444,42449,42449] ]s } ] }
Ler vários intervalos em várias planilhas
O exemplo de código
spreadsheets.values.batchGet
a seguir mostra como ler valores de intervalos nas Planilhas Sheet1!A1:D5,
Products!D1:D100 e Sales!E4:F6 e os retorna na resposta. A configuração
ValueRenderOption
de UNFORMATTED_VALUE
indica que os valores são calculados, mas não formatados
na resposta. Linhas e colunas vazias à direita são omitidas.
O protocolo da solicitação é mostrado aqui.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet? ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
A resposta a essa chamada de método consiste em um objeto com o ID da planilha
e uma matriz de objetos
ValueRange
correspondentes a cada intervalo solicitado, listados na ordem em que foram
solicitados. O campo majorDimension
indica que as matrizes são listas de valores organizados por colunas. Exemplo:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!A1:D5", "majorDimension": "COLUMNS", "values": [ [...], [...] ] }, { "range": "Products!D1:D100", "majorDimension": "COLUMNS", "values": [ [...] ] }, { "range": "Sales!E4:F6", "majorDimension": "COLUMNS", "values": [ [...], [...] ] } ] }