Использование API.

Содержание

1. Введение
   1. Аутентификация и авторизация
   2. Идентификаторы Google Книг
   3. Настройка местоположения пользователя
2. Работа с томами
   1. Выполнение поиска
   2. Получение определенного тома
3. Работа с книжными полками.
   1. Получение списка общедоступных книжных полок пользователя
   2. Получение конкретной общедоступной книжной полки
   3. Получение списка томов на общедоступной книжной полке
4. Работа с книжными полками в «Моей библиотеке»
   1. Получение списка моих книжных полок
   2. Получение списка томов на моей книжной полке
   3. Добавляю том на свою книжную полку
   4. Убираю том с книжной полки
   5. Убираю все тома с книжной полки
5. Справочник по параметрам запроса
   1. Стандартные параметры запроса
   2. Параметры запроса, специфичные для API

Введение

Этот документ предназначен для разработчиков, желающих писать приложения, способные взаимодействовать с API книг. Задача Google Книги — оцифровать книжный контент по всему миру и сделать его более доступным для поиска в Интернете. API книг – это способ поиска и доступа к этому контенту, а также создания и просмотра персонализации этого контента.

Если вы не знакомы с концепциями Google Книги, вам следует прочитать «Начало работы» , прежде чем приступать к написанию кода.

Авторизация запросов и идентификация вашего приложения

Каждый запрос, который ваше приложение отправляет в Books API, должен идентифицировать ваше приложение для Google. Существует два способа идентифицировать ваше приложение: с помощью токена OAuth 2.0 (который также авторизует запрос) и/или с помощью ключа API приложения. Вот как определить, какой из этих вариантов использовать:

• Если запрос требует авторизации (например, запрос личных данных человека), приложение должно предоставить вместе с запросом токен OAuth 2.0. Приложение также может предоставить ключ API, но это не обязательно.
• Если запрос не требует авторизации (например, запрос общедоступных данных), то приложение должно предоставить либо ключ API, либо токен OAuth 2.0, либо и то, и другое — любой вариант, который вам наиболее удобен.

О протоколах авторизации

Ваше приложение должно использовать OAuth 2.0 для авторизации запросов. Другие протоколы авторизации не поддерживаются. Если ваше приложение использует «Войти через Google» , некоторые аспекты авторизации выполняются за вас.

Авторизация запросов с помощью OAuth 2.0

Запросы к Books API для получения закрытых пользовательских данных должны быть авторизованы прошедшим проверку подлинности пользователем.

Детали процесса авторизации или «потока» для OAuth 2.0 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применим ко всем типам приложений:

1. Когда вы создаете свое приложение, вы регистрируете его с помощью консоли Google API . Затем Google предоставляет информацию, которая понадобится вам позже, например идентификатор клиента и секрет клиента.
2. Активируйте Books API в консоли Google API. (Если API не указан в консоли API, пропустите этот шаг.)
3. Когда вашему приложению требуется доступ к пользовательским данным, оно запрашивает у Google определенный объем доступа.
4. Google отображает пользователю экран согласия , прося его разрешить вашему приложению запрашивать некоторые его данные.
5. Если пользователь одобряет, Google предоставляет вашему приложению кратковременный токен доступа .
6. Ваше приложение запрашивает пользовательские данные, прикрепляя к запросу токен доступа.
7. Если Google определит, что ваш запрос и токен действительны, он вернет запрошенные данные.

Некоторые потоки включают дополнительные шаги, например использование токенов обновления для получения новых токенов доступа. Подробную информацию о потоках для различных типов приложений см. в документации Google OAuth 2.0 .

Ниже представлена ​​информация об области действия OAuth 2.0 для Books API:

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

Чтобы запросить доступ с помощью OAuth 2.0, вашему приложению необходима информация об области действия, а также информация, которую Google предоставляет при регистрации вашего приложения (например, идентификатор клиента и секрет клиента).

Совет: Клиентские библиотеки API Google могут выполнить за вас часть процесса авторизации. Они доступны для различных языков программирования; проверьте страницу с библиотеками и образцами для получения более подробной информации.

Получение и использование ключа API

Запросы к Books API на получение общедоступных данных должны сопровождаться идентификатором, который может быть ключом API или токеном доступа .

Чтобы получить ключ API:

1. Откройте страницу «Учетные данные» в консоли API.
2. Этот 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 Книг

Вам необходимо указать поля идентификатора для определенных вызовов методов API. В Google Книгах используются идентификаторы трех типов:

• Идентификаторы томов – уникальные строки, присвоенные каждому тому, о котором знает Google Книги. Пример идентификатора тома: _LettPDhwR0C . Вы можете использовать API для получения идентификатора тома, выполнив запрос, который возвращает ресурс тома; вы можете найти идентификатор тома в поле его id .
• Идентификаторы книжных полок — числовые значения, присвоенные книжной полке в библиотеке пользователя. Google предоставляет несколько заранее определенных полок для каждого пользователя со следующими идентификаторами:
  • Избранное: 0
  • Куплено: 1
  • Читать: 2
  • Читаю сейчас: 3
  • Прочитано: 4
  • Просмотрено: 5
  • Недавно просмотрено: 6
  • Мои электронные книги: 7
  • Книги Для Вас: 8 Если у нас нет рекомендаций для пользователя, значит этой полки не существует.
  Пользовательские полки имеют идентификаторы больше 1000. Идентификатор книжной полки уникален для данного пользователя, т. е. два пользователя могут иметь книжную полку с одним и тем же идентификатором, которые относятся к разным книжным полкам. Вы можете использовать API, чтобы получить идентификатор книжной полки, выполнив запрос, который возвращает ресурс книжной полки; вы можете найти идентификатор книжной полки в поле 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

• Идентификатор книжной полки
  

  При просмотре конкретной книжной полки на сайте вы можете найти идентификатор книжной полки в URL-параметре as_coll . Вот пример:

  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 — возвращает все поля объема.
• 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 — возвращает все поля объема.
• 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 и Shelf Path на идентификаторы, указывающие пользователя и книжную полку, которую вы хотите получить. Дополнительную информацию см. в разделе «Идентификаторы 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 и Shelf Path на идентификаторы, указывающие пользователя и книжную полку, которую вы хотите получить. Дополнительную информацию см. в разделе «Идентификаторы 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 .

Необязательные параметры запроса

Вы можете использовать стандартные параметры запроса при удалении всех томов с одной из книжных полок аутентифицированного пользователя.

Справочник по параметрам запроса

В этом разделе приведены параметры запроса, которые можно использовать с Books API. Все значения параметров должны быть закодированы в URL.

Стандартные параметры запроса

Параметры запроса, применимые ко всем операциям Books API, описаны в разделе «Системные параметры» .

Параметры запроса, специфичные для API

Параметры запроса, которые применяются только к определенным операциям в Books API, приведены в следующей таблице.

Параметр	Значение	Примечания	Применимость
download	Ограничьте объемы доступностью загрузки.	В настоящее время единственным поддерживаемым значением является epub . Для доступа к загрузке может потребоваться покупка.	Выполнение поиска
filter	Фильтруйте результаты поиска по типу тома и доступности.	Поддерживаемые фильтры: filter=partial — ограничить результаты только томами, где хотя бы часть текста доступна для предварительного просмотра. filter=full — ограничить результаты томами, где весь текст доступен для просмотра. filter=free-ebooks — ограничить результаты бесплатными электронными книгами Google. filter=paid-ebooks – Ограничить результаты только электронными книгами Google с ценой за покупку. filter=ebooks – ограничить результаты только электронными книгами Google, платными или бесплатными. Примерами неэлектронных книг могут быть материалы издателя, доступные в ограниченном предварительном просмотре и не предназначенные для продажи, или журналы.	Выполнение поиска
langRestrict	Ограничивает возвращаемые тома теми, которые помечены указанным языком.	Ограничьте результаты поиска теми, кто говорит на определенном языке, указав langRestrict двухбуквенный код ISO-639-1, например «en» или «fr».	Выполнение поиска
maxResults	Максимальное количество элементов, возвращаемых с помощью этого запроса.	Для любого запроса ко всем элементам коллекции вы можете разбить результаты на страницы, указав startIndex и maxResults в параметрах запроса. По умолчанию: maxResults=10 Максимально допустимое значение: maxResults=40.	Выполнение поиска Список книжных полок пользователей Получение списка томов на книжных полках пользователей Перечислите мои книжные полки Перечислите тома моей книжной полки
orderBy	Порядок результатов поиска по объему.	По умолчанию поисковый запрос возвращает результаты maxResults , где maxResults — это параметр, используемый при нумерации страниц, отсортированный по наиболее релевантному значению. Вы можете изменить порядок, задав для параметра orderBy одно из следующих значений: orderBy=relevance — возвращает результаты поиска в порядке от наиболее релевантных к наименее (это значение по умолчанию). orderBy=newest — возвращает результаты поиска в порядке от самой новой опубликованной даты до самой старой.	Выполнение поиска
printType	Ограничьтесь книгами или журналами.	Поддерживаемые значения: printType=all — возвращает все типы содержимого тома (без ограничений). Это значение по умолчанию. printType=books — Возвращает только книги. printType=magazines — Возвращает только журналы.	Выполнение поиска
projection	Ограничьте возвращаемую информацию об объеме подмножеством полей.	Поддерживаемые проекции: projection=full — включает все метаданные тома (по умолчанию). projection=lite — включает только тему тома и метаданные доступа.	Выполнение поиска Получение тома Получение списка томов на книжных полках пользователей Перечислите тома моей книжной полки
q	Полнотекстовая строка запроса.	При создании запроса перечислите условия поиска, разделенные знаком «+», в форме q =term1+term2_term3 . (В качестве альтернативы вы можете разделить их пробелом, но, как и все значения параметров запроса, пробелы должны быть закодированы в URL-адресе.) API возвращает все записи, соответствующие всем критериям поиска (например, использование AND между терминами). Как и веб-поиск Google, API ищет полные слова (и связанные слова с той же основой), а не подстроки. Чтобы найти точную фразу, заключите ее в кавычки: q="exact phrase" . Чтобы исключить записи, соответствующие данному термину, используйте форму q=-term . Условия поиска не чувствительны к регистру. Пример: для поиска всех записей, содержащих точную фразу "Elizabeth Bennet" и слово "Darcy" , но не содержащих слово "Austen" , используйте следующее значение параметра запроса: q="Elizabeth+Bennet"+Darcy-Austen Существуют специальные ключевые слова (с учетом регистра), которые вы можете указать в условиях поиска для поиска в определенных полях, например: intitle : возвращает результаты, в заголовке которых находится текст, следующий за этим ключевым словом. inauthor : возвращает результаты, в которых текст, следующий за этим ключевым словом, встречается у автора. inpublisher : возвращает результаты, в которых текст, следующий за этим ключевым словом, найден у издателя. subject : Возвращает результаты, в которых текст, следующий за этим ключевым словом, указан в списке категорий тома. isbn : возвращает результаты, в которых текст, следующий за этим ключевым словом, является номером ISBN. lccn : возвращает результаты, в которых текст после этого ключевого слова представляет собой контрольный номер Библиотеки Конгресса. oclc : возвращает результаты, в которых текст, следующий за этим ключевым словом, является номером онлайн-компьютерного библиотечного центра.	Выполнение поиска
startIndex	Позиция в коллекции, с которой начинается список результатов.	Для любого запроса ко всем элементам коллекции вы можете разбить результаты на страницы, указав startIndex и maxResults в параметрах запроса. Индекс первого элемента равен 0.	Выполнение поиска Список книжных полок пользователей Получение списка томов на книжных полках пользователей Перечислите мои книжные полки Перечислите тома моей книжной полки
volumeId	Идентифицирует том, связанный с запросом.	Указывает том, который нужно добавить или удалить с книжной полки.	Добавляю том на свою книжную полку Убираю том с книжной полки