Начиная

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

Введение

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

Прежде чем ты начнешь

Получить учетную запись Google

Для тестирования вам потребуется учетная запись Google . Если у вас уже есть тестовая учетная запись, все готово; вы можете посетить пользовательский интерфейс Google Книг , чтобы настроить, изменить или просмотреть свои тестовые данные.

Знакомство с книгами

Если вы не знакомы с концепциями Google Книг, вам следует прочитать этот документ и поэкспериментировать с пользовательским интерфейсом, прежде чем приступать к программированию. В этом документе предполагается, что вы знакомы с концепциями веб-программирования и форматами веб-данных.

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

Когда ваше приложение запрашивает личные данные, запрос должен быть авторизован аутентифицированным пользователем, имеющим доступ к этим данным.

В частности, все операции в разделе "Моя библиотека" в API Google Книг считаются частными и требуют проверки подлинности и авторизации. Кроме того, любая операция по изменению данных Google Книг может выполняться только пользователем, которому принадлежат эти данные.

Когда ваше приложение запрашивает общедоступные данные, запрос не требует авторизации, но должен сопровождаться идентификатором, например ключом API.

Сведения о том, как авторизовать запросы и использовать ключи API, см. в разделе Авторизация запросов и идентификация вашего приложения в документе Использование API.

Справочная информация об API книг

Концепции книг

Google Книги построены на четырех основных принципах:

  • Том . Том представляет собой данные о книге или журнале, которые хранятся в Google Книгах. Это основной ресурс в API книг. Все остальные ресурсы в этом API либо содержат том, либо аннотируют его.
  • Книжная полка : Книжная полка представляет собой набор томов. Google Книги предоставляют набор предопределенных книжных полок для каждого пользователя, некоторые из которых полностью управляются пользователем, некоторые автоматически заполняются в зависимости от активности пользователя, а некоторые из них смешаны. Пользователи могут создавать, изменять или удалять другие книжные полки, которые всегда заполняются томами вручную. Книжные полки могут быть сделаны пользователем частными или общедоступными.

    Примечание. Создание и удаление книжных полок, а также изменение настроек конфиденциальности для книжных полок в настоящее время возможно только через сайт Google Книги .

  • Обзор . Обзор тома представляет собой комбинацию звездного рейтинга и/или текста. Пользователь может отправить один отзыв на каждый том. Обзоры также доступны из внешних источников и имеют соответствующие атрибуты.
  • Позиция чтения : Позиция чтения указывает последнюю позицию чтения в томе для пользователя. У пользователя может быть только одна позиция для чтения на том. Если пользователь ранее не открывал этот том, то позиции чтения не существует. Позиция чтения может хранить подробную информацию о позиции вплоть до разрешения слова. Эта информация всегда является частной для пользователя.

Модель данных API книг

Ресурс — это отдельный объект данных с уникальным идентификатором. Books API работает с двумя типами ресурсов на основе описанных выше концепций:

  • Ресурс тома : представляет том.
  • Ресурс книжной полки : представляет одну книжную полку для определенного пользователя.

Модель данных Books API основана на группах ресурсов, называемых коллекциями:

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

Google предоставляет набор предопределенных книжных полок для каждого пользователя:

  • Избранное: Мобильная книжная полка.
  • Куплено: заполняется томами, которые приобрел пользователь. Пользователь не может вручную добавлять или удалять тома.
  • Читать: Изменяемая книжная полка.
  • Читаю сейчас: Изменяемая книжная полка.
  • Прочитал: Изменяемая книжная полка.
  • Просмотрено: заполнено томами, просмотренными пользователем. Пользователь не может вручную добавлять или удалять тома.
  • Недавно просмотренные: содержит тома, недавно открытые пользователем в веб-ридере. Пользователь не может вручную добавлять тома.
  • Мои электронные книги: Изменяемая книжная полка. Купленные книги добавляются автоматически, но их можно удалить вручную.
  • Книги для вас: заполнены персонализированными рекомендациями по объему. Если у нас нет рекомендаций для пользователя, этой книжной полки не существует.

Пример книжных полок:

  • "Избранное"
    • "Гарри Поттер"
  • "Мои электронные книги"
    • "Выключатель"
    • "Сумерки"
    • "Девушка с татуировкой дракона"

Операции API книг

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

Операция Описание HTTP-сопоставления REST
список Перечисляет указанное подмножество ресурсов в коллекции. GET для коллекции URI.
вставлять Вставляет новый ресурс в коллекцию (создавая новый ресурс). POST на URI коллекции, где вы передаете данные для нового ресурса.
получить Получает определенный ресурс. GET для URI ресурса.
Обновить Обновляет определенный ресурс. PUT в URI ресурса, где вы передаете данные для обновленного ресурса.
Удалить Удаляет определенный ресурс. DELETE в URI ресурса, где вы передаете данные для удаляемого ресурса.

Операции, которые поддерживаются для различных типов ресурсов, приведены в таблице ниже. Операции, которые применяются к личным данным пользователя, называются операциями «Моя библиотека», и все они требуют аутентификации .

Тип ресурса
Поддерживаемые операции
список вставлять получить Обновить Удалить
Объемы да* да
Книжные полки да* да, ПОДТВЕРЖДЕН да* да, ПОДТВЕРЖДЕН да, ПОДТВЕРЖДЕН
Позиции чтения да, ПОДТВЕРЖДЕН да, ПОДТВЕРЖДЕН да, ПОДТВЕРЖДЕН да, ПОДТВЕРЖДЕН

*Доступны как AUTHENTICATED , так и неаутентифицированные версии этих операций, где аутентифицированные запросы работают с частными данными пользователя «Моя библиотека», а неаутентифицированные запросы работают только с общедоступными данными.

Стили вызова

Существует несколько способов вызова API:

  • Использование REST напрямую
  • Использование REST из JavaScript (код на стороне сервера не требуется)

ОТДЫХАТЬ

REST — это стиль архитектуры программного обеспечения, обеспечивающий удобный и последовательный подход к запросу и изменению данных.

Термин REST является сокращением от « Передача репрезентативного состояния ». В контексте API Google это относится к использованию глаголов HTTP для извлечения и изменения представлений данных, хранящихся в Google.

В системе RESTful ресурсы хранятся в хранилище данных; клиент отправляет запрос серверу на выполнение определенного действия (например, создание, извлечение, обновление или удаление ресурса), а сервер выполняет действие и отправляет ответ, часто в форме представления указанного ресурса.

В RESTful API Google клиент указывает действие с помощью команды HTTP, такой как POST , GET , PUT или DELETE . Он определяет ресурс с помощью глобально уникального URI следующего вида:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Поскольку все ресурсы API имеют уникальные доступные по HTTP URI, REST обеспечивает кэширование данных и оптимизирован для работы с распределенной сетевой инфраструктурой.

Вы можете найти полезными определения методов в документации по стандартам HTTP 1.1; они включают спецификации для GET , POST , PUT и DELETE .

REST в API книг

Поддерживаемые операции Books напрямую сопоставляются с HTTP-командами REST, как описано в разделе Операции API Books .

Конкретный формат для URI Books API:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

где resourceID — это идентификатор тома или ресурса книжной полки, а parameters — это любые параметры, применяемые к запросу. Дополнительные сведения см. в разделе Справочник по параметрам запроса .

Формат расширений пути resourceID позволяет определить ресурс, с которым вы сейчас работаете, например:

https://www.googleapis.com/books/v1/volumes
https://www.googleapis.com/books/v1/volumes/volumeId
https://www.googleapis.com/books/v1/mylibrary/bookshelves
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
...

Обратите внимание, что операции с mylibrary в URI применяются только к данным частной библиотеки текущего аутентифицированного пользователя. Полный набор URI, используемых для каждой поддерживаемой операции в API, приведен в документе Справочник по API книг .

Вот несколько примеров того, как это работает в Books API.

Выполните поиск для квилтинга:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

Получить информацию о томе s1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

ОТДЫХ из JavaScript

Вы можете вызывать API книг с помощью REST из JavaScript (также называемого JSON-P ), используя параметр запроса callback и функцию обратного вызова. Это позволяет вам писать многофункциональные приложения, которые отображают данные Книг, без написания кода на стороне сервера.

Примечание. Вы можете вызывать аутентифицированные методы, передав токен OAuth 2.0 с помощью параметра access_token . Чтобы получить токен OAuth 2.0 для использования с JavaScript, следуйте инструкциям, описанным в OAuth 2.0 для клиентских веб-приложений . На вкладке «Доступ к API» консоли API обязательно настройте идентификатор клиента для веб-приложений и используйте эти учетные данные OAuth 2.0 при получении токена.

В следующем примере этот подход используется для отображения результатов поиска по запросу «Гарри Поттер»:

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

Формат данных

JSON

JSON (нотация объектов JavaScript) — это распространенный независимый от языка формат данных, который обеспечивает простое текстовое представление произвольных структур данных. Для получения дополнительной информации см. json.org .