Ta strona została przetłumaczona przez Cloud Translation API.

Pierwsze kroki

Ten dokument zawiera szczegółową wiedzę specjalistyczną, która jest niezbędna do korzystania z interfejsu API Książek Google.

Wprowadzenie
Zanim zaczniesz
Tło interfejsu Books API
Styl połączenia
1. REST
Format danych
1. JSON

Wstęp

Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje współpracujące z interfejsem API Książek Google. Celem Książek Google jest digitalizacja książek z całego świata. Przy użyciu interfejsu Google Books API możesz wyszukiwać treści, porządkować osobistą bibliotekę uwierzytelnionego użytkownika oraz ją modyfikować.

Zanim rozpoczniesz

Załóż konto Google

Aby przeprowadzić test, musisz mieć konto Google. Jeśli masz już konto testowe, to wszystko. Możesz już korzystać z interfejsu użytkownika Książek Google, by konfigurować, edytować i wyświetlać dane testowe.

Poznaj Książki

Jeśli nie masz wiedzy o Książkach Google, przeczytaj ten dokument i wypróbuj różne funkcje interfejsu użytkownika, zanim zaczniesz pisać kod. Zakładamy w nim, że znasz pojęcia programowania stron internetowych i formaty danych z sieci.

Dowiedz się więcej o autoryzowaniu żądań i identyfikowaniu aplikacji

Gdy Twoja aplikacja żąda prywatnych danych, użytkownik mający do nich dostęp musi autoryzować takie żądanie.

W szczególności wszystkie operacje w sekcji „Moja biblioteka” w interfejsie API Książek Google są uznawane za prywatne i wymagają uwierzytelnienia oraz autoryzacji. Poza tym każdą operację modyfikują dane Książek Google może wykonać tylko użytkownik, do którego należą te dane.

Gdy aplikacja żąda danych publicznych, nie wymaga autoryzacji, ale musi mu towarzyszyć identyfikator, np. klucz interfejsu API.

Informacje o autoryzowaniu żądań i używaniu kluczy interfejsu API znajdziesz w artykule Autoryzacja żądań i identyfikowanie aplikacji w dokumencie „Korzystanie z interfejsu API”.

Tło interfejsu API Książek

Pojęcia związane z książkami

Książki Google opierają się na 4 podstawowych zasadach:

Wolumin: wolumin reprezentuje dane o książce lub czasopiśmie przechowywane w Książkach Google. Jest to główny zasób w interfejsie Books API. Wszystkie inne zasoby w tym interfejsie API zawierają wolumin lub mają do niego adnotacje.
Bookshelf to zbiór tomów. W Książkach Google jest dostępny zestaw wstępnie zdefiniowanych półek na książki dla każdego użytkownika. Niektóre z nich są w pełni zarządzane przez użytkownika. Niektóre są wypełniane automatycznie na podstawie jego aktywności, a część miesza się z innymi. Użytkownicy mogą tworzyć, modyfikować i usuwać inne półki na książki, które zawsze są wypełniane ręcznie. Użytkownicy mogą ustawić półki na książki jako prywatne lub publiczne.
Uwaga: obecnie możesz tworzyć i usuwać półki na książki oraz zmieniać ustawienia prywatności tych półek tylko w witrynie Książki Google.
Opinia: recenzja tomu składa się z oceny oraz tekstu i oceny. Użytkownik może przesłać 1 recenzję w każdym tomie. Opinie są też dostępne ze źródeł zewnętrznych i są odpowiednio przypisywane.
Pozycja czytania: wskazuje ostatnią pozycję czytania w wolumencie przez użytkownika. Użytkownik może mieć tylko 1 miejsce czytania na wolumin. Jeśli użytkownik nie otwierał wcześniej tego woluminu, oznacza to, że miejsce odczytu nie istnieje. Miejsce czytania może przechowywać szczegółowe informacje o pozycji z dokładnością do rozdzielczości danego słowa. Użytkownik zawsze ma do nich dostęp.

Model danych interfejsu Books API

Zasób to pojedynczy element danych z unikalnym identyfikatorem. Interfejs Books API działa na 2 typach zasobów zgodnie z koncepcjami opisanymi powyżej:

Zasób woluminu: reprezentuje wolumin.
Zasób półki: reprezentuje jedną półkę dla konkretnego użytkownika.

Model danych interfejsu Books API opiera się na grupach zasobów nazywanych kolekcjami:

Zbieranie woluminów: Kolekcja tomów to zbiór wszystkich tomów zarządzanych przez Książki Google. W związku z tym nie można wyświetlić wszystkich zasobów woluminu, ale można wyświetlić wszystkie woluminy pasujące do zestawu wyszukiwanych haseł.
Kolekcja półek: Kolekcja półek na książki składa się ze wszystkich zasobów na półkę zarządzanych przez Książki Google. Odwołania do półek na książki muszą zawsze występować w kontekście biblioteki konkretnego użytkownika. Półki na książki mogą zawierać zero lub więcej tomów.

Operacje interfejsu Books API

W interfejsie Books API możesz wywoływać 5 różnych metod na kolekcjach i zasobach zgodnie z opisem w tabeli poniżej.

Operacja	Opis	Mapowania HTTP REST
list	Wyświetla określony podzbiór zasobów w zbiorze.	`GET` w identyfikatorze URI kolekcji.
wstaw	Wstawia nowy zasób do kolekcji (tworzenie nowego zasobu).	`POST` w identyfikatorze URI kolekcji, w którym przekazujesz dane dla nowego zasobu.
pobierz	Pobiera określony zasób.	`GET` w identyfikatorze URI zasobu.
zaktualizuj	Aktualizuje określony zasób.	`PUT` w identyfikatorze URI zasobu, gdzie przekazujesz dane dla zaktualizowanego zasobu.
usuń	Usuwa określony zasób.	`DELETE` w identyfikatorze URI zasobu, gdzie przekazujesz dane do usunięcia.

W tabeli poniżej znajdziesz podsumowanie operacji obsługiwanych w przypadku różnych typów zasobów. Operacje dotyczące prywatnych danych użytkownika są nazywane operacjami „Mojej biblioteki” i wymagają uwierzytelniania.

Typ zasobu	Obsługiwane operacje
	lista	wstaw	pobierz	zaktualizuj	usuń
Woluminy	tak*		tak
Półki na książki	tak*	tak, UWIERZYTELNIONE	tak*	tak, UWIERZYTELNIONE	tak, UWIERZYTELNIONE
Pozycje czytania		tak, UWIERZYTELNIONE	tak, UWIERZYTELNIONE	tak, UWIERZYTELNIONE	tak, UWIERZYTELNIONE

*Dostępne są zarówno wersje UWIERZYTELnione, jak i nieuwierzytelnione, w przypadku których uwierzytelnione żądania działają na prywatnych danych użytkownika w „Mojej bibliotece”, a nieuwierzytelnione żądania działają wyłącznie na danych publicznych.

Style połączeń

Interfejs API można wywołać na kilka sposobów:

Bezpośrednie korzystanie z REST
Używanie REST z JavaScript (kod po stronie serwera nie jest wymagany).

REST

REST to styl architektury oprogramowania, który zapewnia wygodne i spójne podejście do żądania i modyfikowania danych.

Skrót REST to reprezentatywny transfer stanowy. W kontekście interfejsów API Google oznacza to używanie czasowników HTTP do pobierania i modyfikowania reprezentacji danych przechowywanych przez Google.

W systemie REST zasoby są przechowywane w magazynie danych. Klient wysyła żądanie, aby serwer wykonał określone działanie (np. utworzenie, pobranie, zaktualizowanie lub usunięcie zasobu), a serwer wykonuje działanie i wysyła odpowiedź, często w formie reprezentacji określonego zasobu.

W interfejsach API typu REST firmy Google klient określa działanie za pomocą czasownika HTTP, takiego jak POST, GET, PUT lub DELETE. Wskazuje zasób za pomocą globalnie unikalnego identyfikatora URI o następującej postaci:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Ponieważ wszystkie zasoby interfejsu API mają unikalne identyfikatory URI dostępne przez HTTP, interfejs REST umożliwia buforowanie danych i jest zoptymalizowany pod kątem pracy z rozproszoną infrastrukturą sieciową.

Definicje metod znajdziesz w dokumentacji standardów HTTP 1.1. Obejmują one specyfikacje GET, POST, PUT i DELETE.

REST w interfejsie Books API

Obsługiwane operacje w Książkach są mapowane bezpośrednio na czasowniki HTTP REST zgodnie z opisem w sekcji Operacje interfejsu Books API.

Identyfikatory URI interfejsu Books API mają następujący format:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

gdzie resourceID to identyfikator woluminu lub zasobu na półce, a parameters to parametry stosowane do zapytania. Szczegółowe informacje znajdziesz w dokumentacji parametrów zapytania.

Format rozszerzeń ścieżek resourceID 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 mylibrary w identyfikatorze URI dotyczą tylko danych biblioteki prywatnej obecnie uwierzytelnionego użytkownika. Pełny zestaw identyfikatorów URI używanych w przypadku każdej obsługiwanej operacji w interfejsie API został podsumowany w dokumencie Books API Reference.

Oto kilka przykładów, jak to działa w interfejsie Books API.

Wyszukaj hasło na temat pikowania:

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 Books API można wywołać za pomocą protokołu REST w języku JavaScript (nazywanym też JSON-P) za pomocą parametru zapytania callback i funkcji wywołania zwrotnego. Umożliwia to pisanie zaawansowanych aplikacji wyświetlających dane z Książek bez konieczności pisania kodu po stronie serwera.

Uwaga: możesz wywoływać uwierzytelnione metody, przekazując token OAuth 2.0 za pomocą parametru access_token. Aby uzyskać token OAuth 2.0 do użycia z JavaScriptem, wykonaj instrukcje opisane w artykule OAuth 2.0 dla aplikacji internetowych po stronie klienta. Na karcie „Dostęp do interfejsów API” w konsoli interfejsów API skonfiguruj identyfikator klienta dla aplikacji internetowych, który będzie używany podczas uzyskiwania tokena.

Poniższy przykład pokazuje zastosowanie tej metody do 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) to popularny, niezależny od języka format danych, który w prosty sposób przedstawia dowolne struktury danych w formie tekstowej. Więcej informacji znajdziesz na stronie json.org.