Leitura básica

A API do Planilhas Google permite que você leia valores de células, intervalos, conjuntos de intervalos, e planilhas inteiras. Os exemplos nesta página ilustram alguns casos de com o spreadsheets.values recurso. Você também pode 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 neutras. Para saber como implementar leituras em diferentes idiomas usando a API para bibliotecas de clientes da API, consulte Leitura e gravar célula de imagem.

Nesses exemplos, o marcador SPREADSHEET_ID indica onde você forneceria o ID da planilha, que podem ser descobertas no URL da planilha. Os intervalos de leitura são especificado usando a notação A1 na solicitação URL. Um exemplo de intervalo é Sheet1!A1:D5.

Dados de origem

Para esses exemplos, suponha que a planilha que está sendo lida tenha a seguinte fonte dados em sua primeira planilha ("Sheet1"). As strings na primeira linha são rótulos para as colunas individuais. Para ver exemplos de como ler em outras planilhas no planilha, consulte a notação A1.

	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

Ler um único intervalo

O seguinte spreadsheets.values.get exemplo de código mostra como ler os valores do intervalo Sheet1!A1:D5 e retorna 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 ValueRange objeto que descreve os valores do intervalo. A 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 seguinte spreadsheets.values.get exemplo de código mostra como ler os valores do intervalo Sheet1!A1:D3 e retorna na resposta, mas agrupadas por coluna. Linhas e colunas vazias à direita são omitido.

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 ValueRange objeto que descreve os valores do intervalo. A 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 seguinte spreadsheets.values.get exemplo de código mostra como ler os valores do intervalo Sheet1!A1:D5 e retorna na resposta, mas usa opções de renderização para gerenciar como essas informações é retornado. A Configuração ValueRenderOption de FORMULA indica que será preciso retornar fórmulas em vez de valor calculado, e o DateTimeRenderOption A configuração 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 omitido.

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 ValueRange objeto que descreve os valores do intervalo. A 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 seguinte spreadsheets.values.batchGet exemplo de código mostra como ler valores dos intervalos Sheet1!B:B e Sheet1!D:D e 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 ValueRange objetos correspondentes a cada intervalo solicitado, listados na ordem em que foram solicitado. A 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 planilhas

O seguinte spreadsheets.values.batchGet o exemplo de código mostra como ler valores de intervalos nas Planilhas Planilhas1!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 ValueRange objetos correspondentes a cada intervalo solicitado, listados na ordem em que foram solicitado. A 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": [
        [...],
        [...]
      ]
    }
  ]
}