Если у вас уже есть приложения на базе API Google Таблиц v3, вы можете перейти на API Google Таблиц v4. Версия v4 основана на JSON, имеет более простой в использовании интерфейс и добавляет значительный объём функций, недоступных в версии v3.
На этой странице представлено сопоставление между старыми командами API Таблиц v3 и их эквивалентными операциями в API Таблиц v4. Сопоставление в основном сосредоточено на коллекции spreadsheets.values , которая обеспечивает прямое чтение и запись ячеек. Другие функции, такие как добавление листов или обновление свойств листов, обрабатываются коллекцией spreadsheets . Обратите внимание, что структуры JSON API v4 несовместимы с XML-структурами, используемыми в v3.
Дополнительную информацию о ресурсах, доступных в API Таблиц v4, см. в Справочнике по API .
Обозначения и термины
В API версии 3 листы внутри конкретной электронной таблицы называются «рабочими листами». Это синоним термина «листы», используемого в API версии 4.
API часто требуют указать идентификатор таблицы, с которой вы работаете. Также часто требуется идентификатор обрабатываемого листа. Эти значения отображаются либо как часть URL-адреса конечной точки API, либо как параметры запроса, либо как часть тела запроса. На этой странице плейсхолдеры spreadsheetId и sheetId обозначают идентификаторы таблицы и листа соответственно. При использовании методов, описанных на этой странице, подставляйте в эти места фактические идентификаторы.
API v3 также назначает идентификатор строкам, извлеченным с помощью его списка каналов ; на этой странице это представлено заполнителем rowId .
Авторизовать запросы
При запуске вашего приложения оно запрашивает у пользователей определенные разрешения; области действия, которые вы указываете в своем приложении, определяют, какие разрешения оно запрашивает.
API v3
API Таблиц v3 работает с единой областью авторизации:
https://spreadsheets.google.com/feeds
который является псевдонимом для
https://www.googleapis.com/auth/spreadsheets
Можно использовать любой из форматов области действия.
API v4
API Таблиц v4 использует один или несколько из следующих наборов областей:
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 v3
API Таблиц v3 определяет видимость непосредственно в своих конечных точках. public таблица «опубликована в Интернете» и, таким образом, доступна API без авторизации, в то время как для private таблицы требуется аутентификация. Видимость указывается в конечной точке после идентификатора таблицы:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API v4
В новом API Таблиц версии 4 нет явного объявления видимости. Вызовы API выполняются с использованием идентификаторов электронных таблиц. Если у приложения нет разрешения на доступ к указанной таблице, возвращается ошибка. В противном случае вызов продолжается.
Проекция
Термин «проекция» используется в API Таблиц v3 для обозначения набора данных, возвращаемых данным вызовом API — либо всех данных, либо фиксированного подмножества, определённого в API. API Таблиц v4 не использует проекцию, а предоставляет больше контроля над возвращаемыми данными.
API v3
В API Таблиц версии 3 доступны только два возможных параметра проекции. full проекция возвращает всю доступную информацию, тогда как basic — меньший фиксированный подмножество данных (для листов, списков и каналов ячеек). Как и видимость, проекция должна быть указана в конечной точке API (после параметра видимости):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Меньший подмножество данных, предоставляемое basic проекцией, ценно для повышения эффективности кода, но не может быть настроен.
API v4
Хотя API Таблиц v4 может возвращать полный набор данных, он не определяет фиксированные подмножества, аналогичные basic настройке видимости в API Таблиц v3. Методы в коллекции электронных таблиц ограничивают объём возвращаемых данных с помощью параметра запроса «поля» .
Например, следующий запрос возвращает только заголовки всех листов в определенной электронной таблице:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Создать электронную таблицу
API v3
API Таблиц v3 не предоставляет возможности создания новых электронных таблиц. Вместо этого для создания новых файлов электронных таблиц можно использовать метод Files.create API Диска . Для этого приложение должно указать область действия https://www.googleapis.com/auth/drive .
API v4
Метод Files.create API Drive также можно использовать с API Таблиц v4, но для этого приложение должно предоставить область действия https://www.googleapis.com/auth/drive .
В качестве эквивалентной альтернативы API Таблиц v4 предоставляет метод spreadsheets.create , который также может опционально добавлять листы, задавать свойства таблицы и листа, а также добавлять именованные диапазоны. Например, следующий код создаёт новую таблицу и присваивает ей имя «NewTitle»:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Список электронных таблиц для аутентифицированного пользователя
API v3
Канал API Таблиц v3 позволяет приложению получать список всех электронных таблиц, доступных аутентифицированному пользователю. Конечная точка канала:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
API Таблиц версии 4 не поддерживает эту функцию. Мы рекомендуем перенести приложение на использование области действия drive.file в сочетании с Google Picker для выбора электронных таблиц.
В случаях, когда требуются электронные таблицы со списком, их можно реплицировать с помощью метода Drive API Files.list , используя запрос mimeType :
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'Использование метода API Drive files.list для вывода списка всех электронных таблиц пользователя требует ограниченной области действия.
Извлечь метаданные листа
API Таблиц v3 предоставляет канал для доступа к метаданным листа, содержащимся в данной электронной таблице (данные строк и ячеек доступны через отдельный канал). Метаданные включают в себя такую информацию, как заголовки листов и сведения о размере.
Метод spreadsheets.get API Таблиц v4 обеспечивает доступ к этой информации и многому другому.
API v3
Канал рабочих листов доступен из этой конечной точки 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 v4
Метод spreadsheets.get можно использовать для получения свойств листа и других метаданных — гораздо большего количества, чем доступно в API Таблиц v3. Если вам нужно только прочитать свойства листа, установите для параметра запроса 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 v3
API Таблиц v3 позволяет добавлять новые листы в электронную таблицу, выполняя следующий (аутентифицированный) 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 v4
Вы можете добавить новые листы, выполнив запрос 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 Таблиц v3 позволяет обновлять заголовки и размеры листов; API Таблиц v4 также позволяет это делать, но его также можно использовать для обновления других свойств листа. Обратите внимание, что уменьшение размера листа может привести к безпредупреждающему удалению данных в обрезанных ячейках.
API v3
Чтобы изменить заголовок или размер листа, сначала откройте фид листов и найдите нужную запись листа, содержащую 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 v4
Чтобы обновить размер, заголовок и другие свойства листа, выполните запрос updateSheetProperties в методе spreadsheets.batchUpdate . Тело запроса POST должно содержать изменяемые свойства, а параметр fields должен явно перечислять эти свойства (если вы хотите обновить все свойства, используйте fields:"*" в качестве сокращения для их перечисления). Например, следующий код указывает, что свойства заголовка и размера листа должны быть обновлены для листа с заданным идентификатором:
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 v3
Чтобы удалить рабочий лист, начните с получения фида рабочих листов , затем отправьте запрос DELETE на URL-адрес edit целевой записи рабочего листа.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API v4
Чтобы удалить лист, выполните запрос DeleteSheet в методе spreadsheets.batchUpdate . Тело POST -запроса должно содержать только sheetId листа, который нужно удалить. Например:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Чтобы получить sheetId отдельного листа, используйте метод spreadsheet spreadsheets.get .
Извлечь данные строки
Лента строк списка — один из двух методов, предоставляемых API Таблиц v3 для доступа к данным в ячейках электронной таблицы (второй — лента ячеек ). Лента строк предназначена для поддержки распространённых операций с электронными таблицами (построчное чтение, добавление строк, сортировка), но имеет определённые допущения, делающие её непригодной для некоторых задач. В частности, лента списка предполагает, что пустые строки являются конечными точками ленты, а обязательные заголовки присутствуют в первой строке листа.
В отличие от этого, API Таблиц v4 не использует методы доступа, привязанные к строкам. Вместо этого доступ к данным ячеек листа осуществляется путём ссылки на требуемые диапазоны с использованием нотации A1 . Диапазоны могут представлять собой блоки ячеек, целые строки, целые столбцы или целые листы. API также может обращаться к непересекающимся наборам ячеек.
API v3
Чтобы определить 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 Таблиц v3 предоставляет параметры запроса для изменения этого порядка.
Обратный порядок:
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:lastnameAPI Таблиц v3 также позволяет фильтровать определенные строки с помощью структурированного запроса (на который ссылаются заголовки столбцов):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
С помощью API Таблиц версии 4 строки можно извлекать по диапазону, используя методы spreadsheets.values.get или spreadsheets.values.batchGet . Например, следующий код возвращает все строки в таблице «Лист1»:
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"]]
}При извлечении целых строк, столбцов или листов конечные пустые ячейки не включаются в ответ.
В API Таблиц v4 нет аналогов для параметров запроса порядка строк, предоставляемых API Таблиц v3. Обратный порядок тривиален; просто обработайте массив возвращаемых values в обратном порядке. Сортировка по столбцу не поддерживается для чтения, но можно отсортировать данные в таблице (с помощью запроса SortRange ) и затем прочитать их.
В настоящее время в API Таблиц v4 нет прямого аналога для структурированных запросов API Таблиц v3. Тем не менее, вы можете извлекать соответствующие данные и сортировать их по мере необходимости в вашем приложении.
Добавить новую строку данных
Добавить новую строку данных на лист можно с помощью любого из API.
API v3
Чтобы определить 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 v4
С помощью API Таблиц версии 4 можно добавлять строки, используя метод spreadsheets.values.append . В следующем примере новая строка данных добавляется под последней таблицей на листе «Лист1» электронной таблицы.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Кроме того, API Таблиц v4 также позволяет добавлять ячейки с определенными свойствами и форматированием с помощью запросов AppendCells в spreadsheets.batchUpdate .
Редактировать строку с новыми данными
Оба API позволяют обновлять данные строк новыми значениями.
API v3
Чтобы отредактировать строку данных, найдите в ленте списка запись, соответствующую нужной строке. При необходимости обновите содержимое этой записи. Убедитесь, что значение идентификатора в используемой записи точно совпадает с идентификатором существующей записи.
После обновления записи отправьте 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 v4
С помощью API Таблиц v4 вы можете редактировать строку, используя нотацию A1 для редактируемой строки и выполнив запрос spreadsheets.values.update для её перезаписи. Указанный диапазон должен относиться только к первой ячейке в строке; API определяет ячейки для обновления на основе значений, предоставленных в запросе. Если вместо этого указать диапазон из нескольких ячеек, предоставляемые значения должны соответствовать этому диапазону; в противном случае API возвращает ошибку.
Следующий пример запроса и тела запроса добавляет данные в четвертую строку «Листа1»:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Вы также можете обновить данные строк из метода spreadsheet.values.batchUpdate ; этот метод более эффективен, если вы обновляете несколько строк или ячеек.
Кроме того, API Таблиц v4 также позволяет редактировать свойства ячеек и форматирование ячеек с помощью запросов UpdateCells или RepeatCell в spreadsheets.batchUpdate .
Удалить строку
Оба API поддерживают удаление строк. Удалённая строка удаляется из таблицы, а строки, расположенные ниже, поднимаются на одну позицию вверх.
API v3
Чтобы удалить строку, сначала извлеките её из ленты списка , а затем отправьте запрос 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 v4
Удаление строк в API Таблиц v4 осуществляется вызовом метода spreadsheet.batchUpdate с использованием запроса DeleteDimension . Этот запрос также можно использовать для удаления столбцов, и разработчики могут выбрать удаление только части строки или столбца. Например, следующий код удаляет шестую строку листа с заданным идентификатором (индексы строк начинаются с нуля, startIndex включается, endIndex не включается):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}Идентификатор листа sheetId можно получить с помощью метода spreadsheet.get .
Извлечь данные ячейки
API Таблиц v3 предоставляет канал ячеек для базового доступа ко всем данным, хранящимся в электронной таблице. Для чтения канал ячеек может предоставлять всё содержимое листа или диапазон ячеек листа, определённый набором параметров запроса, но только единым блоком — непересекающиеся диапазоны необходимо извлекать отдельно с помощью дополнительных GET запросов.
API Таблиц v4 позволяет извлекать любые наборы данных ячеек из листа (включая несколько непересекающихся диапазонов). API Таблиц v3 может возвращать содержимое ячеек только в виде входных значений (в том виде, в каком оно было бы введено пользователем с клавиатуры) и/или результатов формулы (если это числовые данные); API Таблиц v4 предоставляет полный доступ к значениям, формулам, форматированию, гиперссылкам, проверке данных и другим свойствам.
API v3
Чтобы определить 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=4API Таблиц v3 возвращает inputValue извлеченных ячеек — значение, которое пользователь в противном случае ввёл бы в интерфейсе Google Таблиц для работы с ячейкой. 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 v4
Извлеките данные из ячеек, вызвав метод spreadsheets.values.get или spreadsheets.values.batchGet для интересующего диапазона или диапазонов соответственно. Например, следующий код возвращает ячейки столбца D листа «Лист2», начиная со строки 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 Таблиц v3 позволяет редактировать содержимое ячеек, отправляя команду PUT в канал ячеек, используя измененную запись ячейки в качестве тела запроса.
В отличие от этого, API Таблиц v4 предоставляет методы spreadsheets.values.update и spreadsheets.values.batchUpdate для изменения содержимого ячеек.
API v3
Чтобы изменить содержимое одной ячейки, сначала найдите запись об этой ячейке в ленте данных . Запись содержит 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 v4
Редактирование отдельных ячеек в API Таблиц v4 можно выполнить с помощью метода spreadsheets.values.update . Этот метод требует параметра запроса ValueInputOption , который указывает, следует ли обрабатывать входные данные так, как будто они введены в интерфейс Таблиц ( 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 предоставляют возможность вносить изменения в содержимое нескольких ячеек одним (пакетным) запросом. Ячейки, на которые ссылается пакетный запрос, не обязательно должны находиться в непрерывном диапазоне.
В случае сбоя одного или нескольких изменений в пакете, API Таблиц v3 позволяет остальным успешно выполнить изменения. Однако API Таблиц v4 возвращает ошибку, если какое-либо из изменений в пакете завершается сбоем, и в этом случае не применяет ни одно из изменений.
API v3
Чтобы отредактировать несколько ячеек, сначала получите канал ячеек для рабочего листа. Запись содержит 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 v4
API Таблиц v4 обеспечивает пакетное редактирование значений ячеек с помощью метода 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 возвращает ошибку.