Если у вас есть приложения на основе 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 Drive API для вывода списка всех электронных таблиц пользователя требует ограниченной области действия.
Получить метаданные листа
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 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>
По умолчанию строки, возвращаемые в фиде списка, возвращаются в порядке строк. 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:lastname
Sheets API v3 также позволяет фильтровать определенные строки с помощью структурированного запроса (на который ссылаются заголовки столбцов):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?sq=age>25%20and%20height<175
v4 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 версии 4, напротив, предоставляет методы 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 возвращает ошибку.
Если у вас есть приложения на основе 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
В новом API Sheets 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 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>
По умолчанию строки, возвращаемые в фиде списка, возвращаются в порядке строк. 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:lastname
Sheets API v3 также позволяет фильтровать определенные строки с помощью структурированного запроса (на который ссылаются заголовки столбцов):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?sq=age>25%20and%20height<175
v4 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 в проведении интересующего рабочего листа.
Чтобы добавить строку данных, отправьте запрос POST
на URL -адрес POST, используя соответствующий заголовок авторизации. Например:
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
С листами API V4 вы можете добавлять строки, используя метод электронных таблиц . Values.Append. В следующем примере записывается новая строка данных ниже последней таблицы в «Листе 1» электронную таблицу.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Кроме того, Sheets API V4 также позволяет добавлять ячейки с определенными свойствами и форматированием, используя запросы AppendCells в таблицах .
Отредактируйте строку с новыми данными
Оба API позволяют обновлять данные строки с помощью новых значений.
V3 API
Чтобы редактировать строку данных, проверьте подачу списка , чтобы найти запись для строки, которую вы хотите обновить. Обновите содержимое этой записи по мере необходимости. Убедитесь, что значение идентификатора в записи, которую вы используете, точно соответствует идентификатору существующей записи.
После того, как запись будет обновлена, отправьте запрос 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
С листами API V4 вы можете отредактировать ряд, используя A1 обозначения строки, которую вы хотите отредактировать и выпустить электронные таблицы . Указанный диапазон необходим только в первой ячейке в ряду; API позволяет ячейкам обновлять на основе значений, предоставленных с запросом. Если вместо этого вы указываете многоклеточный диапазон, предоставляемые вами значения должны соответствовать в этом диапазоне; Если не API возвращает ошибку.
Следующий пример запроса и корпуса запроса добавляет данные в четвертую строку «Лист1»:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Вы также можете обновить данные строк из метода электронной таблицы.values.batchupdate ; Более эффективно использовать этот метод, если вы делаете несколько обновлений строк или ячейки.
Кроме того, Sheets API V4 также позволяет редактировать свойства ячейки и форматирование ячеек, используя запросы UpdateCells или RepeatCell в таблицах .batchUpdate .
Удалить ряд
Оба API поддерживают удаление рядов. Удаленная строка удаляется из электронной таблицы, а ряды под ней выдвигаются вверх.
V3 API
Чтобы удалить строку, сначала верните строку, чтобы удалить из подачи списка , затем отправьте запрос DELETE
на URL edit
, указанный в записи строки. Это тот же URL, который используется для обновления строки.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Если вы хотите убедиться, что вы не удаляете строку, которая была изменена другим клиентом с момента его извлечения, включите заголовок HTTP, если содержит исходное значение ETAG. Вы можете определить исходное значение ETAG строки, изучив атрибут GD: ETAG от ETAG.
Если вы хотите удалить строку независимо от того, обновил ли кто-то его, так как вы его взяли, используйте, если матч: * и не включайте ETAG. (В этом случае вам не нужно получать строку, прежде чем удалить ее.)
V4 API
Удаление рядов с помощью листов API V4 обрабатывается с помощью вызова метода Spreadsheet.batchupdate с использованием запроса DeletEdImension . Этот запрос также может использоваться для удаления столбцов, а также разработчиков и выбрать только часть строки или столбца. Например, следующее удаляет 6-й ряд листа с данным идентификатором (индексы строк основаны на нулевом уровне, с инклюзивным и исключительным Endidex):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteDimension": { "range": { "sheetId": sheetId, "dimension": "ROWS", "startIndex": 5, "endIndex": 6 } } } ], }
sheetId может быть извлечен с использованием метода электронной таблицы .
Получить данные ячейки
Sheets API V3 предоставляет клеточную подачу для базового доступа ко всем данным, хранящимся в электронной таблице. Для доступа к чтению корм для ячейки может обеспечить весь содержимое листа или диапазон ячеек листа, определенные набором параметров запроса, но только в качестве одного блока - диапазоны диссуата должны быть получены отдельно, используя дополнительные запросы на GET
.
Sheets API V4 может извлечь любой набор данных ячеек с листа (включая множество диапазонов непересеченности). Sheets API V3 может возвращать только содержимое ячейки в качестве входных значений (как будет введено пользователем на клавиатуре) и/или выходов формулы (если числовые); Sheets API V4 дает полный доступ к значениям, формулам, форматированию, гиперссылкам, проверке данных и другим свойствам.
V3 API
Чтобы определить URL-адрес полета на основе ячейки для данного рабочего листа, изучите кормление рабочего листа и найдите URL-файл Cell Feed в проведении интересующего рабочего листа.
Чтобы получить подачу на основе ячейки, отправьте запрос 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
Получить данные ячейки, вызывая электронные таблицы . Например, следующее возвращает ячейки в столбце 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"]] }] }
Более эффективно использовать таблицу . Если вы хотите получить доступ к свойствам ячеек, таким как форматирование, требуется метод сбора .
Редактировать ячейку
Sheets API V3 позволяет вам редактировать содержание ячейки, выпустив команду PUT
для подачи ячейки с модифицированным вводом ячейки в качестве корпуса запроса.
Sheets API V4, напротив, предоставляет электронные таблицы .
V3 API
Чтобы отредактировать содержание одной ячейки, сначала найдите запись ячейки в кормке ячейки . Запись содержит Edit URL. Обновите запись, чтобы отразить содержимое, которое вы хотите, чтобы ячейка имела, а затем выпустите запрос PUT
на URL Edit с обновленной записью ячейки в качестве корпуса запроса. Например, в следующих обновлениях ячейка 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
Редактирование одноклеточных ячеек в листах API V4 может быть сделано с помощью метода электронных таблиц . Этот метод требует параметра запроса ValueInputOption
, который указывает, обрабатываются ли входные данные так, как если бы введены в пользовательский интерфейс листов ( USER_ENTERED
), или оставлены без остановки и взяты как есть ( RAW
). Например, следующие обновления ячейки D2 с формулой:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}
Если вы делаете несколько исследований ячеек, используйте метод электронных таблиц .
Изменить несколько ячеек с помощью пакетного запроса
Оба API предоставляют средства для внесения изменений в содержание нескольких ячеек с одним (пакетным) запросом. Клетки, упомянутые пакетным запросом, не обязательно должны находиться в непредвиденном диапазоне.
В случае, когда один или несколько редактирования ячейки в пакете не сбои, листы API V3 позволяют другим добиться успеха. Тем не менее, листы API V4 возвращает ошибку, если какое -либо из пакетных обновлений не удалось и не применяет ни одного из них в этом случае.
V3 API
Чтобы редактировать несколько ячеек, сначала забрать клеточный корм для рабочего листа. Запись содержит партийный URL. Отправьте запрос в этот URL -адрес POST
, а также тело запроса, описывающее ячейки, которые вы хотите обновить, и новое содержание ячейки. У корпуса запроса и запроса 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 обеспечивает пакетное редактирование значений ячеек с помощью метода электронных таблиц .
Редактирование нескольких ячеек может быть сделано путем выдачи запроса 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 возвращает ошибку.