Эта страница переведена с помощью Cloud Translation API.

Начало работы

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

Введение
Прежде чем ты начнешь
Фон API книг
Стиль звонка
1. ОТДЫХ
Формат данных
1. JSON

Введение

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

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

Получить аккаунт Google

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

Познакомьтесь с Книгами

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

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

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

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

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

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

Фон API книг

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

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

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

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

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

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

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

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

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

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

Операция	Описание	Сопоставления REST HTTP
список	Перечисляет указанное подмножество ресурсов в коллекции.	`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 имеют уникальные URI, доступные по HTTP, REST обеспечивает кэширование данных и оптимизирован для работы с распределенной инфраструктурой Интернета.

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

REST в API книг

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

Конкретный формат URI 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 .

Вот несколько примеров того, как это работает в 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 и функцию обратного вызова. Это позволяет вам писать многофункциональные приложения, которые отображают данные Books без написания кода на стороне сервера.

Примечание. Вы можете вызвать аутентифицированные методы, передав токен 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 .