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

Pierwsze kroki

Ten dokument zawiera szczegółową wiedzę potrzebną do korzystania z interfejsu Google Books API.

Wprowadzenie
Zanim zaczniesz
Tło interfejsu API Książek
Styl rozmowy
1. REST
Format danych
1. JSON

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.

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.