Содержание
Введение
Этот документ предназначен для разработчиков, которые хотят писать приложения, которые могут взаимодействовать с API книг. Миссия Google Книг — оцифровать книжный контент со всего мира и сделать его более доступным для поиска в Интернете. API Книг — это способ поиска и доступа к этому контенту, а также создания и просмотра персонализации этого контента.
Если вы не знакомы с концепциями Google Книг, вам следует прочитать Начало работы , прежде чем приступать к написанию кода.
Авторизация запросов и идентификация вашего приложения
Каждый запрос, отправляемый вашим приложением в API Книг, должен идентифицировать ваше приложение в Google. Есть два способа идентифицировать ваше приложение: с помощью токена OAuth 2.0 (который также авторизует запрос) и/или с помощью ключа API приложения. Вот как определить, какой из этих вариантов использовать:
- Если запрос требует авторизации (например, запрос личных данных человека), то приложение должно предоставить токен OAuth 2.0 вместе с запросом. Приложение также может предоставить ключ API, но это не обязательно.
- Если запрос не требует авторизации (например, запрос общедоступных данных), то приложение должно предоставить либо ключ API, либо токен OAuth 2.0, либо и то, и другое — в зависимости от того, какой вариант вам наиболее удобен.
О протоколах авторизации
Ваше приложение должно использовать OAuth 2.0 для авторизации запросов. Никакие другие протоколы авторизации не поддерживаются. Если ваше приложение использует Sign In With Google , некоторые аспекты авторизации выполняются за вас.
Авторизация запросов с помощью OAuth 2.0
Запросы к API книг для закрытых пользовательских данных должны быть авторизованы пользователем, прошедшим проверку подлинности.
Детали процесса авторизации или «потока» для OAuth 2.0 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применяется ко всем типам приложений:
- Когда вы создаете свое приложение, вы регистрируете его с помощью Google API Console . Затем Google предоставляет информацию, которая понадобится вам позже, например идентификатор клиента и секрет клиента.
- Активируйте API книг в консоли Google API. (Если API не указан в консоли API, пропустите этот шаг.)
- Когда вашему приложению требуется доступ к пользовательским данным, оно запрашивает у Google определенную область доступа.
- Google отображает пользователю экран согласия , предлагая ему разрешить вашему приложению запрашивать некоторые из его данных.
- Если пользователь одобряет, Google предоставляет вашему приложению краткосрочный токен доступа .
- Ваше приложение запрашивает данные пользователя, прикрепляя к запросу токен доступа.
- Если Google определяет, что ваш запрос и токен действительны, он возвращает запрошенные данные.
Некоторые потоки включают дополнительные шаги, например использование маркеров обновления для получения новых маркеров доступа. Подробную информацию о потоках для различных типов приложений см. в документации Google по OAuth 2.0 .
Вот информация об области OAuth 2.0 для Books API:
https://www.googleapis.com/auth/books
Чтобы запросить доступ с помощью OAuth 2.0, вашему приложению требуется информация о области, а также информация, которую Google предоставляет при регистрации вашего приложения (например, идентификатор клиента и секрет клиента).
Совет . Клиентские библиотеки API Google могут выполнить часть процесса авторизации за вас. Они доступны для различных языков программирования; проверьте страницу с библиотеками и примерами для более подробной информации.
Получение и использование ключа API
Запросы к API Книг для общедоступных данных должны сопровождаться идентификатором, который может быть ключом API или токеном доступа .
Чтобы получить ключ API:
- Откройте страницу учетных данных в консоли API.
- Этот API поддерживает два типа учетных данных. Создайте любые учетные данные, подходящие для вашего проекта:
OAuth 2.0: всякий раз, когда ваше приложение запрашивает личные данные пользователя, оно должно отправлять токен OAuth 2.0 вместе с запросом. Ваше приложение сначала отправляет идентификатор клиента и, возможно, секрет клиента для получения токена. Вы можете создавать учетные данные OAuth 2.0 для веб-приложений, учетных записей служб или установленных приложений.
Дополнительные сведения см. в документации по OAuth 2.0 .
Ключи API: запрос, не предоставляющий токен OAuth 2.0, должен отправлять ключ API. Ключ идентифицирует ваш проект и предоставляет доступ к API, квоту и отчеты.
API поддерживает несколько типов ограничений на ключи API. Если нужный вам ключ API еще не существует, создайте ключ API в консоли, щелкнув Создать учетные данные > Ключ API . Вы можете ограничить ключ перед его использованием в рабочей среде, щелкнув Ограничить ключ и выбрав одно из ограничений .
Чтобы обеспечить безопасность ключей API, следуйте рекомендациям по безопасному использованию ключей API .
Получив ключ API, ваше приложение может добавлять параметр запроса key= yourAPIKey
ко всем URL-адресам запроса.
Ключ API безопасен для встраивания в URL-адреса; ему не нужна кодировка.
Идентификаторы Google Книг
Вам необходимо указать поля ID с определенными вызовами методов API. В Google Книгах используются идентификаторы трех типов:
- Идентификаторы томов . Уникальные строки, присвоенные каждому тому, о котором знает Google Книги. Пример идентификатора тома:
_LettPDhwR0C
. Вы можете использовать API для получения идентификатора тома, выполнив запрос, который возвращает ресурс тома; вы можете найти идентификатор тома в его полеid
. - Идентификаторы книжных полок — числовые значения, присвоенные книжной полке в пользовательской библиотеке. Google предоставляет несколько предопределенных полок для каждого пользователя со следующими идентификаторами:
- Избранное: 0
- Куплено: 1
- Читать: 2
- Читаю сейчас: 3
- Прочитано: 4
- Отзывов: 5
- Недавно просмотрено: 6
- Мои электронные книги: 7
- Книги для вас: 8 Если у нас нет рекомендаций для пользователя, этой полки не существует.
id
. - Идентификаторы пользователей — уникальные числовые значения, присвоенные каждому пользователю. Эти значения не обязательно совпадают с идентификаторами, используемыми в других службах Google. В настоящее время единственный способ получить идентификатор пользователя — извлечь его из selfLink в ресурсе Bookshelf, полученном с помощью аутентифицированного запроса. Пользователи также могут получить собственный идентификатор пользователя на сайте Книги. Пользователь не может получить идентификатор пользователя для другого пользователя через API или сайт Книг; другой пользователь должен будет явно поделиться этой информацией, например, по электронной почте.
Идентификаторы на сайте Google Книг
Идентификаторы, которые вы используете с API Книг, — это те же идентификаторы, которые используются на сайте Google Книг .
- Идентификатор тома
При просмотре определенного тома на сайте вы можете найти идентификатор тома в параметре
id
URL. Вот пример:https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- Идентификатор книжной полки
При просмотре конкретной книжной полки на сайте вы можете найти идентификатор книжной полки в параметре
as_coll
URL. Вот пример:https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
- ID пользователя
При просмотре вашей библиотеки на сайте вы можете найти идентификатор пользователя в параметре
uid
URL. Вот пример:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Настройка местоположения пользователя
Google Книги соблюдают авторские права, контракты и другие юридические ограничения, связанные с местонахождением конечного пользователя. В результате некоторые пользователи могут не иметь доступа к книгам из определенных стран. Например, некоторые книги доступны для предварительного просмотра только в США; мы опускаем такие ссылки для предварительного просмотра для пользователей в других странах. Поэтому результаты API ограничены на основе IP-адреса вашего сервера или клиентского приложения.
Работа с объемами
Выполнение поиска
Вы можете выполнить поиск томов, отправив HTTP- GET
на следующий URI:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Этот запрос имеет один обязательный параметр:
-
q
— поиск томов, содержащих эту текстовую строку. Существуют специальные ключевые слова, которые вы можете указать в условиях поиска для поиска в определенных полях, например:-
intitle:
возвращает результаты, в которых текст, следующий за этим ключевым словом, находится в заголовке. -
inauthor:
возвращает результаты, в которых текст, следующий за этим ключевым словом, найден у автора. -
inpublisher:
возвращает результаты, в которых текст, следующий за этим ключевым словом, найден в издателе. -
subject:
возвращает результаты, в которых текст, следующий за этим ключевым словом, указан в списке категорий тома. -
isbn:
возвращает результаты, в которых текст, следующий за этим ключевым словом, является номером ISBN. -
lccn:
возвращает результаты, в которых текст, следующий за этим ключевым словом, является контрольным номером Библиотеки Конгресса. -
oclc:
возвращает результаты, в которых текст, следующий за этим ключевым словом, является номером центра компьютерной онлайн-библиотеки.
-
Запрос
Вот пример поиска «Цветов для Элджернона» Дэниела Киза:
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Примечание. Выполнение поиска не требует аутентификации, поэтому вам не нужно предоставлять HTTP-заголовок Authorization
вместе с запросом GET
. Однако, если вызов выполняется с аутентификацией, каждый том будет содержать информацию о пользователе, такую как статус покупки.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
, и результаты тома:
200 OK { "kind": "books#volumes", "items": [ { "kind": "books#volume", "id": "_ojXNuzgHRcC", "etag": "OTD2tB19qn4", "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC", "volumeInfo": { "title": "Flowers", "authors": [ "Vijaya Khisty Bodach" ], ... }, { "kind": "books#volume", "id": "RJxWIQOvoZUC", "etag": "NsxMT6kCCVs", "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC", "volumeInfo": { "title": "Flowers", "authors": [ "Gail Saunders-Smith" ], ... }, { "kind": "books#volume", "id": "zaRoX10_UsMC", "etag": "pm1sLMgKfMA", "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC", "volumeInfo": { "title": "Flowers", "authors": [ "Paul McEvoy" ], ... }, "totalItems": 3 }
Необязательные параметры запроса
В дополнение к стандартным параметрам запроса вы можете использовать следующие параметры запроса при выполнении поиска томов.
Формат загрузки
Вы используете параметр download
, чтобы ограничить возвращаемые результаты томами, которые имеют доступный формат загрузки epub
, установив параметр
к значению epub
.
В следующем примере выполняется поиск книг с доступной загрузкой epub:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Фильтрация
Вы можете использовать параметр filter
для дальнейшего ограничения возвращаемых результатов, установив для него одно из следующих значений:
-
partial
— возвращает результаты, в которых хотя бы часть текста доступна для предварительного просмотра. -
full
— возвращает только те результаты, в которых виден весь текст. -
free-ebooks
— возвращает только бесплатные электронные книги Google. -
paid-ebooks
— возвращаются только результаты, которые являются электронными книгами Google с указанием цены. -
ebooks
— возвращаются только результаты, которые являются электронными книгами Google, платными или бесплатными. Примерами неэлектронных книг может быть контент издателя, доступный в ограниченном предварительном просмотре и не предназначенный для продажи, или журналы.
В следующем примере результаты поиска ограничиваются теми, которые доступны в виде бесплатных электронных книг:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Пагинация
Вы можете разбить список томов на страницы, указав два значения в параметрах запроса:
-
startIndex
— позиция в коллекции, с которой следует начать. Индекс первого элемента равен 0. -
maxResults
— максимальное количество возвращаемых результатов. Значение по умолчанию — 10, а максимально допустимое значение — 40.
Тип печати
Вы можете использовать параметр printType
, чтобы ограничить возвращаемые результаты определенным типом печати или публикации, установив для него одно из следующих значений:
-
all
— не ограничивается типом печати (по умолчанию). -
books
— возвращает только результаты, являющиеся книгами. -
magazines
— возвращает результаты, которые являются журналами.
В следующем примере результаты поиска ограничиваются журналами:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Проекция
Вы можете использовать параметр projection
с одним из следующих значений, чтобы указать предопределенный набор возвращаемых полей объема:
-
full
— возвращает все поля Volume. -
lite
— возвращает только определенные поля. См. описания полей, отмеченные двойными звездочками, в справке по объему, чтобы узнать, какие поля включены.
В следующем примере возвращаются результаты поиска с информацией об ограниченном объеме:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Сортировка
По умолчанию запрос на объемный поиск возвращает результаты maxResults
, где maxResults
— это параметр, используемый при разбивке на страницы (выше), упорядоченный по релевантности поисковым запросам.
Вы можете изменить порядок, установив для параметра orderBy
одно из следующих значений:
-
relevance
— возвращает результаты в порядке релевантности условий поиска (по умолчанию). -
newest
— возвращает результаты в порядке от самых последних до наименее недавно опубликованных.
В следующем примере результаты перечислены по дате публикации, от новых к старым:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Получение определенного тома
Вы можете получить информацию для определенного тома, отправив HTTP- GET
на URI ресурса тома:
https://www.googleapis.com/books/v1/volumes/volumeId
Замените параметр пути volumeId
идентификатором тома, который необходимо получить. Дополнительную информацию об идентификаторах томов см. в разделе « Идентификаторы Google Книг ».
Запрос
Вот пример запроса GET
, который получает один том:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Примечание. Для получения информации о томе не требуется проверка подлинности, поэтому вам не нужно предоставлять HTTP-заголовок Authorization
вместе с запросом GET
. Однако, если вызов выполняется с аутентификацией, объем будет включать информацию о пользователе, такую как статус покупки.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и запрошенным ресурсом тома:
200 OK { "kind": "books#volume", "id": "zyTCAlFPjgYC", "etag": "f0zKg75Mx/I", "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC", "volumeInfo": { "title": "The Google story", "authors": [ "David A. Vise", "Mark Malseed" ], "publisher": "Random House Digital, Inc.", "publishedDate": "2005-11-15", "description": "\"Here is the story behind one of the most remarkable Internet successes of our time. Based on scrupulous research and extraordinary access to Google, ...", "industryIdentifiers": [ { "type": "ISBN_10", "identifier": "055380457X" }, { "type": "ISBN_13", "identifier": "9780553804577" } ], "pageCount": 207, "dimensions": { "height": "24.00 cm", "width": "16.03 cm", "thickness": "2.74 cm" }, "printType": "BOOK", "mainCategory": "Business & Economics / Entrepreneurship", "categories": [ "Browsers (Computer programs)", ... ], "averageRating": 3.5, "ratingsCount": 136, "contentVersion": "1.1.0.0.preview.2", "imageLinks": { "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api", "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api", "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api", "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api", "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api", "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api" }, "language": "en", "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api", "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC" }, "saleInfo": { "country": "US", "saleability": "FOR_SALE", "isEbook": true, "listPrice": { "amount": 11.99, "currencyCode": "USD" }, "retailPrice": { "amount": 11.99, "currencyCode": "USD" }, "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api" }, "accessInfo": { "country": "US", "viewability": "PARTIAL", "embeddable": true, "publicDomain": false, "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY", "epub": { "isAvailable": true, "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api" }, "pdf": { "isAvailable": false }, "accessViewStatus": "SAMPLE" } }
Доступ к информации
Раздел accessInfo
представляет особый интерес для определения того, какие функции доступны для электронной книги. epub
— это электронная книга в текстовом формате, раздел epub
будет иметь свойство isAvailable
, указывающее, доступен ли этот тип электронной книги. У него будет ссылка для загрузки, если есть образец книги или если пользователь может прочитать книгу либо из-за ее покупки, либо из-за того, что она является общественным достоянием в местоположении пользователя. pdf
-файл для книг Google представляет собой версию электронной книги в виде отсканированных страниц с аналогичными сведениями, такими как информация о ее доступности и ссылка для скачивания. Google рекомендует файлы epub
для электронных книг и смартфонов, так как отсканированные страницы могут быть трудночитаемыми на этих устройствах. Если раздел accessInfo
отсутствует, том недоступен в виде электронной книги Google.
Необязательные параметры запроса
В дополнение к стандартным параметрам запроса при извлечении определенного тома можно использовать следующий параметр запроса.
Проекция
Вы можете использовать параметр projection
с одним из следующих значений, чтобы указать предопределенный набор возвращаемых полей объема:
-
full
— возвращает все поля Volume. -
lite
— возвращает только определенные поля. См. описания полей, отмеченные двойными звездочками, в справке по объему, чтобы узнать, какие поля включены.
В следующем примере возвращается ограниченная информация о томе для одного тома:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Работа с книжными полками.
Получение списка общедоступных книжных полок пользователя
Вы можете получить список общедоступных книжных полок пользователя, отправив запрос HTTP GET
на URI в следующем формате:
https://www.googleapis.com/books/v1/users/userId/bookshelves
Замените параметр пути userId идентификатором пользователя, чьи книжные полки вы хотите получить. Дополнительную информацию об идентификаторах пользователей см. в разделе « Идентификаторы Google Книг ».
Запрос
Вот пример:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Поскольку пользователю не нужно проходить аутентификацию для получения информации об общедоступных книжных полках, вам не нужно предоставлять HTTP-заголовок Authorization
с запросом GET
.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и списком книжных полок:
200 OK { "kind": "books#bookshelves", "items": [ { ... }, { "kind": "books#bookshelf", "id": 3, "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3", "title": "Reading now", "description": "", "access": "PUBLIC", "updated": "2011-02-02T20:34:20.146Z", "created": "2011-02-02T20:34:20.146Z", "volumeCount": 2, "volumesLastUpdated": "2011-02-02T20:34:20.110Z" }, ... ] }
Необязательные параметры запроса
Вы можете использовать стандартные параметры запроса при получении списка общедоступных книжных полок пользователя.
Получение конкретной общедоступной книжной полки
Вы можете получить конкретную общедоступную книжную полку, отправив HTTP- GET
на URI в следующем формате:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Замените параметры userId и пути к полке идентификаторами, указывающими пользователя и книжную полку, которую вы хотите получить. Дополнительные сведения см. в разделе « Идентификаторы Google Книг ».
Запрос
Вот пример:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Поскольку пользователю не нужно проходить аутентификацию для получения информации об общедоступных книжных полках, вам не нужно предоставлять HTTP-заголовок Authorization
с запросом GET
.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и ресурсом книжной полки:
200 OK { "kind": "books#bookshelf", "id": 3, "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3", "title": "Reading now", "description": "", "access": "PUBLIC", "updated": "2011-02-02T20:34:20.146Z", "created": "2011-02-02T20:34:20.146Z", "volumeCount": 2, "volumesLastUpdated": "2011-02-02T20:34:20.110Z" }
Необязательные параметры запроса
Вы можете использовать стандартные параметры запроса при получении конкретной общедоступной книжной полки.
Получение списка томов на общедоступной книжной полке
Вы можете получить список томов на общедоступной книжной полке пользователя, отправив HTTP- GET
на URI в следующем формате:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Запрос
Вот пример:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Замените параметры userId и пути к полке идентификаторами, указывающими пользователя и книжную полку, которую вы хотите получить. Дополнительные сведения см. в разделе « Идентификаторы Google Книг ».
Поскольку пользователю не нужно проходить аутентификацию для получения информации об общедоступных книжных полках, вам не нужно предоставлять HTTP-заголовок Authorization
с запросом GET
.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и списком книжных полок пользователя:
200 OK { "kind": "books#volumes", "items": [ { "kind": "books#volume", "id": "AZ5J6B1-4BoC", "etag": "kIzQA7IUObk", "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC", "volumeInfo": { "title": "The Girl Who Kicked the Hornet's Nest", "authors": [ "Stieg Larsson" ], "publisher": "Knopf", "publishedDate": "2010-05-25", ... }, { "kind": "books#volume", "id": "UvK1Slvkz3MC", "etag": "otKmdbRgdFQ", "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC", "volumeInfo": { "title": "The Girl who Played with Fire", "authors": [ "Stieg Larsson" ], "publisher": "Knopf", "publishedDate": "2009-07-28", ... }, { "kind": "books#volume", "id": "OBM3AAAAIAAJ", "etag": "xb47kTr8HsQ", "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ", "volumeInfo": { "title": "The Sign of Four", "authors": [ "Sir Arthur Conan Doyle" ], "publishedDate": "1890", ... } ], "totalItems": 3 }
Необязательные параметры запроса
В дополнение к стандартным параметрам запроса вы можете использовать следующий параметр запроса при получении списка томов на общедоступной книжной полке.
Пагинация
Вы можете разбить список томов на страницы, указав два значения в параметрах запроса:
-
startIndex
— позиция в коллекции, с которой следует начать. Индекс первого элемента равен 0. -
maxResults
— максимальное количество возвращаемых результатов. Значение по умолчанию — 10, а максимально допустимое значение — 40.
Работа с книжными полками в «Моей библиотеке»
Все запросы «Моя библиотека» относятся к данным аутентифицированного пользователя.
Получение списка моих книжных полок
Вы можете получить список всех книжных полок аутентифицированного пользователя, отправив HTTP- GET
на URI в следующем формате:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Запрос
Вот пример:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Примечание. Чтобы получить список книжных полок «Моя библиотека», пользователь должен пройти аутентификацию. Таким образом, вы должны предоставить HTTP-заголовок Authorization
с запросом GET
.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и списком всех книжных полок для текущего аутентифицированного пользователя:
200 OK { "kind": "books#bookshelves", "items": [ { "kind": "books#bookshelf", "id": 0, "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0", "title": "Favorites", "access": "PRIVATE", "updated": "2011-04-22T04:03:15.416Z", "created": "2011-04-22T04:03:15.416Z", "volumeCount": 0, "volumesLastUpdated": "2011-04-22T04:03:17.000Z" }, { "kind": "books#bookshelf", "id": 3, "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3", "title": "Reading now", "access": "PUBLIC", "updated": "2010-11-11T19:44:22.377Z", "created": "2010-11-11T19:44:22.377Z", "volumeCount": 1, "volumesLastUpdated": "2010-11-11T19:44:22.341Z" } ] }
Необязательные параметры запроса
Вы можете использовать стандартные параметры запроса при получении списка книжных полок аутентифицированного пользователя.
Получение списка томов на моей книжной полке
Вы можете получить список томов на книжной полке аутентифицированного пользователя, отправив запрос HTTP GET
на URI в следующем формате:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Замените параметр пути к полке идентификатором книжной полки. Дополнительную информацию об идентификаторах книжных полок см. в разделе « Идентификаторы Google Книг ».
Запрос
Вот пример:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Примечание. Пользователь должен пройти аутентификацию, чтобы получить список томов «Моя библиотека». Таким образом, вы должны предоставить HTTP-заголовок Authorization
с запросом GET
.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и списком томов книжных полок:
200 OK { "kind": "books#volumes", "items": [ { "kind": "books#volume", "id": "AZ5J6B1-4BoC", "etag": "kIzQA7IUObk", "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC", "volumeInfo": { "title": "The Girl Who Kicked the Hornet's Nest", "authors": [ "Stieg Larsson" ], "publisher": "Knopf", "publishedDate": "2010-05-25", ... }, { "kind": "books#volume", "id": "UvK1Slvkz3MC", "etag": "otKmdbRgdFQ", "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC", "volumeInfo": { "title": "The Girl who Played with Fire", "authors": [ "Stieg Larsson" ], "publisher": "Knopf", "publishedDate": "2009-07-28", ... }, { "kind": "books#volume", "id": "OBM3AAAAIAAJ", "etag": "xb47kTr8HsQ", "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ", "volumeInfo": { "title": "The Sign of Four", "authors": [ "Sir Arthur Conan Doyle" ], "publishedDate": "1890", ... } ], "totalItems": 3 }
Необязательные параметры запроса
В дополнение к стандартным параметрам запроса вы можете использовать следующий параметр запроса при получении списка томов на одной из книжных полок аутентифицированного пользователя.
Пагинация
Вы можете разбить список томов на страницы, указав два значения в параметрах запроса:
-
startIndex
— позиция в коллекции, с которой следует начать. Индекс первого элемента равен 0. -
maxResults
— максимальное количество возвращаемых результатов. По умолчанию 10.
Добавление тома на мою книжную полку
Чтобы добавить том на книжную полку аутентифицированного пользователя, отправьте HTTP-запрос POST
на URI в следующем формате:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Замените параметр пути к полке идентификатором книжной полки. Дополнительную информацию об идентификаторах книжных полок см. в разделе « Идентификаторы Google Книг ».
Запрос имеет один обязательный параметр запроса:
-
volumeId
— идентификатор тома. Дополнительную информацию об идентификаторах томов см. в разделе « Идентификаторы Google Книг ».
Запрос
Вот пример добавления «Цветы для Элджернона» на книжную полку «Избранное»:
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Примечание. Пользователь должен пройти аутентификацию, чтобы вносить изменения в книжную полку, поэтому вы должны предоставить HTTP-заголовок Authorization
вместе с запросом POST
. Однако для этого POST
не требуются никакие данные.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 204 No Content
.
Необязательные параметры запроса
Вы можете использовать стандартные параметры запроса при добавлении тома на одну из книжных полок аутентифицированного пользователя.
Удаление тома с моей книжной полки
Чтобы удалить том с книжной полки аутентифицированного пользователя, отправьте HTTP POST
на URI в следующем формате:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Замените параметр пути к полке идентификатором книжной полки. Дополнительную информацию об идентификаторах книжных полок см. в разделе « Идентификаторы Google Книг ».
Запрос имеет один обязательный параметр запроса:
-
volumeId
— идентификатор тома. Видеть раздел « Идентификаторы Google Книг » для получения дополнительной информации об идентификаторах томов.
Запрос
Вот пример удаления «Цветы для Элджернона» с книжной полки «Избранное»:
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Примечание. Пользователь должен пройти аутентификацию, чтобы вносить изменения в книжную полку, поэтому вы должны предоставить HTTP-заголовок Authorization
вместе с запросом POST
. Однако для этого POST
не требуются никакие данные.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния 204 No Content
.
Необязательные параметры запроса
Вы можете использовать стандартные параметры запроса при удалении тома с одной из книжных полок аутентифицированного пользователя.
Очистка всех томов с моей книжной полки
Чтобы удалить все тома с книжной полки аутентифицированного пользователя, отправьте HTTP POST
на URI в следующем формате:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Замените параметр пути к полке идентификатором книжной полки. Дополнительную информацию об идентификаторах книжных полок см. в разделе « Идентификаторы Google Книг ».
Запрос
Вот пример очистки книжной полки «Избранное»:
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Примечание. Пользователь должен пройти аутентификацию, чтобы вносить изменения в книжную полку, поэтому вы должны предоставить HTTP-заголовок Authorization
вместе с запросом POST
. Однако для этого POST
не требуются никакие данные.
Ответ
Если запрос выполнен успешно, сервер отвечает кодом состояния 204 No Content
.
Необязательные параметры запроса
Вы можете использовать стандартные параметры запроса при очистке всех томов с одной из книжных полок аутентифицированного пользователя.
Справочник по параметрам запроса
В этом разделе кратко описаны параметры запроса, которые можно использовать с API книг. Все значения параметров должны быть закодированы в URL.
Стандартные параметры запроса
Параметры запроса, применимые ко всем операциям API книг, задокументированы в разделе Системные параметры .
Параметры запроса API
Параметры запроса, применимые только к определенным операциям в Books API, приведены в следующей таблице.
Параметр | Значение | Заметки | Применимость |
---|---|---|---|
download | Ограничение объемов по доступности загрузки. |
| |
filter | Фильтруйте результаты поиска по типу тома и доступности. |
| |
langRestrict | Ограничивает возвращаемые тома теми, которые помечены указанным языком. |
| |
maxResults | Максимальное количество элементов, возвращаемых этим запросом. |
| orderBy | Порядок результатов поиска по объему. |
|
printType | Ограничьтесь книгами или журналами. |
| |
projection | Ограничьте объем информации, возвращаемой подмножеством полей. |
| |
q | Полнотекстовая строка запроса. |
| |
startIndex | Позиция в коллекции, с которой начинается список результатов. |
| |
volumeId | Идентифицирует том, связанный с запросом. |
|