Если у вас есть приложения на основе Google Sheets API v3, вы можете перейти на Google Sheets API v4. Версия v4 основана на JSON, имеет более простой в использовании интерфейс и добавляет значительный объем функций, недоступных в версии v3.
На этой странице представлено сопоставление старых команд Sheets API v3 и их эквивалентных операций в Sheets API v4. Сопоставление в основном сосредоточено на коллекции электронных таблиц.значения , которая обеспечивает функции прямого чтения и записи ячеек. Другие аспекты, такие как добавление листов или обновление свойств листов, обрабатываются коллекцией электронных таблиц . Обратите внимание, что структуры JSON API версии 4 не имеют обратной совместимости со структурами XML, используемыми в версии 3.
Дополнительную информацию о ресурсах, доступных в API Sheets v4, см. в Справочнике по API .
Обозначения и термины
API версии 3 называет листы в конкретной электронной таблице «рабочими листами». Это синоним термина «листы», который использует API версии 4.
API часто требуют, чтобы вы указали идентификатор таблицы , с которой вы работаете. Им также часто требуется идентификатор листа, которым манипулируют. Эти значения отображаются либо как часть URL-адреса конечной точки API, либо как параметры запроса, либо как часть тела запроса. На этой странице заполнители spreadsheetId и sheetId относятся к идентификаторам электронной таблицы и листа соответственно. При использовании методов, описанных на этой странице, замените фактические идентификаторы в этих местах.
API версии 3 также присваивает идентификатор строкам, полученным с помощью канала списка ; на этой странице это представлено заполнителем rowId .
Авторизовать запросы
Когда ваше приложение запускается, оно просит пользователей предоставить определенные разрешения; области, которые вы указываете в своем приложении, определяют, какие разрешения оно запрашивает.
API v3
Sheets API v3 работает с единой областью авторизации:
https://spreadsheets.google.com/feeds
это псевдоним для
https://www.googleapis.com/auth/spreadsheets
Можно использовать любой формат области.
v4 API
Sheets 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
Sheets API v3 обеспечивает видимость непосредственно в своих конечных точках. public электронная таблица «опубликована в Интернете», и поэтому к ней можно получить доступ через API без авторизации, тогда как private электронная таблица требует аутентификации. Видимость указывается в конечной точке после идентификатора таблицы:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
v4 API
В новом Sheets API v4 нет явного объявления видимости. Вызовы API выполняются с использованием идентификаторов электронных таблиц. Если у приложения нет разрешения на доступ к указанной электронной таблице, возвращается ошибка. В противном случае вызов продолжается.
Проекция
Термин « проекция» используется в Sheets API v3 для обозначения набора данных, возвращаемых данным вызовом API — либо всех, либо фиксированного подмножества, определенного в API. Sheets API v4 не использует проекцию; скорее, это позволяет вам лучше контролировать, какие данные возвращаются.
API v3
В Sheets API v3 есть только две возможные настройки проекции. full проекция возвращает всю доступную информацию, тогда как basic возвращает меньший фиксированный подмножество данных (для листов, списков и каналов ячеек). Как и видимость, проекция должна быть указана в конечной точке API (после настройки видимости):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Меньшее подмножество данных, предоставляемое basic проекцией, полезно для повышения эффективности кода, но его нельзя настроить.
v4 API
Хотя Sheets API v4 может возвращать полный набор данных, он не определяет фиксированные подмножества, аналогичные basic настройке видимости Sheets API v3. Методы в коллекции электронных таблиц ограничивают объем данных, которые они возвращают, с помощью параметра запроса полей .
Например, следующий запрос возвращает только заголовки всех листов в определенной электронной таблице:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Создать электронную таблицу
API v3
Sheets API v3 не предоставляет средств для создания новых электронных таблиц; вместо этого метод Drive API Files.create можно использовать для создания новых файлов электронных таблиц. Для этого приложение должно объявить область действия https://www.googleapis.com/auth/drive .
v4 API
Метод Drive API Files.create также можно использовать с Sheets API v4, но для этого требуется, чтобы приложение предоставило область https://www.googleapis.com/auth/drive .
В качестве эквивалентной альтернативы Sheets API v4 предоставляет метод электронная таблица.create , который также может при необходимости добавлять листы, устанавливать свойства электронной таблицы и листа, а также добавлять именованные диапазоны. Например, следующая команда создает новую электронную таблицу и присваивает ей имя «NewTitle»:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Список электронных таблиц для аутентифицированного пользователя
API v3
Фид Sheets API v3 позволяет приложению получать список всех электронных таблиц, доступных авторизованному пользователю. Конечная точка фида электронной таблицы:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API
Sheets API v4 не поддерживает эту конкретную операцию. Мы рекомендуем перенести ваше приложение, чтобы использовать область диска.файл в сочетании с инструментом выбора Google для выбора электронной таблицы.
В тех случаях, когда требуются электронные таблицы со списками, их можно реплицировать с помощью метода Drive API Files.list , используя запрос mimeType :
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'Использование метода files.list API Drive для вывода списка всех электронных таблиц пользователя требует ограниченной области действия.
Получить метаданные листа
Sheets API v3 предоставляет канал для доступа к метаданным листа, содержащимся в данной электронной таблице (доступ к данным строк и ячеек осуществляется через отдельный канал). Метаданные включают в себя такую информацию, как заголовки листов и информацию о размере.
Метод Spreadsheets.get API Sheets 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>
v4 API
Метод Spreadsheets.get можно использовать для получения свойств листа и других метаданных — гораздо больше, чем то, что доступно с помощью Sheets 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
Sheets 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>
v4 API
Вы можете добавить новые листы, выполнив запрос AddSheet в методе Spreadsheets.batchUpdate . В теле запроса вы можете указать свойства нового листа; все свойства являются необязательными. Указание названия, которое используется для существующего листа, является ошибкой.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Изменение названия и размера листа
Sheets API v3 позволяет обновлять заголовки и размеры листов; Sheets 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>
v4 API
Чтобы обновить размер, заголовок и другие свойства листа, выполните запрос 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
v4 API
Чтобы удалить лист, выполните запрос DeleteSheet в методе Spreadsheets.batchUpdate . Тело запроса POST должно содержать только sheetId листа, который нужно удалить. Например:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Чтобы получить sheetId отдельного листа, используйте метод электронной таблицы Spreadsheets.get .
Получить данные строки
Подача строк списка — это один из двух методов, которые Sheets API v3 предоставляет для доступа к данным в ячейках электронной таблицы (второй — это подача ячеек ). Подача строк предназначена для поддержки общих операций с электронными таблицами (чтение построчно, добавление строк, сортировка), но содержит определенные допущения, которые делают ее непригодной для некоторых задач. В частности, канал списка предполагает, что пустые строки являются завершением канала и что в первой строке листа присутствуют обязательные заголовки.
Напротив, Sheets API v4 не использует методы доступа, специфичные для строк. Вместо этого доступ к данным ячеек листа осуществляется путем ссылки на определенные требуемые диапазоны с использованием нотации 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>
По умолчанию строки, возвращаемые в фиде списка, возвращаются в порядке строк. Sheets 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:lastnameSheets API v3 также позволяет фильтровать определенные строки с помощью структурированного запроса (на который ссылаются заголовки столбцов):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 API
С помощью Sheets API v4 строки можно получать по диапазону с помощью методов 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"]]
}Завершающие пустые ячейки не включаются в ответ при получении целых строк, столбцов или листов.
Sheets API v4 не имеет эквивалентов для параметров запроса порядка строк, предоставляемых Sheets API v3. Обратный порядок тривиален; просто обработайте массив возвращаемых values в обратном порядке. Порядок по столбцу не поддерживается для чтения, но можно отсортировать данные на листе (с помощью запроса SortRange ), а затем прочитать их.
Sheets API v4 в настоящее время не имеет прямого эквивалента для структурированных запросов Sheets 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>
Новые строки добавляются в конец указанного листа.
v4 API
С помощью Sheets API v4 вы можете добавлять строки с помощью метода Spreadsheets.values.append . В следующем примере новая строка данных записывается под последней таблицей в «Лист1» электронной таблицы.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Кроме того, Sheets API v4 также позволяет добавлять ячейки с определенными свойствами и форматированием с помощью запросов AppendCells в файле externalsheets.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>
v4 API
С помощью Sheets 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 ; этот метод более эффективно использовать, если вы выполняете обновление нескольких строк или ячеек.
Кроме того, Sheets 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. (В этом случае вам не нужно извлекать строку перед ее удалением.)
v4 API
Удаление строк с помощью Sheets API v4 обрабатывается вызовом метода Spreadsheet.batchUpdate с использованием запроса DeleteDimension . Этот запрос также можно использовать для удаления столбцов, а разработчики могут выбрать удаление только части строки или столбца. Например, следующее удаляет 6-ю строку листа с заданным идентификатором (индексы строк отсчитываются от нуля, включая 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 .
Получить данные ячейки
Sheets API v3 предоставляет канал ячеек для базового доступа ко всем данным, хранящимся в электронной таблице. Для доступа на чтение канал ячеек может предоставлять все содержимое листа или диапазон ячеек листа, определенный набором параметров запроса, но только в виде одного блока — непересекающиеся диапазоны необходимо получать отдельно с помощью дополнительных запросов GET .
Sheets API v4 может извлекать любой набор данных ячеек из листа (включая несколько непересекающихся диапазонов). Sheets API v3 может возвращать содержимое ячеек только в виде входных значений (как если бы пользователь вводил их с клавиатуры) и/или выходных данных формулы (если числовое); Sheets 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=4 Sheets API v3 возвращает 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>
v4 API
Получите данные ячейки, вызвав метод 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 .
Редактировать ячейку
Sheets API v3 позволяет редактировать содержимое ячейки, введя команду PUT в фид ячеек с измененной записью ячейки в качестве тела запроса.
API Sheets 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>
v4 API
Редактирование отдельных ячеек в Sheets 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 предоставляют средства для внесения изменений в содержимое нескольких ячеек с помощью одного (пакетного) запроса. Ячейки, на которые ссылается пакетный запрос, не обязательно должны находиться в непрерывном диапазоне.
В случае сбоя одного или нескольких изменений ячеек в пакете Sheets API v3 позволяет добиться успеха другим. Однако Sheets 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 , содержащий полный путь к идентификатору ячейки. Все эти поля обязательны для каждой записи.
v4 API
Sheets 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 возвращает ошибку.