Использование 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 Книг, вам следует прочитать Начало работы , прежде чем приступать к написанию кода.

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

Каждый запрос, отправляемый вашим приложением в 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 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применяется ко всем типам приложений:

1. Когда вы создаете свое приложение, вы регистрируете его с помощью Google API Console . Затем Google предоставляет информацию, которая понадобится вам позже, например идентификатор клиента и секрет клиента.
2. Активируйте 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

Запросы к 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 Книг

Вам необходимо указать поля ID с определенными вызовами методов 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

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

  При просмотре конкретной книжной полки на сайте вы можете найти идентификатор книжной полки в параметре 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	Ограничение объемов по доступности загрузки.	В настоящее время единственным поддерживаемым значением является 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 возвращает все записи, которые соответствуют всем условиям поиска (например, при использовании И между условиями). Как и веб-поиск 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	Идентифицирует том, связанный с запросом.	Указывает том, который нужно добавить или удалить с книжной полки.	Добавление тома на мою книжную полку Удаление тома с моей книжной полки