Ten dokument zawiera szczegółową wiedzę potrzebną do korzystania z interfejsu Google Books API.
Wprowadzenie
Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje, które mogą współpracować z interfejsem Google Books API. Książki Google mają wizję digitalizacji książek z całego świata. Za pomocą interfejsu API Książek Google możesz wyszukiwać zawartość, porządkować osobistą bibliotekę i edytować ją.
Zanim rozpoczniesz
Załóż konto Google
Do testowania potrzebujesz konta Google. Jeśli masz już konto testowe, możesz przejść do interfejsu Książek Google, aby skonfigurować, edytować lub wyświetlić dane testowe.
Poznaj Książki
Jeśli nie znasz się na pojęciach związanych z Książkami Google, przeczytaj ten dokument i eksperymentuj z interfejsem, zanim zaczniesz kodować. W tym dokumencie założono, że znasz się na pojęciach związanych z programowaniem stron internetowych i formatami danych internetowych.
Więcej informacji o autoryzowaniu żądań i identyfikowaniu aplikacji
Gdy Twoja aplikacja żąda prywatnych danych, użytkownik mający do nich dostęp musi autoryzować takie żądanie.
Wszystkie operacje wykonywane w sekcji „Moja biblioteka” w interfejsie Google Books API są uważane za prywatne i wymagają uwierzytelniania i autoryzacji. Oprócz tego wszelkie działania służące do modyfikowania danych Książek Google mogą być wykonywane tylko przez tych użytkowników, którzy są ich właścicielami.
Gdy aplikacja żąda danych publicznych, żądanie nie musi być autoryzowane, ale musi towarzyszyć mu identyfikator, taki jak klucz interfejsu API.
Informacje o autoryzowaniu żądań i korzystaniu z kluczy interfejsu API znajdziesz w artykule Autoryzowanie żądań i identyfikowanie aplikacji w dokumencie Korzystanie z interfejsu API.
Tło interfejsu API Książek
Pojęcia związane z książkami
4 podstawowych pojęć dotyczących Książek Google:
- Tom: to dane o książce lub czasopiśmie przechowywane w Książkach Google. Jest to główny zasób interfejsu API Książek. Wszystkie pozostałe zasoby w tym interfejsie API zawierają wolumin lub je opisują.
- Półka na książki: to kolekcja książek. Książki Google udostępniają zestaw wstępnie zdefiniowanych półek dla każdego użytkownika. Część z nich jest w pełni zarządzana przez użytkownika, a niektóre są wypełniane automatycznie na podstawie aktywności użytkownika, a niektóre z nich są mieszane. Użytkownicy mogą tworzyć, modyfikować i usuwać inne półki na książki, które zawsze są wypełniane ręcznie. Półki na książki mogą być prywatne lub publiczne.
Uwaga: tworzenie i usuwanie półek na książki oraz modyfikowanie ustawień prywatności na tych półkach można obecnie robić tylko na stronie Książki Google.
- Opinia: opinia o objętości to połączenie oceny z gwiazdką lub tekstu. Użytkownik może przesłać jedną opinię na każdy tom. Opinie są też dostępne z zewnętrznych źródeł i są prawidłowo przypisywane.
- Pozycja czytania: wskazuje ostatnią pozycję do odczytu w obrębie głośności użytkownika. Użytkownik może mieć tylko 1 pozycję odczytu na wolumin. Jeśli użytkownik nie otwierał jeszcze tego woluminu, pozycja odczytu nie istnieje. Pozycja czytania może przechowywać szczegółowe informacje o pozycji do rozdzielczości słowa. Te informacje są zawsze prywatne dla użytkownika.
Model danych interfejsu Books API
Zasób to konkretna jednostka danych z unikalnym identyfikatorem. Działa on na podstawie 2 typów zasobów zgodnie z powyższymi pojęciami:
- Zasób woluminu: reprezentuje wolumin.
- Zasób półki: reprezentuje jedną półkę na określonego użytkownika.
Model danych interfejsu API Książek jest oparty na grupach zasobów zwanych kolekcjami:
- Zbieranie woluminów
- Zbiór woluminów to zbiór każdego zasobu woluminu zarządzanego przez Książki Google.
Dlatego nie możesz wyświetlić wszystkich zasobów woluminu, ale możesz wyświetlić wszystkie zasoby pasujące do zestawu wyszukiwanych haseł.
- Kolekcja półek
- Kolekcja półek składa się ze wszystkich zasobów półki zarządzanych przez Książki Google. Półki z książkami zawsze muszą być umieszczone w kontekście biblioteki konkretnego użytkownika. Półki na książki mogą zawierać 0 lub więcej tomów.
- Ulubione: półka z możliwością dostosowania.
- Kupione: wypełnione wartościami kupionymi przez użytkownika. Użytkownik nie może ręcznie dodawać ani usuwać woluminów.
- Do przeczytania: pełna półka na książki.
- Czytanie teraz: pełna półka na książki.
- Przeczytaj: półka na książki.
- Sprawdzone: reklamy wypełnione woluminami ocenionymi przez użytkownika. Użytkownik nie może ręcznie dodawać ani usuwać woluminów.
- Ostatnio wyświetlane: pola wypełnione woluminami, które użytkownik ostatnio otworzył w czytniku internetowym. Użytkownik nie może ręcznie dodawać woluminów.
- Moje e-booki: półka na książki. Kupione książki są dodawane automatycznie, ale możesz je usunąć ręcznie.
- Książki dla Ciebie: spersonalizowane rekomendacje dotyczące objętości. Jeśli nie mamy rekomendacji dla użytkownika, ta półka nie istnieje.
- „Ulubione”
- „Harry Potter”
- „Moje e-booki”
- „Zmień”
- „Zmierzch”
- „Dziewczynka z tatuażem ze smokiem”
Google udostępnia zestaw wstępnie zdefiniowanych półek dla każdego użytkownika:
Przykładowe półki:
Operacje dotyczące interfejsu Books API
W interfejsie API Książek możesz wywołać 5 różnych metod gromadzenia i zasobów, zgodnie z opisem w tabeli poniżej.
Operacja | Opis | Mapowanie HTTP REST |
---|---|---|
list | Wyświetla określony podzbiór zasobów w kolekcji. | GET w identyfikatorze URI kolekcji. |
wstaw | Wstawia nowy zasób do kolekcji (tworzą nowy zasób). | POST w identyfikatorze URI kolekcji, gdzie przekazujesz dane nowego zasobu. |
pobierz | Pobiera określony zasób. | GET w identyfikatorze URI zasobu. |
zaktualizuj | Aktualizuje konkretny zasób. | PUT w identyfikatorze URI zasobu, w którym przekazujesz dane zaktualizowanego zasobu. |
usuń | Usuwa określony zasób. | DELETE w identyfikatorze URI zasobu, gdzie przekazujesz dane do usunięcia zasobu. |
Operacje obsługiwane w przypadku różnych typów zasobów zostały opisane w tabeli poniżej. Operacje związane z prywatnymi danymi użytkownika są nazywane operacjami „Moja biblioteka” i wymagają one uwierzytelniania.
Typ zasobu |
Obsługiwane operacje |
||||
---|---|---|---|---|---|
list | wstaw | Pobierz | aktualizacja | usuń | |
Tomy | tak* | tak | |||
Półki na książki | tak* | tak, AUTHENTICATED | tak* | tak, AUTHENTICATED | tak, AUTHENTICATED |
Pozycje czytania | tak, AUTHENTICATED | tak, AUTHENTICATED | tak, AUTHENTICATED | tak, AUTHENTICATED |
*Dostępne są obie opcje AUTHENTICATED i nieuwierzytelnione wersje tych operacji, w których uwierzytelnione żądania działają w prywatnych danych użytkownika „Moja biblioteka”, a żądania nieuwierzytelnione działają tylko z danymi publicznymi.
Style połączeń
Interfejs API możesz wywołać na kilka sposobów:
- Użycie REST bezpośrednio
- Wykorzystujesz REST z JavaScriptu (nie jest wymagany kod po stronie serwera)
REST
REST to styl architektury oprogramowania, który zapewnia wygodne i spójne podejście do żądania i modyfikowania danych.
Termin „EST” to skrót od „Representational State Transfer”. W kontekście interfejsów API Google oznacza to używanie czasowników HTTP w celu pobierania i modyfikowania informacji przechowywanych przez Google.
W systemie REST zasoby są przechowywane w magazynie danych. Klient wysyła żądanie wykonania określonego działania (na przykład utworzenia, pobrania, zaktualizowania lub usunięcia zasobu), a serwer wykonuje tę czynność i wysyła odpowiedź, często w postaci reprezentacji określonego zasobu.
W interfejsach API REST Google klient wskazuje działanie za pomocą czasownika HTTP, np. POST
, GET
, PUT
lub DELETE
. Określa zasób przez globalnie unikalny identyfikator URI tego formularza:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Wszystkie zasoby API mają unikalne identyfikatory URI dostępne w protokole HTTP, dlatego funkcja REST umożliwia przechowywanie danych w pamięci podręcznej i zoptymalizowanie jej do pracy z rozproszoną infrastrukturą internetową.
Definicje metod znajdziesz w dokumentacji standardów HTTP 1.1. Zawierają one specyfikacje GET
, POST
, PUT
i DELETE
.
REST w interfejsie Books API
Obsługiwane operacje dotyczące książki są mapowane bezpośrednio na czasowniki HTTP REST w sposób opisany w opisie operacji interfejsu Books API.
Identyfikator URI identyfikatorów interfejsu API Książek Google to:
https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters
gdzie resourceID
to identyfikator zasobu lub półki na książki, a parameters
to wszystkie parametry, które mają być użyte w zapytaniu. Więcej informacji znajdziesz w dokumentacji parametrów zapytań.
Format rozszerzeń resourceID
ścieżek pozwala zidentyfikować zasób, z którego aktualnie korzystasz, na przykład:
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 ...
Pamiętaj, że operacje z użyciem identyfikatora mylibrary
w identyfikatorze URI dotyczą tylko danych prywatnych bibliotek obecnie uwierzytelnionego użytkownika. Pełny zestaw identyfikatorów URI używanych w każdej obsługiwanej operacji w interfejsie API można znaleźć w dokumencie Books API Reference (Informacje o interfejsie API Książek).
Oto kilka przykładów, jak to działa w interfejsie Books API.
Wyszukaj pikowanie:
GET https://www.googleapis.com/books/v1/volumes?q=quilting
Uzyskaj informacje o woluminie s1gVAAAAYAAJ:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST z JavaScriptu
Interfejs API Książek możesz wywoływać interfejs API REST z kodu JavaScript (nazywany też JSON-P), używając parametru zapytania callback
i funkcji wywołania zwrotnego. Dzięki temu możesz pisać rozbudowane aplikacje, które wyświetlają dane Książek bez pisania kodu po stronie serwera.
Uwaga: metody uwierzytelnione można wywoływać, przekazując token OAuth 2.0 za pomocą parametru access_token
. Aby uzyskać token OAuth 2.0 do użycia z JavaScriptem, postępuj zgodnie z instrukcjami podanymi w artykule OAuth 2.0 dla aplikacji internetowych po stronie klienta. Na karcie „Dostęp do interfejsu API” w konsoli interfejsów API skonfiguruj identyfikator klienta dla aplikacji internetowych i korzystaj z tych danych logowania OAuth 2.0 podczas pobierania tokena.
Poniższy przykład przedstawia zastosowanie metody wyświetlania wyników wyszukiwania hasła „harry potter”:
<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>
Format danych
JSON
JSON (JavaScript Object Notation) jest popularnym formatem danych niezależnym od języka, który w prosty sposób prezentuje dowolne struktury danych. Więcej informacji znajdziesz na stronie json.org.