Переход с Sheets API v3

Если у вас уже есть приложения, основанные на Google Sheets API версии 3, вы можете перейти на Google Sheets API версии 4. Версия 4 основана на JSON, имеет более удобный интерфейс и добавляет значительный объем функциональности, недоступной в версии 3.

На этой странице представлено сопоставление команд старого API Sheets версии 3 с эквивалентными операциями в API Sheets версии 4. Сопоставление в основном сосредоточено на коллекции spreadsheets.values , которая обеспечивает прямую функциональность чтения и записи ячеек. Другие аспекты, такие как добавление листов или обновление свойств листов, обрабатываются коллекцией spreadsheets . Обратите внимание, что структуры JSON в API версии 4 не обратно совместимы со структурами XML, используемыми в версии 3.

Для получения дополнительной информации о ресурсах, доступных в API Sheets v4, см. Справочник по API .

Обозначения и термины

В API версии 3 листы внутри конкретной электронной таблицы называются «рабочими листами». Это синонимично термину «листы», используемому в API версии 4.

API часто требуют указания идентификатора электронной таблицы , с которой вы работаете. Также часто требуется идентификатор листа, с которым вы работаете. Эти значения отображаются либо как часть URL-адреса конечной точки API, либо как параметры запроса, либо как часть тела запроса. На этой странице заполнители spreadsheetId и sheetId обозначают идентификаторы электронной таблицы и листа соответственно. При использовании методов, описанных на этой странице, подставьте фактические идентификаторы в эти места.

API версии 3 также присваивает идентификаторы строкам, полученным с помощью списка результатов поиска ; на этой странице это представлено заполнителем rowId .

Авторизация запросов

При запуске ваше приложение запрашивает у пользователей предоставление определенных разрешений; области действия, указанные в вашем приложении, определяют, какие разрешения оно запрашивает.

API версии 3

API Google Sheets версии 3 работает с единой областью авторизации:

https://spreadsheets.google.com/feeds

который является псевдонимом для

https://www.googleapis.com/auth/spreadsheets

Можно использовать любой из форматов области видимости.

API версии 4

API Google Sheets версии 4 использует один или несколько из следующих наборов областей видимости:

https://www.googleapis.com/auth/spreadsheets.readonly
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive

Используйте области доступа только для чтения, если вашему приложению не требуется вносить изменения в листы или свойства листов пользователя. Используйте области доступа к электронным таблицам вместо областей доступа к Диску, если приложению не требуется общий доступ к Диску.

Видимость

В более старых версиях API термин «видимость» использовался для обозначения доступности той или иной электронной таблицы.

API версии 3

API Google Sheets версии 3 напрямую указывает на видимость в своих конечных точках. public электронная таблица «опубликована в Интернете» и, следовательно, может быть доступна через API без авторизации, в то время как для доступа к private электронной таблице требуется аутентификация. Видимость указывается в конечной точке после идентификатора электронной таблицы:

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

API версии 4

В новой версии Sheets API v4 явное указание видимости отсутствует. Вызовы API выполняются с использованием идентификаторов электронных таблиц. Если у приложения нет разрешения на доступ к указанной электронной таблице, возвращается ошибка. В противном случае вызов продолжается.

Проекция

В API Google Sheets версии 3 термин «проекция» используется для обозначения набора данных, возвращаемых конкретным вызовом API — либо всех данных, либо фиксированного подмножества, определенного в API. API Google Sheets версии 4 не использует проекцию; вместо этого он предоставляет вам больший контроль над тем, какие данные возвращаются.

API версии 3

В Sheets API v3 возможны только два варианта проекции: full проекция возвращает всю доступную информацию, а basic — меньшее, фиксированное подмножество данных (для рабочих листов, списка и ячеек). Как и в случае с видимостью, проекцию необходимо указать в конечной точке API (после параметра видимости):

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic

Меньший набор данных, предоставляемый basic проекцией, ценен для повышения эффективности кода, но не может быть настроен.

API версии 4

Хотя Sheets API v4 может возвращать полный набор данных, он не определяет фиксированные подмножества, аналогичные basic настройке видимости в Sheets API v3. Методы в коллекции электронных таблиц ограничивают объем возвращаемых данных с помощью параметра запроса fields .

Например, следующий запрос возвращает только заголовки всех листов в конкретной электронной таблице:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

Создайте электронную таблицу

API версии 3

API Google Sheets версии 3 не предоставляет средств для создания новых электронных таблиц; вместо этого для создания новых файлов электронных таблиц можно использовать метод Files.create API Google Drive . Для этого приложению необходимо объявить область действия https://www.googleapis.com/auth/drive .

API версии 4

Метод Files.create API Google Drive также можно использовать с API Google Sheets версии 4, но для этого приложению необходимо указать область действия https://www.googleapis.com/auth/drive .

В качестве альтернативного варианта API Google Sheets версии 4 предоставляет метод spreadsheets.create , который также позволяет добавлять листы, устанавливать свойства электронной таблицы и листа, а также добавлять именованные диапазоны. Например, следующий код создает новую электронную таблицу и присваивает ей имя "NewTitle":

POST https://sheets.googleapis.com/v4/spreadsheets
{
 "properties": {"title": "NewTitle"}
}

Таблицы со списками для авторизованного пользователя

API версии 3

Канал Sheets API v3 позволяет приложению получать список всех электронных таблиц, доступных авторизованному пользователю. Конечная точка канала электронных таблиц:

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

API версии 4

API Google Sheets версии 4 не предоставляет эту конкретную операцию. Мы рекомендуем перевести ваше приложение на использование области видимости drive.file в сочетании с Google Picker для выбора элементов в электронных таблицах.

В тех случаях, когда требуется отображение списка электронных таблиц, это можно сделать с помощью метода Files.list в API Google Диска , используя запрос mimeType : 

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

Для отображения списка всех электронных таблиц пользователя с помощью метода files.list из API Google Drive требуется ограниченная область видимости.

Получить метаданные листа

API Sheets версии 3 предоставляет канал для доступа к метаданным листа, содержащимся в заданной электронной таблице (доступ к данным строк и ячеек осуществляется через отдельный канал). Метаданные включают такую ​​информацию, как заголовки листов и сведения о размерах.

Метод spreadsheets.get в Sheets API v4 предоставляет доступ к этой информации и многому другому.

API версии 3

Доступ к ленте рабочих таблиц осуществляется через эту конечную точку API (с использованием соответствующего заголовка авторизации): 

GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

Ответ на этот запрос имеет аналогичную структуру, при этом данные каждого листа содержатся в отдельной <entry> ): 

<feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006"
    xmlns:gd="http://schemas.google.com/g/2005"
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <title type="text">Groceries R Us</title>
  <link rel="alternate" type="text/html"
      href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
  <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>fitz@example.com</email>
  </author>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
  <entry gd:etag='"YDwqeyI."'>
    <id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
    <updated>2006-11-17T18:23:45.173Z</updated>
    <title type="text">Sheet1</title>
    <content type="text">Sheet1</content>
    <link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
        type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
    <link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
        type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
    <link rel="self" type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
    <link rel="edit" type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
    <gs:rowCount>100</gs:rowCount>
    <gs:colCount>20</gs:colCount>
  </entry>
</feed>

API версии 4

Метод spreadsheets.get позволяет получать свойства листа и другие метаданные — гораздо больше, чем доступно в Sheets API версии 3. Если вам нужно только прочитать свойства листа, установите параметр запроса includeGridData в false , чтобы предотвратить включение данных ячеек электронной таблицы: 

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

В ответе Spreadsheet содержится массив объектов Sheet ; заголовки листов и информация о размерах находятся в элементе SheetProperties этих объектов. Например: 

{
  "spreadsheetId": spreadsheetId,
  "sheets": [
      {"properties": {
          "sheetId": sheetId,
          "title": "Sheet1",
          "index": 0,
          "gridProperties": {
              "rowCount": 100,
              "columnCount": 20,
              "frozenRowCount": 1,
              "frozenColumnCount": 0,
              "hideGridlines": false
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

Добавить лист в электронную таблицу

Оба API позволяют добавлять новые листы в существующую электронную таблицу.

API версии 3

API Google Sheets версии 3 позволяет добавлять новые листы в электронную таблицу, отправляя следующий (аутентифицированный) POST запрос. Вы можете указать размер нового листа: 

POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <title>Expenses</title>
  <gs:rowCount>50</gs:rowCount>
  <gs:colCount>10</gs:colCount>
</entry>

API версии 4

Добавить новые листы можно, отправив запрос AddSheet в методе spreadsheets.batchUpdate . В теле запроса можно указать свойства нового листа; все свойства являются необязательными. Указание заголовка, используемого для существующего листа, приведет к ошибке. 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [{
      "addSheet": {
          "properties": {
            "title": "Expenses",
            "sheetType": "GRID",
            "gridProperties": {
              "rowCount": 50,
              "columnCount": 10
            }
          }
      }
  }],
}

Изменить заголовок и размер листа

API Sheets версии 3 позволяет обновлять заголовки и размер листов; API Sheets версии 4 также позволяет это делать, но может использоваться и для обновления других свойств листа. Обратите внимание, что уменьшение размера листа может привести к удалению данных в обрезанных ячейках без предупреждения.

API версии 3

Чтобы изменить заголовок или размер листа, сначала получите ленту листов и найдите нужную запись, содержащую URL-адрес edit . Обновите метаданные листа и отправьте их в качестве тела PUT запроса на URL-адрес редактирования. Например: 

PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
  <id>
    https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
  </id>
  <updated>2007-07-30T18:51:30.666Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
  <title type="text">Expenses</title>
  <content type="text">Expenses</content>
  <link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
    type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
  <link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
    type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
  <gs:rowCount>45</gs:rowCount>
  <gs:colCount>15</gs:colCount>
</entry>

API версии 4

Для обновления размера, заголовка и других свойств листа выполните запрос updateSheetProperties в методе spreadsheets.batchUpdate . Тело POST запроса должно содержать свойства, которые необходимо изменить, а параметр fields должен явно перечислять эти свойства (если вы хотите обновить все свойства, используйте fields:"*" в качестве сокращения для их перечисления). Например, следующий запрос указывает, что для листа с заданным ID должны быть обновлены свойства заголовка и размера: 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "updateSheetProperties": {
          "properties": {
            "sheetId": sheetId,
            "title": "Expenses",
            "gridProperties": {
              "rowCount": 45,
              "columnCount": 15,
            }
          },
          "fields": "title,gridProperties(rowCount,columnCount)"
     }
   }
  ],
}

Чтобы получить sheetId листа, используйте метод spreadsheets.get для работы с электронными таблицами.

Удалить лист

Любой из API позволяет удалять листы из заданной электронной таблицы.

API версии 3

Чтобы удалить лист, сначала получите ленту листов , а затем отправьте запрос DELETE по URL-адресу edit целевой записи листа. 

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

API версии 4

Для удаления листа выполните запрос DeleteSheet в методе spreadsheets.batchUpdate . Тело POST запроса должно содержать только sheetId удаляемого листа. Например: 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

Чтобы получить sheetId листа (sheetId) отдельного листа, используйте метод spreadsheets.get в таблице.

Извлечение данных строки

Доступ к данным в ячейках электронной таблицы через список строк — это один из двух методов, предоставляемых API Sheets версии 3 (другой — доступ через ячейки ). Доступ через строки предназначен для поддержки распространенных операций с электронными таблицами (построчное чтение, добавление строк, сортировка), но делает определенные предположения, которые делают его непригодным для некоторых задач. В частности, доступ через список строк предполагает, что пустые строки являются завершением потока данных, и что в первой строке листа присутствуют обязательные заголовки.

В отличие от этого, API Sheets версии 4 не использует методы доступа, привязанные к строкам. Вместо этого доступ к данным ячеек листа осуществляется путем ссылки на необходимые диапазоны с использованием обозначения A1 . Диапазоны могут представлять собой блоки ячеек, целые строки, целые столбцы или целые листы. API также может получать доступ к непересекающимся наборам ячеек.

API версии 3

Чтобы определить URL-адрес ленты новостей в виде списка для заданного листа, получите ленту новостей этого листа и найдите URL-адрес ленты новостей в интересующей вас записи листа.

Для получения ленты новостей в виде списка отправьте GET запрос на URL-адрес ленты новостей, используя соответствующий заголовок авторизации. Например: 

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

Ответ на этот запрос содержит, помимо прочего, записи, соответствующие конкретным строкам. На отдельные ячейки ссылаются имена, указанные в (обязательной) строке заголовка листа. Например, вот запись из одной строки: 

<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
      term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>10</gsx:hours>
  <gsx:items>2</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

По умолчанию строки, отображаемые в списке, возвращаются в порядке следования строк. API Google Sheets версии 3 предоставляет параметры запроса для изменения этого порядка.

Обратный порядок: 

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true

Сортировать по определенному столбцу: 

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?orderby=column:lastname

API Google Sheets версии 3 также позволяет фильтровать определенные строки с помощью структурированного запроса (на который ссылаются заголовки столбцов): 

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

API версии 4

В версии 4 API таблиц можно получать строки по диапазону, используя методы spreadsheets.values.get или spreadsheets.values.batchGet . Например, следующий код возвращает все строки в "Sheet1": 

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

Ответ на этот запрос имеет следующую структуру: 

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

При извлечении целых строк, столбцов или листов пустые ячейки в конце строки не учитываются в ответе.

В Sheets API версии 4 отсутствуют аналоги параметров запроса для сортировки по строкам, предоставляемых Sheets API версии 3. Сортировка в обратном порядке тривиальна; достаточно обработать возвращаемый массив values в обратном порядке. Сортировка по столбцам не поддерживается для чтения, но можно отсортировать данные в запросе к таблице (используя SortRange ), а затем прочитать их.

В настоящее время в Sheets API версии 4 нет прямого аналога структурированным запросам Sheets API версии 3. Однако вы можете получить необходимые данные и отсортировать их по мере необходимости в своем приложении.

Добавить новую строку данных

Добавить новую строку данных в таблицу можно с помощью любого из API.

API версии 3

Чтобы определить URL-адрес ленты новостей в виде списка для заданного листа, получите ленту новостей листа и найдите URL-адрес публикации в интересующей вас записи листа.

Для добавления строки данных отправьте POST запрос на указанный URL-адрес, используя соответствующий заголовок авторизации. Например: 

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

Тело POST запроса должно содержать запись для добавления данных из строк, при этом ссылки на отдельные ячейки должны быть указаны в заголовках столбцов: 

<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
  <gsx:hours>2</gsx:hours>
  <gsx:ipm>0.5</gsx:ipm>
  <gsx:items>60</gsx:items>
  <gsx:name>Elizabeth</gsx:name>
</entry>

Новые строки добавляются в конец указанного листа.

API версии 4

В Sheets API версии 4 можно добавлять строки с помощью метода spreadsheets.values.append . В следующем примере новая строка данных записывается под последней таблицей на листе "Sheet1" электронной таблицы. 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Кроме того, Sheets API v4 также позволяет добавлять ячейки с определенными свойствами и форматированием с помощью запросов AppendCells в методе spreadsheets.batchUpdate .

Отредактируйте строку, добавив новые данные.

Оба API позволяют обновлять данные строк новыми значениями.

API версии 3

Чтобы отредактировать строку данных, просмотрите список записей , чтобы найти нужную запись. При необходимости обновите содержимое этой записи. Убедитесь, что значение ID в используемой записи точно совпадает со значением ID существующей записи.

После обновления записи отправьте PUT запрос с указанной в теле запроса записью на URL-адрес edit , указанный в этой строке, используя соответствующий заголовок авторизации. Например: 

PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>20</gsx:hours>
  <gsx:items>4</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

API версии 4

В Sheets API версии 4 вы можете редактировать строку, используя обозначение ячейки A1 , и отправлять запрос spreadsheets.values.update для перезаписи этой строки. Указанный диапазон должен относиться только к первой ячейке строки; API определяет ячейки для обновления на основе значений, предоставленных в запросе. Если вы укажете диапазон из нескольких ячеек, предоставленные вами значения должны укладываться в этот диапазон; в противном случае API вернет ошибку.

В приведенном ниже примере запроса и тела запроса данные добавляются в четвертую строку листа "Sheet1": 

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Также можно обновлять данные строк с помощью метода spreadsheet.values.batchUpdate ; этот метод более эффективен, если вы обновляете несколько строк или ячеек.

Кроме того, Sheets API v4 также позволяет редактировать свойства ячеек и форматирование ячеек с помощью запросов UpdateCells или RepeatCell в методе spreadsheets.batchUpdate .

Удалить строку

Оба API поддерживают удаление строк. Удалённая строка удаляется из электронной таблицы, а строки ниже неё сдвигаются на одну позицию вверх.

API версии 3

Чтобы удалить строку, сначала получите строку для удаления из списка , а затем отправьте запрос DELETE на URL-адрес edit , указанный в записи строки. Это тот же URL-адрес, который использовался для обновления строки. 

DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

Чтобы гарантировать, что вы не удалите строку, измененную другим клиентом после ее получения, добавьте HTTP-заголовок If-Match, содержащий значение ETag исходной строки. Вы можете определить значение ETag исходной строки, изучив атрибут gd:etag элемента записи.

Если вы хотите удалить строку независимо от того, обновлял ли её кто-то другой после получения, используйте условие If-Match: * и не включайте ETag. (В этом случае вам не нужно получать строку перед удалением.)

API версии 4

Удаление строк с помощью Sheets API v4 осуществляется вызовом метода spreadsheet.batchUpdate с использованием запроса DeleteDimension . Этот запрос также можно использовать для удаления столбцов, и разработчики могут выбрать удаление только части строки или столбца. Например, следующий код удаляет 6-ю строку листа с заданным ID (индексы строк начинаются с нуля, начиная с startIndex и заканчивая endIndex): 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

sheetId листа (sheetId) можно получить с помощью метода spreadsheet.get .

Получить данные ячейки

API Sheets версии 3 предоставляет канал данных по ячейкам для базового доступа ко всем данным, хранящимся в электронной таблице. Для доступа на чтение канал данных по ячейкам может предоставлять либо всё содержимое листа, либо диапазон ячеек листа, определяемый набором параметров запроса, но только в виде единого блока — непересекающиеся диапазоны необходимо получать отдельно с помощью дополнительных GET запросов.

API Sheets версии 4 позволяет получать любой набор данных ячеек из листа (включая несколько непересекающихся диапазонов). API Sheets версии 3 может возвращать содержимое ячеек только в виде входных значений (введенных пользователем с клавиатуры) и/или результатов формул (если они числовые); API Sheets версии 4 предоставляет полный доступ к значениям, формулам, форматированию, гиперссылкам, проверке данных и другим свойствам.

API версии 3

Чтобы определить URL-адрес ленты новостей, привязанной к ячейке, для заданного листа, изучите ленту новостей листа и найдите URL-адрес ленты новостей в интересующей вас записи листа.

Для получения ленты новостей из ячейки отправьте GET запрос на URL-адрес ленты, используя соответствующий заголовок авторизации. Например: 

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

Ссылки на ячейки осуществляются с помощью номера строки и столбца. Получение определенного диапазона можно выполнить с помощью параметров запроса max-row , min-row , max-col и min-col . Например, следующий код извлекает все ячейки в столбце 4 (D), начиная со строки 2: 

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

API Google Sheets версии 3 возвращает inputValue полученных ячеек — значение, которое пользователь обычно вводит в интерфейс Google Sheets для управления ячейкой. inputValue может быть литеральным значением или формулой. API также иногда возвращает numericValue ; например, когда формула выдает число. Например, ответ может содержать записи ячеек, похожие по структуре на следующие: 

<entry gd:etag='"ImB5CBYSRCp7"'>
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
  <updated>2006-11-17T18:27:32.543Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#cell"/>
  <title type="text">D4</title>
  <content type="text">5</content>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
  <gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
    numericValue="5.0">5</gs:cell>
</entry>

API версии 4

Получение данных из ячеек осуществляется путем вызова метода spreadsheets.values.get или spreadsheets.values.batchGet для интересующего диапазона или диапазонов соответственно. Например, следующий код возвращает ячейки в столбце D листа "Sheet2", начиная со строки 2, в порядке столбцов и возвращает формулы в том виде, в котором они были введены (пустые ячейки в конце опускаются): 

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

Ответ на этот запрос по структуре аналогичен следующему: 

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
      {"range": "Sheet2!D2:D",
       "majorDimension": "COLUMNS",
       "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
      }]
}

Использование метода spreadsheet.values.batchGet более эффективно, если вы планируете получать данные из нескольких диапазонов ячеек. Если вам нужен доступ к свойствам ячеек, таким как форматирование, необходим метод spreadsheet.get .

Редактировать ячейку

API Google Sheets версии 3 позволяет редактировать содержимое ячеек, отправляя команду PUT в канал ячеек, указав в качестве тела запроса измененную запись в ячейке.

В отличие от этого, Sheets API v4 предоставляет методы spreadsheets.values.update и spreadsheets.values.batchUpdate для изменения содержимого ячеек.

API версии 3

Чтобы отредактировать содержимое отдельной ячейки, сначала найдите запись этой ячейки в ленте ячеек . Запись содержит URL-адрес для редактирования. Обновите запись, указав желаемое содержимое ячейки, а затем отправьте PUT запрос на URL-адрес редактирования, указав обновленную запись ячейки в качестве тела запроса. Например, следующий код обновляет ячейку D2 (R2C4), добавляя формулу SUM : 

PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc


<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/>
  <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/>
</entry>

API версии 4

Редактирование отдельных ячеек в Sheets API v4 можно выполнить с помощью метода spreadsheets.values.update . Этот метод требует параметра запроса ValueInputOption , который указывает, обрабатываются ли входные данные так, как если бы они были введены в пользовательский интерфейс Sheets ( USER_ENTERED ), или остаются необработанными и принимаются как есть ( RAW ). Например, следующий код обновляет ячейку D2 формулой: 

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}

Если вы вносите изменения в несколько ячеек, используйте метод spreadsheets.values.batchUpdate , чтобы выполнить их в одном запросе.

Редактирование нескольких ячеек с помощью пакетного запроса

Оба API предоставляют средства для внесения изменений в содержимое нескольких ячеек с помощью одного (пакетного) запроса. Ячейки, на которые ссылается пакетный запрос, не обязательно должны находиться в смежном диапазоне.

В случае, если одно или несколько изменений ячеек в пакете завершаются неудачей, Sheets API v3 позволяет успешно выполнить остальные. Однако Sheets API v4 возвращает ошибку, если какое-либо из обновлений в пакете завершается неудачей, и в этом случае ни одно из них не применяется.

API версии 3

Для редактирования нескольких ячеек сначала получите список ячеек для листа. Запись содержит URL-адрес для пакетной обработки. Отправьте POST запрос на этот URL-адрес, указав в теле запроса ячейки, которые вы хотите обновить, и их новое содержимое. POST -запрос и тело запроса имеют структуру, аналогичную следующей: 

POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:batch="http://schemas.google.com/gdata/batch"
      xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
  <entry>
    <batch:id>request1</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
    <gs:cell row="2" col="4" inputValue="newData"/>
  </entry>
  ...
  <entry>
    <batch:id>request2</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
    <gs:cell row="5" col="2" inputValue="moreInfo"/>
  </entry>
</feed>

Поле batch:id должно однозначно идентифицировать запрос в пакете. Поле batch:operation должно update при редактировании ячеек. gs:cell идентифицирует ячейку по номеру строки и столбца и предоставляет новые данные для вставки. Поле id содержит полный URL-адрес ячейки, которую необходимо обновить. link должно иметь атрибут href , содержащий полный путь к идентификатору ячейки. Все эти поля обязательны для каждой записи.

API версии 4

API Google Sheets версии 4 позволяет выполнять пакетное редактирование значений ячеек с помощью метода spreadsheets.values.batchUpdate .

Редактирование нескольких ячеек одновременно можно выполнить, отправив POST запрос с указанием изменений данных в теле запроса. Например: 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
  "valueInputOption": "USER_ENTERED"
  "data": [
       {"range": "D4",
        "majorDimension": "ROWS",
        "values": [["newData"]]
       },
       {"range": "B5",
        "majorDimension": "ROWS",
        "values": [["moreInfo"]]
       }
  ]
}

Если вы указали диапазон в одну ячейку, все предоставленные значения будут записаны на лист, начиная с этой ячейки в качестве координаты верхнего левого угла. Если же вы укажете диапазон в несколько ячеек, предоставленные вами значения должны точно соответствовать этому диапазону; в противном случае API вернет ошибку.