Pierwsze kroki

W tym dokumencie znajdziesz podstawowe informacje, które pomogą Ci korzystać z interfejsu Google Books API.

Wprowadzenie
Zanim zaczniesz
Informacje o interfejsie Books API
Styl dzwonienia
1. REST
Format danych
1. JSON

Wprowadzenie

Ten dokument jest przeznaczony dla deweloperów, którzy chcą tworzyć aplikacje, które mogą wchodzić w interakcje z interfejsem Google Books API. Książki Google mają na celu zdigitalizowanie wszystkich książek na świecie. Za pomocą interfejsu Google Books API możesz wyszukiwać treści, organizować osobistą bibliotekę uwierzytelnionego użytkownika i ją modyfikować.

Zanim rozpoczniesz

Uzyskiwanie konta Google

Do celów testowych potrzebujesz konta Google. Jeśli masz już konto testowe, możesz przejść do interfejsu użytkownika Książek Google, aby skonfigurować, edytować lub wyświetlić dane testowe.

Zapoznaj się z Książkami

Jeśli nie znasz pojęć związanych z Książkami Google, przed rozpoczęciem kodowania przeczytaj ten dokument i wypróbuj interfejs użytkownika. W tym dokumencie zakładamy, że znasz koncepcje programowania aplikacji internetowych oraz formaty 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.

W szczególności wszystkie operacje w sekcji „Moja biblioteka” w interfejsie Google Books API są uznawane za prywatne i wymagają uwierzytelniania oraz autoryzacji. Ponadto każdą operację, która modyfikuje dane Google Play Książek, może wykonać tylko użytkownik, który jest właścicielem tych danych.

Gdy aplikacja żąda danych publicznych, nie musi autoryzować żądania, ale musi dołączyć identyfikator, np. klucz interfejsu API.

Informacje o autoryzowaniu żądań i używaniu kluczy interfejsu API znajdziesz w sekcji Autoryzowanie żądań i identyfikowanie aplikacji w dokumencie Korzystanie z interfejsu API.

Informacje o interfejsie Books API

Pojęcia związane z Książkami

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

Tom: tom to dane o książce lub czasopiśmie, które są hostowane w Książkach Google. Jest to podstawowy zasób w interfejsie Books API. Wszystkie inne zasoby w tym interfejsie API zawierają wolumin lub go opisują.
Półka na książki: półka na książki to zbiór woluminów. Usługa Książki Google udostępnia każdemu użytkownikowi zestaw predefiniowanych półek na książki. Niektóre z nich są w pełni zarządzane przez użytkownika, inne są automatycznie wypełniane na podstawie jego aktywności, a jeszcze inne są mieszane. Użytkownicy mogą tworzyć, modyfikować i usuwać inne półki, które zawsze są wypełniane ręcznie. Półki mogą być ustawione przez użytkownika jako prywatne lub publiczne.
Uwaga: tworzenie i usuwanie półek, a także modyfikowanie ustawień prywatności półek jest obecnie możliwe tylko w witrynie Książki Google.
Opinia: opinia o książce to połączenie oceny w postaci gwiazdek lub tekstu. Użytkownik może przesłać 1 opinię na tom. Opinie są też dostępne ze źródeł zewnętrznych i są odpowiednio przypisywane.
Pozycja czytania: pozycja czytania wskazuje ostatnią pozycję czytania w tomie dla użytkownika. Każdy użytkownik może mieć tylko jedną pozycję czytania w przypadku każdego tomu. Jeśli użytkownik nie otworzył wcześniej tego woluminu, pozycja czytania nie istnieje. Miejsce czytania może przechowywać szczegółowe informacje o pozycji, aż do rozdzielczości słowa. Te informacje są zawsze prywatne dla użytkownika.

Model danych interfejsu Books API

Zasób to pojedynczy obiekt danych z unikalnym identyfikatorem. Interfejs Books API działa na 2 typach zasobów, które są oparte na opisanych powyżej koncepcjach:

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

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

Volume Collection: Kolekcja woluminów to zbiór wszystkich zasobów woluminów zarządzanych przez Książki Google. Nie możesz więc wyświetlić wszystkich zasobów dotyczących dużych ilości, ale możesz wyświetlić wszystkie tomy pasujące do zestawu wyszukiwanych haseł.
Kolekcja półek na książki: Kolekcja półek na książki zawiera wszystkie zasoby półek na książki zarządzane przez Książki Google. Półki muszą zawsze być powiązane z biblioteką konkretnego użytkownika. Półki mogą zawierać zero lub więcej woluminów.

Operacje interfejsu Books API

W przypadku kolekcji i zasobów w interfejsie Books API możesz wywoływać 5 różnych metod, jak opisano w tabeli poniżej.

Operacja	Opis	Mapowania REST HTTP
list	Wyświetla określony podzbiór zasobów w kolekcji.	`GET` w identyfikatorze URI kolekcji.
wstaw	Wstawia nowy zasób do kolekcji (tworzy nowy zasób).	`POST` w przypadku URI kolekcji, gdzie przekazujesz dane nowego zasobu.
get	Pobiera określony zasób.	`GET` w identyfikatorze URI zasobu.
aktualizować	Aktualizuje określony 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, w którym przekazujesz dane zasobu do usunięcia.

Operacje obsługiwane w przypadku różnych typów zasobów podsumowaliśmy w tabeli poniżej. Operacje dotyczące prywatnych danych użytkownika są nazywane operacjami „Moja biblioteka” i wszystkie wymagają uwierzytelniania.

Typ zasobu	Obsługiwane operacje
	list	wstaw	pobierz	update	usuń
Tomy	tak*		tak
Półki na książki	tak*	tak, UWIERZYTELNIONY	tak*	tak, UWIERZYTELNIONY	tak, UWIERZYTELNIONY
Pozycje czytania		tak, UWIERZYTELNIONY	tak, UWIERZYTELNIONY	tak, UWIERZYTELNIONY	tak, UWIERZYTELNIONY

*Dostępne są zarówno autoryzowane, jak i nieautoryzowane wersje tych operacji. Autoryzowane żądania działają na prywatnych danych użytkownika w sekcji „Moja biblioteka”, a nieautoryzowane żądania działają tylko na danych publicznych.

Style połączeń

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

Bezpośrednie korzystanie z REST
Korzystanie z REST w JavaScript (bez konieczności pisania kodu po stronie serwera)

REST

REST to styl architektury oprogramowania, który zapewnia wygodne i spójne podejście do wysyłania żądań dotyczących danych i ich modyfikowania.

REST to skrót od „Representational State Transfer”. 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 RESTful zasoby są przechowywane w magazynie danych. Klient wysyła żądanie, aby serwer wykonał określone działanie (np. utworzył, pobrał, zaktualizował lub usunął zasób), a serwer wykonuje to działanie i wysyła odpowiedź, często w formie reprezentacji określonego zasobu.

W interfejsach API REST Google klient określa działanie za pomocą czasownika HTTP, takiego jak POST, GET, PUT lub DELETE. Określa zasób za pomocą unikalnego globalnie identyfikatora URI w tej postaci:

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

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

W dokumentacji standardów HTTP 1.1 znajdziesz definicje metod, w tym specyfikacje metod GET, POST, PUT i DELETE.

REST w interfejsie Books API

Obsługiwane operacje Książek są bezpośrednio powiązane z czasownikami REST HTTP, jak opisano w sekcji Operacje interfejsu Books API.

Identyfikatory URI interfejsu Books API mają te formaty:

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

gdzie resourceID to identyfikator woluminu lub zasobu półki, a parameters to parametry, które mają być zastosowane w zapytaniu. Więcej informacji znajdziesz w omówieniu parametrów zapytania.

Format resourceID rozszerzeń ścieżki pozwala określić zasób, na którym obecnie pracujesz, np.:

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 symbolem mylibrary w identyfikatorze URI dotyczą tylko danych z prywatnej biblioteki aktualnie uwierzytelnionego użytkownika. Pełny zestaw identyfikatorów URI używanych w przypadku każdej obsługiwanej operacji w interfejsie API znajdziesz w dokumencie Dokumentacja interfejsu Books API.

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

Wyszukaj hasło „quilting”:

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ć za pomocą REST z JavaScriptu (zwanego też JSON-P) przy użyciu parametru zapytania callback i funkcji wywołania zwrotnego. Dzięki temu możesz tworzyć rozbudowane aplikacje, które wyświetlają dane z Usługi Książki Google, bez 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 w JavaScript, postępuj zgodnie z instrukcjami podanymi w artykule OAuth 2.0 w przypadku internetowych aplikacji po stronie klienta. Na karcie „Dostęp do interfejsu API” w konsoli interfejsów API skonfiguruj identyfikator klienta dla aplikacji internetowych i użyj tych danych logowania OAuth 2.0 podczas pobierania tokena.

W tym przykładzie używamy tej metody do wyświetlania wyników wyszukiwania dla zapytania „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 zapewnia prostą tekstową reprezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Pierwsze kroki Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.