Funkcja Linki dynamiczne w Książkach Google umożliwia tworzenie bardziej elastycznych i niezawodnych linków do Książek Google z Twojej witryny, które można dostosować do własnych potrzeb. To narzędzie pozwala na przykład generować „inteligentne” linki, które pojawiają się tylko wtedy, gdy książka znajduje się w naszym indeksie, lub wyświetlać linki wskazujące użytkownikom, czy w Książkach Google można zobaczyć podgląd książki. Funkcja Linki dynamiczne umożliwia też dołączenie miniatury do linku do Książek Google. Ten dokument ma Ci pomóc w szybkim dodawaniu tej funkcji do Twojej witryny.
Uwaga: ta funkcja nosiła wcześniej nazwę Book Viewability API.
Kreator podglądu to narzędzie oparte na Linkach dynamicznych, które jeszcze bardziej ułatwia dodawanie linków do podglądu książek z witryny przez skopiowanie kilku wierszy kodu. Ten dokument jest przeznaczony dla bardziej zaawansowanych programistów, którzy chcą dostosować sposób łączenia z usługą Book Search.
Spis treści
- Odbiorcy
- Terminologia dotycząca usługi Book Search
- Wprowadzenie
- Wskazówki dotyczące promowania marki
- Interfejs API po stronie klienta
- Tryby synchroniczne i asynchroniczne
- Najczęstsze pytania
- Przykładowy kod
Odbiorcy
Dokumentacja linków dynamicznych jest przeznaczona dla programistów, którzy chcą pisać aplikacje internetowe zawierające linki do książek dostępnych w Książkach Google. W tej dokumentacji zakładamy, że znasz protokół HTTP i podstawowy JavaScript.
Terminologia dotycząca usługi Book Search
W Książkach Google przestrzegane są lokalne ograniczenia praw autorskich obowiązujące użytkowników, w związku z czym podgląd lub pełny podgląd niektórych książek nie jest dostępny we wszystkich lokalizacjach. Widoczność jest podzielona na te klasy:
- Pełny widok
- Cała książka jest dostępna. Te książki mogą należeć do domeny publicznej.
- Ograniczony podgląd
- Część książki jest widoczna. Ta książka jest chroniona prawem autorskim. Książki Google otrzymały pozwolenie na udostępnienie tych stron użytkownikom. Różnią się one od książek z widokiem fragmentów tym, że użytkownicy mogą przeglądać całe strony.
- Widok fragmentu i brak podglądu
- Użytkownicy widzą tylko stronę „Informacje o książce”. Dostępne są maksymalnie krótkie fragmenty książki. Ta książka nie została zeskanowana lub jest objęta prawami autorskimi. Książki Google nie otrzymały zgody na udostępnianie większej liczby „fragmentów” powiązanych z hasłem wyszukiwanym przez użytkownika.
Wprowadzenie
Dokumentacja linków statycznych opisuje bardzo prosty sposób generowania adresów URL do strony konkretnej książki w Książkach Google. Czasem zdarza się jednak, że określonej książki nie ma w indeksie Książek Google lub że podgląd nie jest dostępny dla użytkownika w określonej lokalizacji geograficznej. Linki statyczne są czasem „ślepe”, więc czasem nie przynoszą zamierzonego efektu.
Linki dynamiczne to alternatywna, zautomatyzowana metoda wysyłania zapytań o widoczność książki za pomocą JavaScriptu po stronie klienta. Umożliwia to dodanie bardziej rzetelnych i przewidywalnych linków do usługi Book Search, co zapewnia bardziej spójną obsługę. Ze względu na to, że widoczność różni się w zależności od lokalizacji użytkownika, interfejs linków dynamicznych nie jest przeznaczony do zapytań po stronie serwera ani zapytań offline.
Aby poznać możliwości Linków dynamicznych, przejdź do przykładowego kodu na końcu tego dokumentu.
Wskazówki dotyczące oznaczania marki
Renderując linki dynamiczne, musisz przestrzegać wytycznych dotyczących marki, które dotyczą rodziny interfejsów API Książek Google. W szczególności
- Musisz podać informacje o autorze utworu i linki do Książek Google.
- Podczas tworzenia linków do podglądu w Książkach Google możesz używać wyłącznie zatwierdzonego przycisku podglądu Google.
- Wszystkie linki tekstowe, przyciski, dokumentacja i tekst opisowy powinny być zgodne z zatwierdzonymi konwencjami nazewnictwa. Na przykład podczas dodawania linków do podglądu w Książkach Google nie należy używać czasowników „pobierz” lub „czytaj”, ponieważ można pobrać w całości tylko utwory z domeny publicznej.
Przykładowe elementy marki
![](https://developers-dot-devsite-v2-prod.appspot.com/static/books/images/gbs_preview_button1.gif?authuser=8&hl=pl)
Sekcja Przykłady na końcu tego dokumentu zawiera dodatkowe przykłady zgodne z aktualnymi wskazówkami dotyczącymi promowania marki.
Interfejs API po stronie klienta
Podstawowym elementem dynamicznego linku po stronie klienta jest format adresów URL, który umożliwia programistom tworzenie adresów URL z prośbami o informacje o jednej lub wielu książkach i wysyłanie żądań do Książek Google za pomocą tagu <script>
.
- Przykład składni:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
Format żądania
Format adresu URL jest podobny do składni adresu URL używanej do tworzenia linków do książek, z tym że pole identyfikatora książki może zawierać wiele identyfikatorów książek rozdzielonych przecinkami oraz dodatkowe parametry „jscmd” i „callback”. Opcjonalnie możesz podać dodatkowe argumenty do sterowania filtrami widoczności.
Linki dynamiczne obsługują kilka różnych metod identyfikacji książek: numery ISBN, numery OCLC i klucze LCCN. Interfejs API zezwala na zapytania zbiorcze, których rozmiar nie przekracza maksymalnego rozmiaru żądania GET.
- ISBN
&bibkeys=ISBN:0451526538
(Interfejs API obsługuje zarówno numery ISBN 10, jak i 13).- Numer OCLC
&bibkeys=OCLC:36792831
- Numer LCCN
&bibkeys=LCCN:96072233
Format wyników w formacie JSON
Odpowiedź z tego wywołania zawiera informacje o żądanych książkach zwróconych jako co najmniej 1 obiekt JSON. Obiekty JSON mają taką strukturę:
JsonSearchResult { string bib_key; string info_url; string preview_url; string thumbnail_url; string preview; };
W tych polach znajdują się następujące informacje:
- bib_key
- Identyfikator użyty do wysłania zapytania dotyczącego tej książki.
- info_url
- Adres URL strony w Książkach Google, która zawiera informacje o książce (stronie z informacjami o książce).
- preview_url
- Adres URL podglądu książki, który przekierowuje użytkownika bezpośrednio do jej okładki. Jeśli dla żądania dostępne są tylko książki w widoku krótkiego widoku lub Brak podglądu, nie zostanie zwrócony żaden adres URL podglądu.
- thumbnail_url
- Adres URL miniatury z okładką książki.
- wersja przedpremierowa
- Wartość wskazująca stan widoczności książki:
full
(w przypadku książek w pełnym widoku),partial
(w przypadku książek z ograniczonym podglądem) lubnoview
(książki z fragmentem lub bez podglądu). - możliwe do umieszczenia
- Wartość logiczna to
true
, jeśli książkę można umieścić na stronach osób trzecich za pomocą wbudowanej przeglądarki Book Search. - jscmd
- Prośba do Książek Google.
- wywołanie zwrotne
- Nazwa funkcji JavaScriptu, do której przekazujemy zwrot.
- P: Czy do korzystania z linków dynamicznych potrzebuję klucza interfejsu API lub innych uprawnień?
- O: Korzystanie z linków dynamicznych nie wymaga klucza API ani innej autoryzacji. Na początek skopiuj i wklej jeden z naszych przykładów, a potem zacznij majsterkować.
- P: Co z przeglądarkami, które nie obsługują JavaScriptu lub mają go wyłączoną?
- O: Jeśli w przeglądarce użytkownika nie jest włączony JavaScript, nie można sprawdzić, czy Książki Google mają dostęp do książki. W przypadku przeglądarek bez JavaScriptu zalecamy używanie statycznej struktury linków Książek Google. Pamiętaj jednak, że nie możesz z wyprzedzeniem sprawdzić, czy link do danej książki jest dostępny w Książkach Google.
- P: Ile książek mogę wyszukać jednocześnie?
- O: Liczba książek, które można wyszukać, jest ograniczona tylko długością żądań GET. Maksymalna długość adresu URL w przeglądarce Microsoft Internet Explorer (2083 znaki) ogranicza długość żądań GET.
- P: Przed chwilą w Książkach Google wyniki były zwracane wyniki dotyczące książki. Dlaczego nie zwraca teraz wyników?
- O: Deweloperzy często przesyłają nietypową liczbę żądań, dlatego możesz przypadkowo zastosować środki bezpieczeństwa opisane w Książkach Google. Aby to sprawdzić, wyświetl wartość zwracaną przez interfejs API. Jeśli jest to prośba o wypełnienie testu captcha, oznacza to, że liczba Twoich zapytań jest zbyt duża. Zalecamy zalogowanie się w Książkach Google i spróbowanie jeszcze raz.
- P: Co z prywatnością?
- O: W odpowiedziach na pytania o widoczność książek Google otrzymuje dane z dzienników serwerów, które nie umożliwiają identyfikacji konkretnej osoby. Szanujemy prywatność użytkowników, dlatego dane te traktujemy zgodnie z opisem w naszej Polityce prywatności. Jeśli udostępniasz użytkownikom usługę, która obejmuje widoczność książek, możesz ich poinformować, że Twoja usługa przesyła zapytania do Google za pomocą linków dynamicznych.
- Przycisk podglądu strony książki
Jeśli chcesz użyć linków dynamicznych, aby dodać przyciski „podgląd” do poszczególnych stron książki w witrynie, jest to przykład dla Ciebie. Ta implementacja korzysta z synchronicznego wywołania Książek Google. - Lista czytania kursów
Ten przykład przedstawia typową listę książek na dany kurs akademicki. Używamy jednego synchronicznego wywołania, aby podać linki do stron książek w Książkach Google, dodać zdjęcia okładek i wskazać dostępność podglądu. - Alternatywna lista książek
Podobnie jak w poprzednim przykładzie, ten przykład dodaje linki do usługi Book Search za pomocą asynchronicznego wywołania zwrotnego interfejsu API. - Interaktywna aplikacja AJAX
Może Cię zainteresować wykorzystanie linków dynamicznych w bardzo interaktywnej aplikacji AJAX. Ten przykład pokazuje, jak wykonać określoną liczbę połączeń bez odświeżania strony.
Odpowiedź to obiekt JSON z 2 polami: „books” z wartością mapy obiektów książek i „options” zawierającą listę opcji włączonych w tym żądaniu. Jeśli nie określono żadnych opcji, pole „options” może zostać pominięte w odpowiedzi. Na przykład:
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"} });
Deweloperzy mogą następnie zmieniać zawartość i wygląd swoich stron internetowych na podstawie wyników w formacie JSON pobranych z serwera GBS. Obecnie GBS nie udostępnia bibliotek umożliwiających modyfikację DOM.
Parametry i dodatkowe pola
Tryb synchroniczny a asynchroniczny
Tryb asynchroniczny
W trybie asynchronicznego deweloper umieszcza tag <script>
w sekcji <head>
dokumentu i tworzy adres URL ze wszystkimi identyfikatorami potrzebnymi do renderowania strony. Dane są odbierane z połączenia w zmiennej. Dzięki temu informacje o książce staną się dostępne dla reszty dokumentu i będą od razu dostępne w kodzie HTML i JavaScript.
Tryb synchroniczny
W trybie synchronicznym deweloper używa adresu URL w środku kodu HTML <body>
. Odpowiedź jest obsługiwana przy użyciu wywołania zwrotnego JavaScriptu.
Najczęstsze pytania
Przykładowy kod
Ta sekcja zawiera przykłady, które pokazują różne sposoby korzystania z Linków dynamicznych. Możesz kliknąć dowolny przykład, aby zobaczyć, jak to działa. Aby zobaczyć kod źródłowy, „wyświetl źródło” w przeglądarce.