Базовое чтение

API Google Sheets позволяет считывать значения из ячеек, диапазонов, наборов диапазонов и целых листов. Примеры на этой странице иллюстрируют некоторые распространенные операции чтения с ресурсом spreadsheets.values . Вы также можете прочитать значения ячеек с помощью метода spreadsheets.get , но обычно использовать spreadsheets.values.get или spreadsheets.values.batchGet проще.

Эти примеры представлены в виде HTTP-запросов, которые не зависят от языка. Чтобы узнать, как реализовать чтение на разных языках с помощью клиентских библиотек Google API, см. раздел Чтение и запись значений ячеек .

В этих примерах заполнитель SPREADSHEET_ID указывает, где вы должны указать идентификатор электронной таблицы , который можно найти по URL-адресу электронной таблицы. Диапазоны для чтения указываются с использованием нотации A1 в URL-адресе запроса. Пример диапазона: Лист1!A1:D5.

Исходные данные

В этих примерах предположим, что считываемая электронная таблица содержит следующие исходные данные на своем первом листе («Лист1»). Строки в первой строке являются метками отдельных столбцов. Чтобы просмотреть примеры чтения с других листов в электронной таблице, см. обозначение A1 .

А Б С Д
1 Элемент Расходы Запасено Дата отправки
2 Колесо 20,50 долларов США 4 01.03.2016
3 Дверь 15 долларов США 2 15.03.2016
4 Двигатель 100 долларов 1 20.03.2016
5 Итоги 135,5 долларов США 7 20.03.2016

Чтение одного диапазона

В следующем примере кода spreadsheets.values.get показано, как считывать значения из диапазона Sheet1!A1:D5 и возвращать их в ответе. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

Ответ состоит из объекта ValueRange , описывающего значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам.

{
  "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"]
  ],
}

Чтение одного диапазона, сгруппированного по столбцу

В следующем примере кода spreadsheets.values.get показано, как считывать значения из диапазона Sheet1!A1:D3 и возвращать их в ответе, но сгруппированные по столбцам. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

Ответ состоит из объекта ValueRange , описывающего значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам.

{
  "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"]
  ],
}

Чтение одного диапазона с параметрами рендеринга

В следующем примере кода spreadsheets.values.get показано, как считывать значения из диапазона Sheet1!A1:D5 и возвращать их в ответе, но для управления возвратом этой информации используются параметры отрисовки. Параметр ValueRenderOption для FORMULA указывает, что вместо вычисленного значения должны быть возвращены формулы, а параметр DateTimeRenderOption для SERIAL_NUMBER указывает, что даты должны быть возвращены в виде чисел. Возможны и другие настройки. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

Ответ состоит из объекта ValueRange , описывающего значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам.

{
  "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)"]
  ],
}

Чтение нескольких диапазонов

В следующем примере кода spreadsheets.values.batchGet показано, как считывать значения из диапазонов Sheet1!B:B и Sheet1!D:D и возвращать их в ответе. Параметр ValueRenderOption UNFORMATTED_VALUE указывает, что значения вычисляются, но не форматируются в ответе. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

Ответ на вызов этого метода состоит из объекта с идентификатором электронной таблицы и массива объектов ValueRange , соответствующих каждому запрошенному диапазону, перечисленных в том порядке, в котором они были запрошены. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам. Например:

{
  "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
    }
  ]
}

Чтение нескольких диапазонов на нескольких листах

В следующем примере кода spreadsheets.values.batchGet показано, как считывать значения из диапазонов на листах Sheet1!A1:D5, Products!D1:D100 и Sales!E4:F6 и возвращать их в ответе. Параметр ValueRenderOption UNFORMATTED_VALUE указывает, что значения вычисляются, но не форматируются в ответе. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

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

Ответ на вызов этого метода состоит из объекта с идентификатором электронной таблицы и массива объектов ValueRange , соответствующих каждому запрошенному диапазону, перечисленных в том порядке, в котором они были запрошены. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам. Например: 

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

API Google Sheets позволяет считывать значения из ячеек, диапазонов, наборов диапазонов и целых листов. Примеры на этой странице иллюстрируют некоторые распространенные операции чтения с ресурсом spreadsheets.values . Вы также можете прочитать значения ячеек с помощью метода spreadsheets.get , но обычно использовать spreadsheets.values.get или spreadsheets.values.batchGet проще.

Эти примеры представлены в виде HTTP-запросов, которые не зависят от языка. Чтобы узнать, как реализовать чтение на разных языках с помощью клиентских библиотек Google API, см. раздел Чтение и запись значений ячеек .

В этих примерах заполнитель SPREADSHEET_ID указывает, где вы должны указать идентификатор электронной таблицы , который можно найти по URL-адресу электронной таблицы. Диапазоны для чтения указываются с использованием нотации A1 в URL-адресе запроса. Пример диапазона: Лист1!A1:D5.

Исходные данные

В этих примерах предположим, что считываемая электронная таблица содержит следующие исходные данные на своем первом листе («Лист1»). Строки в первой строке являются метками отдельных столбцов. Чтобы просмотреть примеры чтения с других листов в электронной таблице, см. обозначение A1 .

А Б С Д
1 Элемент Расходы Запасено Дата отправки
2 Колесо 20,50 долларов США 4 01.03.2016
3 Дверь 15 долларов США 2 15.03.2016
4 Двигатель 100 долларов 1 20.03.2016
5 Итоги 135,5 долларов США 7 20.03.2016

Чтение одного диапазона

В следующем примере кода spreadsheets.values.get показано, как считывать значения из диапазона Sheet1!A1:D5 и возвращать их в ответе. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

Ответ состоит из объекта ValueRange , описывающего значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам.

{
  "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"]
  ],
}

Чтение одного диапазона, сгруппированного по столбцу

В следующем примере кода spreadsheets.values.get показано, как считывать значения из диапазона Sheet1!A1:D3 и возвращать их в ответе, но сгруппированные по столбцам. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

Ответ состоит из объекта ValueRange , описывающего значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам.

{
  "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"]
  ],
}

Чтение одного диапазона с параметрами рендеринга

В следующем примере кода spreadsheets.values.get показано, как считывать значения из диапазона Sheet1!A1:D5 и возвращать их в ответе, но для управления возвратом этой информации используются параметры отрисовки. Параметр ValueRenderOption для FORMULA указывает, что вместо вычисленного значения должны быть возвращены формулы, а параметр DateTimeRenderOption для SERIAL_NUMBER указывает, что даты должны быть возвращены в виде чисел. Возможны и другие настройки. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

Ответ состоит из объекта ValueRange , описывающего значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам.

{
  "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)"]
  ],
}

Чтение нескольких диапазонов

В следующем примере кода spreadsheets.values.batchGet показано, как считывать значения из диапазонов Sheet1!B:B и Sheet1!D:D и возвращать их в ответе. Параметр ValueRenderOption UNFORMATTED_VALUE указывает, что значения вычисляются, но не форматируются в ответе. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

Ответ на вызов этого метода состоит из объекта с идентификатором электронной таблицы и массива объектов ValueRange , соответствующих каждому запрошенному диапазону, перечисленных в том порядке, в котором они были запрошены. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам. Например:

{
  "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
    }
  ]
}

Чтение нескольких диапазонов на нескольких листах

В следующем примере кода spreadsheets.values.batchGet показано, как считывать значения из диапазонов на листах Sheet1!A1:D5, Products!D1:D100 и Sales!E4:F6 и возвращать их в ответе. Параметр ValueRenderOption UNFORMATTED_VALUE указывает, что значения вычисляются, но не форматируются в ответе. Пустые конечные строки и столбцы опускаются.

Протокол запроса показан здесь.

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

Ответ на вызов этого метода состоит из объекта с идентификатором электронной таблицы и массива объектов ValueRange , соответствующих каждому запрошенному диапазону, перечисленных в том порядке, в котором они были запрошены. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам. Например: 

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