Dynamic Links

Функция динамических ссылок Google Книг позволяет создавать более настраиваемые и надежные ссылки на Google Книги с вашего сайта. Например, этот инструмент позволяет создавать «интеллектуальные» ссылки, которые появляются только тогда, когда книга находится в нашем индексе, или отображать ссылки, указывающие вашим пользователям, можно ли предварительно просмотреть книгу в Google Книгах. Функция «Динамические ссылки» также позволяет включать миниатюру изображения в ссылку на Google Книги. Этот документ предназначен для того, чтобы вы могли быстро добавить эту функциональность на свой сайт.

Примечание. Ранее эта функция называлась API просмотра книг.

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

Содержание

  1. Аудитория
  2. Терминология Поиска книг
  3. Введение
  4. Рекомендации по брендингу
  5. Клиентский API
    1. Формат URL-адреса запроса
    2. Формат результатов JSON
  7. Синхронный и асинхронный режимы
  8. Часто задаваемые вопросы
  9. Примеры кода

Аудитория

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

Терминология Поиска книг

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

Полный обзор
Вся книга доступна для просмотра. Эти книги могут находиться в общественном достоянии.
Ограниченный предварительный просмотр
Часть книги доступна для просмотра. Эта книга защищена авторским правом, и Google Книги получили разрешение сделать эти страницы доступными для пользователей. Эти книги отличаются от книг просмотра фрагментов тем, что пользователи могут просматривать страницы целиком.
Просмотр фрагмента и без предварительного просмотра
Пользователи видят только страницу «О книге». В лучшем случае доступны только короткие отрывки из книги. Эта книга либо не была отсканирована, либо защищена авторскими правами, и Google Книги не получили разрешения на предоставление более чем нескольких «фрагментов», связанных с поисковым запросом пользователя.

Введение

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

Динамические ссылки предоставляют альтернативный программный метод на стороне клиента для запроса возможности просмотра книги с помощью JavaScript. Это позволяет добавлять более надежные и предсказуемые ссылки на Поиск книг, что обеспечивает более стабильный опыт для ваших пользователей. Поскольку видимость зависит от местоположения конечного пользователя, интерфейс динамической ссылки не предназначен для серверных или автономных запросов.

Чтобы понять, на что способны динамические ссылки, перейдите к примерам кода в конце этого документа.

Рекомендации по брендингу

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

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

Пример брендинга

Фрикономика: экономист-мошенник исследует скрытую сторону всего
Стивен Левитт и Стивен Дабнер

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

Клиентский API

В основе динамической ссылки на стороне клиента лежит формат URL, который позволяет разработчикам создавать URL-адреса, запрашивающие информацию об одной или нескольких книгах, и отправлять запросы в Google Книги с помощью < script> < script> тег.

Пример синтаксиса:
< script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback">< /script> < script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback">< /script> < script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback">< /script>

Формат запроса

Формат URL-адреса похож на синтаксис URL-адреса , используемый для ссылки на книги , но поле идентификатора книги может содержать несколько идентификаторов книг, разделенных запятыми, а также дополнительные параметры jscmd и callback. При необходимости могут присутствовать дополнительные аргументы для управления фильтрами видимости.

Dynamic Links поддерживает несколько различных методов идентификации книг: ISBN, номера OCLC и ключи LCCN. API позволяет выполнять пакетные запросы размером до максимального размера запроса GET.

ISBN
&bibkeys=ISBN:0451526538 (API поддерживает ISBN 10 и 13.)
OCLC
&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;
};

Эти поля содержат следующую информацию:

bib_key
Идентификатор, используемый для запроса этой книги.
info_url
URL-адрес страницы в Google Книгах с информацией о книге (страница об этой книге).
preview_url
URL-адрес предварительного просмотра книги, по которому пользователь переходит непосредственно к обложке книги. Если для запроса доступны только книги с просмотром фрагмента или без предварительного просмотра, URL-адрес для предварительного просмотра не будет возвращен.
thumbnail_url
URL миниатюры обложки книги.
предварительный просмотр
Значение, указывающее состояние просмотра книги: full (для книг с полным просмотром), partial (для книг с ограниченным предварительным просмотром) или noview (для книг с фрагментами или без предварительного просмотра).
встраиваемый
Это логическое значение имеет значение true , если книгу можно встроить на сторонние страницы с помощью встроенного средства просмотра Поиска книг .

Ответ представляет собой объект JSON с двумя полями: «книги», которые имеют значение карты объектов книг, и «параметры», которые содержат список параметров, включенных для этого запроса. Если параметры не были указаны, поле «Параметры» в ответе может быть опущено. Например:

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.

Параметры и дополнительные поля

jscmd
Запрос к Google Книгам.
перезвонить
Имя функции JavaScript, в которую мы передаем возврат.

Синхронный и асинхронный режимы

Асинхронный режим

В асинхронном режиме разработчик помещает <script> в <head> документа и создает URL-адрес со всеми идентификаторами, необходимыми для отображения страницы. Данные получены от вызова в переменной. Это делает информацию книги доступной для остальной части документа, и к ней можно получить немедленный доступ в HTML и JavaScript.

Синхронный режим

В синхронном режиме разработчик использует URL в середине HTML <body> ; ответ обрабатывается с помощью обратного вызова 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. В этом примере показано, как выполнить несколько различных вызовов без обновления страницы.