Функция динамических ссылок Google Книги позволяет создавать на вашем сайте более настраиваемые и надежные ссылки на Google Книги. Например, этот инструмент позволяет создавать «умные» ссылки, которые появляются только тогда, когда книга находится в нашем индексе, или отображать ссылки, указывающие вашим пользователям, можно ли предварительно просмотреть книгу в Google Книгах. Функция динамических ссылок также позволяет включать миниатюру в ссылку на Google Книги. Этот документ предназначен для того, чтобы вы могли быстро добавить эту функциональность на свой сайт.
Примечание. Эта функция ранее называлась API видимости книг.
Мастер предварительного просмотра — это инструмент, созданный на основе динамических ссылок, который еще больше упрощает создание ссылок на предварительный просмотр книг с сайта, просто скопировав несколько строк кода. Этот документ предназначен для более опытных разработчиков, желающих настроить ссылку на Поиск книг.
Содержание
- Аудитория
- Терминология поиска книг
- Введение
- Рекомендации по брендингу
- Клиентский API
- Синхронный и асинхронный режимы
- Часто задаваемые вопросы
- Примеры кода
Аудитория
Документация по динамическим ссылкам предназначена для программистов, которые хотят писать веб-приложения, ссылающиеся на книги в Google Книгах. В этой документации предполагается, что вы знакомы с протоколом HTTP и базовым языком JavaScript.
Терминология поиска книг
Google Книги соблюдают местные ограничения авторских прав пользователя, поэтому предварительный или полный просмотр некоторых книг доступен не во всех странах. Видимость сгруппирована по следующим классам:
- Полный просмотр
- Вся книга доступна для просмотра. Эти книги могут находиться в общественном достоянии.
- Ограниченный предварительный просмотр
- Часть книги доступна для просмотра. Эта книга защищена авторским правом, и Google Книги получили разрешение сделать эти страницы доступными для пользователей. Эти книги отличаются от книг с просмотром фрагментов тем, что пользователи могут просматривать целые страницы.
- Просмотр фрагмента без предварительного просмотра
- Пользователи видят только страницу «О книге». В лучшем случае доступны только короткие выдержки из книги. Эта книга либо не сканировалась, либо находится под защитой авторских прав, и Google Книги не получили разрешения на публикацию более нескольких «фрагментов», связанных с поисковым запросом пользователя.
Введение
В документации по статическим ссылкам описан очень простой способ создания URL-адресов на страницу конкретной книги в Google Книгах. К сожалению, иногда бывает так, что определенная книга отсутствует в индексе Google Книги или предварительный просмотр недоступен для пользователя в определенном географическом месте. Поскольку статические ссылки «слепы», они иногда не дают желаемого эффекта.
Динамические ссылки предоставляют альтернативный программный метод на стороне клиента для запроса видимости книги с помощью JavaScript. Это позволяет вам включать более надежные и предсказуемые ссылки на Поиск книг, что обеспечивает более единообразный опыт работы ваших пользователей. Поскольку видимость зависит от местоположения конечного пользователя, интерфейс динамической ссылки не предназначен для серверных или автономных запросов.
Чтобы получить представление о том, на что способны динамические ссылки, перейдите к примерам кода в конце этого документа.
Рекомендации по брендингу
При отображении динамических ссылок вы должны соблюдать правила брендинга , регулирующие семейство API Google Книг. В частности,
- Вы должны сохранять авторство и ссылки на Google Книги.
- При ссылке на предварительный просмотр в Google Книгах вы должны использовать только одобренную кнопку Google Preview .
- Любые текстовые ссылки, кнопки, документация или описательный текст должны соответствовать утвержденным соглашениям об именах . Например, не следует использовать глаголы «скачать» или «читать» при ссылках на предварительный просмотр Google Книг, поскольку полностью можно загрузить только произведения, являющиеся общественным достоянием.
Пример брендинга
В разделе «Образцы» в конце этого документа представлены дополнительные примеры, соответствующие действующим рекомендациям по брендингу.
Клиентский API
В основе динамической ссылки на стороне клиента лежит формат URL-адресов, который позволяет разработчикам создавать URL-адреса, запрашивающие информацию об одной или нескольких книгах, и отправлять запросы в Google Книги с помощью < script> тег.
- Пример синтаксиса:
-
< script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback">< /script>
Формат запроса
Формат URL-адреса аналогичен синтаксису URL-адреса , используемому для ссылки на книги , но поле идентификатора книги может содержать несколько идентификаторов книг, разделенных запятыми, а также имеются дополнительные параметры «jscmd» и «обратный вызов». При желании могут присутствовать дополнительные аргументы для управления фильтрами видимости.
Dynamic Links поддерживает несколько различных методов идентификации книг: номера ISBN, номера OCLC и ключи LCCN. API позволяет выполнять пакетные запросы размером до максимального размера запроса GET.
- ISBN
-
&bibkeys=ISBN:0451526538(API поддерживает ISBN 10 и 13.) - ОКЛК
-
&bibkeys=OCLC:36792831 - LCCN
-
&bibkeys=LCCN:96072233
Формат результатов JSON
Ответом на этот вызов будет информация о запрошенных книгах, возвращенная в виде одного или нескольких объектов JSON. Объекты JSON используют следующую структуру:
JsonSearchResult {
string bib_key;
string info_url;
string preview_url;
string thumbnail_url;
string preview;
};Эти поля предоставляют следующую информацию:
- нагрудник_ключ
- Идентификатор, используемый для запроса этой книги.
- info_url
- URL-адрес страницы в Google Книгах с информацией о книге (страница об этой книге).
- URL-адрес предварительного просмотра
- URL-адрес предварительного просмотра книги, который направляет пользователя прямо на обложку книги. Если для запроса доступны только книги с просмотром фрагментов или без предварительного просмотра, URL-адрес предварительного просмотра не будет возвращен.
- миниатюра_url
- URL-адрес миниатюры обложки книги.
- предварительный просмотр
- Значение, указывающее состояние видимости книги:
full(для книг с полным просмотром),partial(для книг с ограниченным предварительным просмотром) илиnoview(для книг с фрагментами или без предварительного просмотра). - встраиваемый
- Это логическое значение
true, если книгу можно встроить на сторонние страницы с помощью встроенной программы просмотра Поиска книг. - jscmd
- Запрос в Google Книги.
- перезвонить
- Имя функции JavaScript, которой мы передаем возврат.
- Вопрос: Нужен ли мне ключ API или другое разрешение для использования динамических ссылок?
- О: Для использования динамических ссылок не требуется ключ API или другая авторизация. Чтобы начать, просто скопируйте и вставьте один из наших примеров и начните работать.
- Вопрос: А как насчет браузеров, которые либо не поддерживают JavaScript, либо отключили его?
- О: Невозможно проверить, есть ли в Google Книгах книга, если в браузере пользователя не включен JavaScript. Мы рекомендуем использовать статическую структуру ссылок Google Книги для браузеров без JavaScript, но помните, что вы не можете заранее знать, есть ли в Google Книгах книга, на которую вы ссылаетесь.
- Вопрос: Сколько книг я могу искать одновременно?
- О: Количество книг, которые вы можете найти, ограничено только длиной GET-запросов. В Microsoft Internet Explorer максимальная длина URL-адреса (2083 символа) ограничивает длину запросов GET.
- Вопрос: Google Книги только что возвращал результаты по книге. Почему сейчас не возвращаются результаты?
- Ответ: Поскольку разработчики часто отправляют нетипичное количество запросов, вы можете случайно нарушить меры безопасности, предусмотренные в Google Книгах. Чтобы проверить, происходит ли это, просмотрите, что возвращает API. Если это запрос на ввод капчи, значит вы отправили слишком много запросов. Мы рекомендуем войти в Google Книги и повторить попытку.
- Вопрос: А как насчет конфиденциальности?
- Ответ: Отвечая на запросы о видимости книги, Google получает данные журнала сервера, не позволяющие идентифицировать личность. Мы серьезно относимся к конфиденциальности пользователей и обращаемся с этими данными, как описано в нашей Политике конфиденциальности . Если вы предоставляете пользователям услугу, включающую возможность просмотра книг, вы можете сообщить им, что ваша служба также отправляет запросы в Google через динамические ссылки.
- Кнопка предварительного просмотра страницы книги
Если вы собираетесь использовать динамические ссылки для добавления кнопок «предварительного просмотра» на отдельные страницы книг на вашем сайте, этот пример для вас. Эта реализация использует синхронный вызов Google Книги. - Список чтения курса
В этом примере показан типичный список книг для академического курса. Мы используем один синхронный вызов для создания ссылок на страницы книг в Google Книгах, добавления изображений обложки и указания доступности предварительного просмотра. - Альтернативный список книг
Как и в предыдущем примере, в этом примере ссылки на Поиск книг добавляются с помощью асинхронного обратного вызова API. - Интерактивный AJAX
Возможно, вас заинтересует использование динамических ссылок в высокоинтерактивном приложении AJAX. В этом примере показано, как выполнить несколько различных вызовов без обновления страницы.
Ответом является объект JSON с двумя полями: «books», который имеет значение карты объектов книги, и «options», который содержит список опций, включенных для этого запроса. Если параметры не указаны, поле «Параметры» в ответе можно опустить. Например:
Request:
https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo
Response:
ProcessGBSBookInfo({
"0596000278":{
"bib_key":"0596000278",
"info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg",
"preview":"partial"
},
"ISBN0765304368":{
"bib_key":"ISBN0765304368",
"info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg",
"preview":"full"
},
"0439554934":{
"bib_key":"0439554934",
"info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM",
"preview":"noview"}
});
Затем разработчики могут изменить содержимое и внешний вид своих веб-страниц на основе результатов JSON, полученных с сервера GBS. В настоящее время GBS не предоставляет библиотеки для изменения DOM для этого.
Параметры и дополнительные поля
Синхронный и асинхронный режим
Асинхронный режим
В асинхронном режиме разработчик помещает тег <script> в <head> документа и создает URL-адрес со всеми идентификаторами, необходимыми для отображения страницы. Данные принимаются от вызова в переменную. Это делает информацию о книге доступной для остальной части документа, и к ней можно сразу получить доступ в HTML и JavaScript.
Синхронный режим
В синхронном режиме разработчик использует URL-адрес в середине HTML <body> ; ответ обрабатывается с помощью обратного вызова JavaScript.
Часто задаваемые вопросы
Примеры кода
В этом разделе представлены примеры, иллюстрирующие различные способы использования динамических ссылок. Вы можете щелкнуть любой пример, чтобы увидеть его в действии. Чтобы увидеть базовый код, «просмотрите исходный код» в своем браузере.