Leitura básica

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 com o recurso spreadsheets.values. Também é possível ler valores de células usando o método spreadsheets.get, mas geralmente spreadsheets.values.get ou spreadsheets.values.batchGet são mais fáceis.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em termos de linguagem. 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 de posição SPREADSHEET_ID indica onde você forneceria o ID da planilha, que pode ser descoberto pelo URL da planilha. Os intervalos que devem ser lidos são especificados usando a notação A1 no URL da solicitação. Um exemplo de intervalo é Planilha1!A1:D5.

Dados de origem

Para esses exemplos, pressuponha que a planilha a ser lida tem os seguintes dados de origem na primeira página ("Sheet1"). As strings na primeira linha são rótulos para as colunas individuais. Para conferir exemplos de como ler outras planilhas, consulte notação A1.

	A	B	C	D
1	Item	Custo	Estoque	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	US$ 135,5	7	20/03/2016

Ler um único intervalo

O exemplo de código spreadsheets.values.get abaixo 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 organizadas 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 organizadas 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 retorna 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 devem ser retornadas em vez do valor calculado, e a configuração DateTimeRenderOption de SERIAL_NUMBER indica que as datas devem 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 organizadas 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 organizadas 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 páginas

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 organizadas 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": [
        [...],
        [...]
      ]
    }
  ]
}