Spis treści
Wstęp
Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje obsługujące interfejs API Książek. Misją Książek Google jest digitalizacja treści książek z całego świata i ułatwiania ich wyszukiwania w internecie. Interfejs Books API to sposób na wyszukiwanie i otwieranie tych treści, a także na tworzenie i wyświetlanie personalizacji dotyczących tych treści.
Jeśli nie masz wiedzy o Książkach Google, zanim zaczniesz pisać kod, przeczytaj Pierwsze kroki.
Autoryzacja żądań i identyfikowanie aplikacji
Każde żądanie wysyłane przez aplikację do interfejsu Books API musi identyfikować Twoją aplikację w Google. Są 2 sposoby identyfikowania aplikacji: za pomocą tokena OAuth 2.0 (który również autoryzuje żądanie) lub za pomocą klucza interfejsu API aplikacji. Oto jak zdecydować, której z tych opcji użyć:
- Jeśli żądanie wymaga autoryzacji (np. dostępu do prywatnych danych danej osoby), aplikacja musi dostarczyć wraz z nim token OAuth 2.0. Aplikacja może też dostarczać klucz interfejsu API, ale nie musi.
- Jeśli żądanie nie wymaga autoryzacji (np. danych publicznych), aplikacja musi dostarczyć klucz interfejsu API lub token OAuth 2.0 albo obie te opcje – która opcja jest dla Ciebie najwygodniejsza.
Informacje o protokołach autoryzacji
Twoja aplikacja musi autoryzować żądania za pomocą protokołu OAuth 2.0. Inne protokoły nie są obsługiwane. Jeśli aplikacja używa funkcji Zaloguj się przez Google, niektórymi aspektami autoryzacji nie musisz się zajmować.
Autoryzowanie żądań za pomocą protokołu OAuth 2.0
Żądania dotyczące niepublicznych danych użytkownika wysyłane do interfejsu Books API muszą być autoryzowane przez uwierzytelnionego użytkownika.
Szczegóły procesu autoryzacji z użyciem protokołu OAuth 2.0 różnią się nieznacznie w zależności od rodzaju projektowanej aplikacji. Do większości typów aplikacji ma zastosowanie ten ogólny proces:
- Gdy tworzysz aplikację, rejestrujesz ją, korzystając z konsoli interfejsów API Google. Następnie Google przekazuje informacje, które są potrzebne później, takie jak identyfikator klienta i tajny klucz klienta.
- Aktywuj interfejs Books API w konsoli interfejsów API Google. (jeśli interfejsu API nie ma na liście w konsoli, pomijasz ten krok).
- Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
- Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
- Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
- Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
- Jeśli Google uzna, że żądanie i token są prawidłowe, przesyła dane, o które prosisz.
Niektóre procesy obejmują dodatkowe kroki, takie jak wykorzystanie tokenów odświeżania do uzyskania nowych tokenów dostępu. Szczegółowe informacje o procesach obowiązujących w przypadku różnych typów aplikacji znajdziesz w dokumencie Google na temat protokołu OAuth 2.0.
Oto informacje o zakresie protokołu OAuth 2.0 dla interfejsu Books API:
https://www.googleapis.com/auth/books
Aby poprosić o dostęp przy użyciu protokołu OAuth 2.0, aplikacja potrzebuje danych z zakresu oraz informacji przekazywanych przez Google po zarejestrowaniu aplikacji (takich jak identyfikator klienta i tajny klucz klienta).
Wskazówka: biblioteki klienta interfejsów API Google mogą wykonać niektóre procesy autoryzacji za Ciebie. Są dostępne dla różnych języków programowania. Więcej szczegółów znajdziesz na stronie z bibliotekami i próbkami.
Uzyskiwanie i używanie klucza interfejsu API
Żądania wysyłane do interfejsu Books API dotyczące danych publicznych muszą mieć identyfikator, którym może być klucz interfejsu API lub token dostępu.
Aby uzyskać klucz interfejsu API:
- Otwórz stronę Dane logowania w konsoli interfejsów API.
-
Ten interfejs API obsługuje 2 typy danych logowania.
Utwórz dane logowania odpowiednie do Twojego projektu:
-
OAuth 2.0: za każdym razem, gdy aplikacja żąda prywatnych danych użytkownika, musi wraz z nimi wysyłać token OAuth 2.0. Twoja aplikacja najpierw wysyła identyfikator klienta, a być może tajny klucz klienta, aby uzyskać token. Dane logowania OAuth 2.0 możesz generować dla aplikacji internetowych, kont usługi i zainstalowanych aplikacji.
Więcej informacji znajdziesz w dokumentacji protokołu OAuth 2.0.
-
Klucze interfejsu API: żądanie, które nie dostarcza tokena OAuth 2.0, musi wysłać klucz interfejsu API. Klucz identyfikuje projekt i zapewnia dostęp do interfejsu API, limity oraz raporty.
Interfejs API obsługuje kilka typów ograniczeń kluczy interfejsu API. Jeśli klucz interfejsu API, którego potrzebujesz, jeszcze nie istnieje, utwórz klucz interfejsu API w konsoli, klikając Utwórz dane logowania > Klucz interfejsu API. Możesz ograniczyć użycie klucza przed użyciem w środowisku produkcyjnym. W tym celu kliknij Ogranicz klucz i wybierz jedno z ograniczeń.
-
Aby zabezpieczyć klucze interfejsu API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.
Gdy uzyskasz klucz interfejsu API, Twoja aplikacja może dołączać parametr zapytania key=yourAPIKey do wszystkich adresów URL żądań.
Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.
Identyfikatory Książek Google
Przy użyciu niektórych wywołań metod interfejsu API musisz określić pola identyfikatorów. W Książkach Google używane są 3 rodzaje dokumentów tożsamości:
- Identyfikatory tomów – unikalne ciągi znaków przypisane do każdego tomu, o którym znają książki w Książkach Google. Przykład identyfikatora woluminu to
_LettPDhwR0C. Identyfikator woluminu możesz uzyskać za pomocą interfejsu API, wysyłając żądanie zwracające zasób woluminu. Znajdziesz go w poluid. - Identyfikatory półek na książki – wartości liczbowe podane półce na książki w bibliotece użytkownika. Każdy użytkownik ma dostęp do wstępnie zdefiniowanych półek o tych identyfikatorach:
- Ulubione: 0
- Kupione: 1
- Do przeczytania: 2
- Do przeczytania: 3
- Przeczytano: 4
- Sprawdzono: 5
- Ostatnio wyświetlane: 6
- Moje e-booki: 7
- Książki dla Ciebie: 8 Jeśli nie mamy żadnych rekomendacji dla użytkownika, ta półka nie istnieje.
id. - Identyfikatory użytkowników – niepowtarzalne wartości liczbowe przypisywane każdemu użytkownikowi. Te wartości nie muszą być takie same jak wartości identyfikatora używane w innych usługach Google. Obecnie jedynym sposobem na pobranie identyfikatora użytkownika jest wyodrębnienie go z linku SelfLink w zasobie półki na książki pobranego za pomocą uwierzytelnionego żądania. Użytkownicy mogą również uzyskać własny identyfikator w witrynie Książki. Użytkownik nie może uzyskać identyfikatora innego użytkownika za pomocą interfejsu API ani w witrynie Książek. Musi on udostępnić te informacje w sposób jednoznaczny, na przykład w e-mailu.
Identyfikatory w witrynie Książek Google
Identyfikatory, których używasz w interfejsie Books API, to te same identyfikatory, których używasz w witrynie Książki Google.
- Identyfikator woluminu
Gdy wyświetlasz w witrynie konkretny tom, jego identyfikator znajdziesz w parametrze adresu URL
id. Oto przykład:https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- Identyfikator półki na książki
Gdy wyświetlasz w witrynie konkretną półkę na książki, jej identyfikator znajdziesz w parametrze adresu URL
as_coll. Oto przykład:https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
- Identyfikator użytkownika
Gdy przeglądasz bibliotekę na tej stronie, identyfikator użytkownika możesz znaleźć w parametrze adresu URL
uid. Oto przykład:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Ustawianie lokalizacji użytkownika
Książki Google przestrzegają praw autorskich, umów oraz innych ograniczeń prawnych związanych z lokalizacją użytkownika. W związku z tym niektórzy użytkownicy mogą nie mieć dostępu do treści książek z określonych krajów. Na przykład niektóre książki można „podglądać” tylko w Stanach Zjednoczonych. Takie linki do podglądu są pomijane w przypadku użytkowników z innych krajów. W związku z tym wyniki interfejsu API są ograniczone w zależności od adresu IP serwera lub aplikacji klienckiej.
Praca z woluminami
Wyszukuję
Możesz przeprowadzić wyszukiwanie woluminów, wysyłając żądanie HTTP GET na ten identyfikator URI:
https://www.googleapis.com/books/v1/volumes?q=search+terms
To żądanie zawiera jeden wymagany parametr:
q– wyszukaj woluminy zawierające ten ciąg tekstowy. W wyszukiwanych hasłach możesz określić specjalne słowa kluczowe, które będą służyć do wyszukiwania w konkretnych polach, na przykład:intitle:Zwraca wyniki, w przypadku których w tytule znajduje się tekst występujący po tym słowie kluczowym.inauthor:Zwraca wyniki, w których przypadku występuje tekst występujący po tym słowie kluczowym.inpublisher:Zwraca wyniki, w przypadku których znaleziono tekst występujący po tym słowie kluczowym.subject:Zwraca wyniki, w których tekst występujący po tym słowie kluczowym znajduje się na liście kategorii woluminu.isbn:Zwraca wyniki, w których tekst występujący po słowie kluczowym jest numerem ISBN.lccn:Zwraca wyniki, w których tekst występujący po tym słowie kluczowym to numer Biblioteki Kongresu Stanów Zjednoczonych.oclc:Zwraca wyniki, w których tekst po słowie kluczowym to numer Online Computer Library Center.
Prośba
Oto przykład wyszukiwania utworu Daniela Keyesa, „Flowers for Algernon”:
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Uwaga: wyszukiwanie nie wymaga uwierzytelniania, więc nie musisz dostarczać nagłówka HTTP Authorization w żądaniu GET. Jeśli jednak wywołanie jest wykonywane z użyciem uwierzytelniania, każdy wolumin będzie zawierał informacje dotyczące użytkownika, takie jak stan zakupu.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi przesyła kod stanu HTTP 200 OK i wyświetli wynik woluminu:
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "_ojXNuzgHRcC",
"etag": "OTD2tB19qn4",
"selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Vijaya Khisty Bodach"
],
...
},
{
"kind": "books#volume",
"id": "RJxWIQOvoZUC",
"etag": "NsxMT6kCCVs",
"selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Gail Saunders-Smith"
],
...
},
{
"kind": "books#volume",
"id": "zaRoX10_UsMC",
"etag": "pm1sLMgKfMA",
"selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Paul McEvoy"
],
...
},
"totalItems": 3
}
Opcjonalne parametry zapytania
Oprócz standardowych parametrów zapytania podczas wyszukiwania woluminów możesz używać podanych niżej parametrów zapytania.
Format pobierania
Za pomocą parametru download możesz ograniczyć zwracane wyniki do woluminów, które mają dostępny format epub, ustawiając na wartość epub.
Oto przykładowe wyszukiwanie książek z dostępnym plikiem EPUB do pobrania:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtrowanie
Aby jeszcze bardziej ograniczyć zwracane wyniki, możesz użyć parametru filter, ustawiając go na jedną z tych wartości:
partial– zwraca wyniki, w których można wyświetlić podgląd co najmniej części tekstu.full– zwraca tylko wyniki, w których cały tekst jest widoczny.free-ebooks– zwraca tylko wyniki, które są bezpłatnymi e-bookami Google.paid-ebooks– zwraca tylko wyniki zawierające e-booki Google z ceną.ebooks– zwraca tylko płatne lub bezpłatne e-booki Google. Przykładami treści innych niż e-booki mogą być czasopisma lub treści wydawcy dostępne w ograniczonej wersji przedpremierowej.
Ten przykład ogranicza wyniki wyszukiwania do tych dostępnych jako bezpłatne e-booki:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Podział na strony
Listę woluminów możesz podzielić na strony, określając 2 wartości w parametrach żądania:
startIndex– pozycja w kolekcji, od której ma się rozpocząć. Indeks pierwszego elementu wynosi 0.maxResults– maksymalna liczba wyników do zwrócenia. Wartość domyślna to 10, a maksymalna dozwolona to 40.
Rodzaj nadruku
Za pomocą parametru printType możesz ograniczyć zwracane wyniki do konkretnego typu materiałów drukowanych lub publikacji, ustawiając go na jedną z tych wartości:
all– brak ograniczeń ze względu na typ wydruku (domyślnie).books– zwraca tylko wyniki, które są książkami.magazines– zwraca wyniki, które są czasopismami.
Ten przykład ogranicza wyniki wyszukiwania do czasopism:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Odwzorowanie
Parametru projection możesz używać z jedną z tych wartości, aby określić wstępnie zdefiniowany zestaw pól liczby do zwrócenia:
full– zwraca wszystkie pola woluminu.lite– zwraca tylko określone pola. Aby dowiedzieć się, które pola uwzględnione, sprawdź opisy pól oznaczone podwójną gwiazdkami w dokumentacji woluminu.
Ten przykład zwraca wyniki wyszukiwania z ograniczoną ilością informacji:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Sortowanie
Domyślnie żądanie wyszukiwania woluminów zwraca wyniki maxResults, gdzie maxResults to parametr używany do podziału na strony (powyżej) uporządkowane według trafności w stosunku do wyszukiwanych haseł.
Możesz zmienić kolejność, ustawiając parametr orderBy na jedną z tych wartości:
relevance– zwraca wyniki w kolejności według trafności wyszukiwanych haseł (jest to ustawienie domyślne).newest– zwraca wyniki w kolejności od najnowszych do najstarszych.
Ten przykład pokazuje wyniki według daty publikacji (od najnowszych do najstarszych):
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Pobieram określony wolumin
Informacje o konkretnym woluminie można pobrać, wysyłając żądanie HTTP GET do identyfikatora URI zasobu woluminu:
https://www.googleapis.com/books/v1/volumes/volumeId
Zastąp parametr ścieżki volumeId identyfikatorem woluminu do pobrania. Więcej informacji o identyfikatorach tomów znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład żądania GET, które pobiera 1 tom:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Uwaga: pobieranie informacji o woluminach nie wymaga uwierzytelniania, więc nie musisz dołączać nagłówka HTTP Authorization w żądaniu GET. Jeśli jednak wywołanie zostanie wykonane w celu uwierzytelnienia, wolumin będzie zawierał informacje dotyczące użytkownika, takie jak stan zakupu.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi przesyła kod stanu HTTP 200 OK i żądanie zasobu woluminu:
200 OK
{
"kind": "books#volume",
"id": "zyTCAlFPjgYC",
"etag": "f0zKg75Mx/I",
"selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
"volumeInfo": {
"title": "The Google story",
"authors": [
"David A. Vise",
"Mark Malseed"
],
"publisher": "Random House Digital, Inc.",
"publishedDate": "2005-11-15",
"description": "\"Here is the story behind one of the most remarkable Internet
successes of our time. Based on scrupulous research and extraordinary access
to Google, ...",
"industryIdentifiers": [
{
"type": "ISBN_10",
"identifier": "055380457X"
},
{
"type": "ISBN_13",
"identifier": "9780553804577"
}
],
"pageCount": 207,
"dimensions": {
"height": "24.00 cm",
"width": "16.03 cm",
"thickness": "2.74 cm"
},
"printType": "BOOK",
"mainCategory": "Business & Economics / Entrepreneurship",
"categories": [
"Browsers (Computer programs)",
...
],
"averageRating": 3.5,
"ratingsCount": 136,
"contentVersion": "1.1.0.0.preview.2",
"imageLinks": {
"smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
"thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
"small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
"medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
"large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
"extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
},
"language": "en",
"infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
"canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
},
"saleInfo": {
"country": "US",
"saleability": "FOR_SALE",
"isEbook": true,
"listPrice": {
"amount": 11.99,
"currencyCode": "USD"
},
"retailPrice": {
"amount": 11.99,
"currencyCode": "USD"
},
"buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
},
"accessInfo": {
"country": "US",
"viewability": "PARTIAL",
"embeddable": true,
"publicDomain": false,
"textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
"epub": {
"isAvailable": true,
"acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
},
"pdf": {
"isAvailable": false
},
"accessViewStatus": "SAMPLE"
}
}
Informacje o dostępie
Sekcja accessInfo służy przede wszystkim do określania, jakie funkcje są dostępne w przypadku e-booka. epub to e-book w formacie tekstu ciągłego. Sekcja epub będzie miała właściwość isAvailable wskazującą, czy dany typ e-booka jest dostępny.
Jeśli dostępna jest próbka książki lub użytkownik może ją przeczytać, ponieważ jej zakupiła lub znajduje się w domenie publicznej użytkownika w jej lokalizacji, będzie zawierał link do pobrania. pdf w przypadku Książek Google oznacza zeskanowaną wersję e-booka z podobnymi informacjami, takimi jak to, czy jest dostępny, i link do pobrania. Google zaleca korzystanie z plików epub na czytnikach e-booków i smartfonach, ponieważ zeskanowane strony mogą być trudne do odczytania na tych urządzeniach.
Jeśli nie ma sekcji accessInfo, wolumin nie jest dostępny jako e-book Google.
Opcjonalne parametry zapytania
Oprócz standardowych parametrów zapytania możesz podczas pobierania konkretnego woluminu użyć poniższego parametru zapytania.
Odwzorowanie
Parametru projection możesz używać z jedną z tych wartości, aby określić wstępnie zdefiniowany zestaw pól liczby do zwrócenia:
full– zwraca wszystkie pola woluminu.lite– zwraca tylko określone pola. Aby dowiedzieć się, które pola uwzględnione, sprawdź opisy pól oznaczone podwójną gwiazdkami w dokumentacji woluminu.
Ten przykład zwraca ograniczone informacje o pojedynczym woluminie:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Praca z półkami na książki
Pobieranie listy publicznych półek na książki użytkownika
Możesz pobrać listę publicznych półek na książki użytkownika, wysyłając żądanie HTTP GET do identyfikatora URI w następującym formacie:
https://www.googleapis.com/books/v1/users/userId/bookshelves
Zastąp parametr ścieżki userId identyfikatorem użytkownika, którego półki na książki chcesz pobrać. Więcej informacji o identyfikatorach użytkowników znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Ponieważ użytkownik nie musi być uwierzytelniony, aby uzyskać informacje o półkach publicznych, nie musisz w żądaniu GET wysyłać nagłówka HTTP Authorization.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowie, przesyłając kod stanu HTTP 200 OK i listę półek na książki:
200 OK
{
"kind": "books#bookshelves",
"items": [
{
...
},
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"description": "",
"access": "PUBLIC",
"updated": "2011-02-02T20:34:20.146Z",
"created": "2011-02-02T20:34:20.146Z",
"volumeCount": 2,
"volumesLastUpdated": "2011-02-02T20:34:20.110Z"
},
...
]
}
Opcjonalne parametry zapytania
Podczas pobierania listy publicznych półek na książki użytkownika możesz użyć standardowych parametrów zapytania.
Pobieranie konkretnej publicznej półki na książki
Możesz pobrać konkretną publiczną półkę, wysyłając do identyfikatora URI żądanie HTTP GET w następującym formacie:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Zastąp parametry ścieżki userId i shelf identyfikatorami określającymi użytkownika oraz półkę na książki, którą chcesz pobrać. Więcej informacji znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Ponieważ użytkownik nie musi być uwierzytelniony, aby uzyskać informacje o półkach publicznych, nie musisz w żądaniu GET wysyłać nagłówka HTTP Authorization.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowiada, przesyłając kod stanu HTTP 200 OK i zasób półki:
200 OK
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"description": "",
"access": "PUBLIC",
"updated": "2011-02-02T20:34:20.146Z",
"created": "2011-02-02T20:34:20.146Z",
"volumeCount": 2,
"volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}
Opcjonalne parametry zapytania
Podczas pobierania określonej publicznej półki możesz użyć standardowych parametrów zapytania.
Pobieranie listy tomów z publicznej półki
Możesz pobrać listę tomów z publicznej półki użytkownika, wysyłając żądanie HTTP GET z identyfikatorem URI w następującym formacie:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Prośba
Oto przykład:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Zastąp parametry ścieżki userId i shelf identyfikatorami określającymi użytkownika oraz półkę na książki, którą chcesz pobrać. Więcej informacji znajdziesz w sekcji Identyfikatory Książek Google.
Ponieważ użytkownik nie musi być uwierzytelniony, aby uzyskać informacje o półkach publicznych, nie musisz w żądaniu GET wysyłać nagłówka HTTP Authorization.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowie, przesyłając kod stanu HTTP 200 OK i listę półek na książki użytkownika:
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "AZ5J6B1-4BoC",
"etag": "kIzQA7IUObk",
"selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
"volumeInfo": {
"title": "The Girl Who Kicked the Hornet's Nest",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2010-05-25",
...
},
{
"kind": "books#volume",
"id": "UvK1Slvkz3MC",
"etag": "otKmdbRgdFQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
"volumeInfo": {
"title": "The Girl who Played with Fire",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2009-07-28",
...
},
{
"kind": "books#volume",
"id": "OBM3AAAAIAAJ",
"etag": "xb47kTr8HsQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
"volumeInfo": {
"title": "The Sign of Four",
"authors": [
"Sir Arthur Conan Doyle"
],
"publishedDate": "1890",
...
}
],
"totalItems": 3
}
Opcjonalne parametry zapytania
Oprócz standardowych parametrów zapytania możesz użyć poniższego parametru zapytania podczas pobierania listy tomów na publicznej półce.
Podział na strony
Listę woluminów możesz podzielić na strony, określając 2 wartości w parametrach żądania:
startIndex– pozycja w kolekcji, od której ma się rozpocząć. Indeks pierwszego elementu wynosi 0.maxResults– maksymalna liczba wyników do zwrócenia. Wartość domyślna to 10, a maksymalna dozwolona to 40.
Praca z półkami na książki w „Mojej bibliotece”
Wszystkie żądania w sekcji „Moja biblioteka” dotyczą danych uwierzytelnionego użytkownika.
Pobieranie listy półek na książki
Możesz pobrać listę wszystkich półek na książki uwierzytelnionego użytkownika, wysyłając do identyfikatora URI żądanie HTTP GET w następującym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Prośba
Oto przykład:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Uwaga: aby pobrać listę półek na książki z listy „Moja biblioteka”, użytkownik musi być uwierzytelniony. Dlatego wraz z żądaniem GET musisz podać nagłówek HTTP Authorization.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer wysyła w odpowiedzi kod stanu HTTP 200 OK i listę wszystkich półek na książki dla bieżącego uwierzytelnionego użytkownika:
200 OK
{
"kind": "books#bookshelves",
"items": [
{
"kind": "books#bookshelf",
"id": 0,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
"title": "Favorites",
"access": "PRIVATE",
"updated": "2011-04-22T04:03:15.416Z",
"created": "2011-04-22T04:03:15.416Z",
"volumeCount": 0,
"volumesLastUpdated": "2011-04-22T04:03:17.000Z"
},
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"access": "PUBLIC",
"updated": "2010-11-11T19:44:22.377Z",
"created": "2010-11-11T19:44:22.377Z",
"volumeCount": 1,
"volumesLastUpdated": "2010-11-11T19:44:22.341Z"
}
]
}
Opcjonalne parametry zapytania
Podczas pobierania listy półek na książki uwierzytelnionego użytkownika możesz użyć standardowych parametrów zapytania.
Pobieranie listy tomów z mojej półki
Aby pobrać listę tomów z półki uwierzytelnionego użytkownika, wyślij do identyfikatora URI żądanie HTTP GET w tym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Zastąp parametr ścieżki półki identyfikatorem półki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Uwaga: aby pobrać listę woluminów „Moja biblioteka”, użytkownik musi być uwierzytelniony. Dlatego wraz z żądaniem GET musisz podać nagłówek HTTP Authorization.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowie, przesyłając kod stanu HTTP 200 OK i listę woluminów półek:
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "AZ5J6B1-4BoC",
"etag": "kIzQA7IUObk",
"selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
"volumeInfo": {
"title": "The Girl Who Kicked the Hornet's Nest",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2010-05-25",
...
},
{
"kind": "books#volume",
"id": "UvK1Slvkz3MC",
"etag": "otKmdbRgdFQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
"volumeInfo": {
"title": "The Girl who Played with Fire",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2009-07-28",
...
},
{
"kind": "books#volume",
"id": "OBM3AAAAIAAJ",
"etag": "xb47kTr8HsQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
"volumeInfo": {
"title": "The Sign of Four",
"authors": [
"Sir Arthur Conan Doyle"
],
"publishedDate": "1890",
...
}
],
"totalItems": 3
}
Opcjonalne parametry zapytania
Oprócz standardowych parametrów zapytania możesz użyć poniższego parametru zapytania podczas pobierania listy tomów z jednej z półek na książki uwierzytelnionego użytkownika.
Podział na strony
Listę woluminów możesz podzielić na strony, określając 2 wartości w parametrach żądania:
startIndex– pozycja w kolekcji, od której ma się rozpocząć. Indeks pierwszego elementu wynosi 0.maxResults– maksymalna liczba wyników do zwrócenia. Wartością domyślną jest 10.
Dodaję tom do mojej półki na książki
Aby dodać wolumin do półki uwierzytelnionego użytkownika, wyślij do identyfikatora URI żądanie HTTP POST w tym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Zastąp parametr ścieżki półki identyfikatorem półki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie zawiera jeden wymagany parametr zapytania:
volumeId– identyfikator woluminu. Więcej informacji o identyfikatorach woluminów znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład dodania etykiety „Kwiaty dla Algernon” do półki „Ulubione”:
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Uwaga: aby zmodyfikować półkę na książki, użytkownik musi być uwierzytelniony, dlatego wraz z żądaniem POST musisz dostarczyć nagłówek HTTP Authorization. W przypadku tego parametru POST nie są jednak wymagane żadne dane.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowie, przesyłając kod stanu HTTP 204 No Content.
Opcjonalne parametry zapytania
Podczas dodawania woluminu do jednej z półek na książki uwierzytelnionego użytkownika możesz użyć standardowych parametrów zapytania.
Usuwanie tomu z półki
Aby usunąć wolumin z półki uwierzytelnionego użytkownika, wyślij żądanie HTTP POST do identyfikatora URI w tym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Zastąp parametr ścieżki półki identyfikatorem półki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie zawiera jeden wymagany parametr zapytania:
volumeId– identyfikator woluminu. Więcej informacji o identyfikatorach woluminów znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład usunięcia napisu „Kwiaty dla Algernon” z półki „Ulubione”:
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Uwaga: aby zmodyfikować półkę na książki, użytkownik musi być uwierzytelniony, dlatego wraz z żądaniem POST musisz dostarczyć nagłówek HTTP Authorization. W przypadku tego parametru POST nie są jednak wymagane żadne dane.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowie kodem stanu 204 No Content.
Opcjonalne parametry zapytania
Podczas usuwania woluminu z jednej z półek na książki uwierzytelnionego użytkownika możesz użyć standardowych parametrów zapytania.
Usuwanie wszystkich tomów z półki
Aby usunąć wszystkie woluminy z półki uwierzytelnionego użytkownika, wyślij żądanie HTTP POST do identyfikatora URI w następującym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Zastąp parametr ścieżki półki identyfikatorem półki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Prośba
Oto przykład czyszczenia półki „Ulubione”:
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Uwaga: aby zmodyfikować półkę na książki, użytkownik musi być uwierzytelniony, dlatego wraz z żądaniem POST musisz dostarczyć nagłówek HTTP Authorization. W przypadku tego parametru POST nie są jednak wymagane żadne dane.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowie kodem stanu 204 No Content.
Opcjonalne parametry zapytania
Podczas czyszczenia wszystkich woluminów z jednej z półek na książki uwierzytelnionego użytkownika możesz użyć standardowych parametrów zapytania.
Dokumentacja parametrów zapytania
W tej sekcji podsumowaliśmy parametry zapytania, których możesz używać w interfejsie Books API.Wszystkie wartości parametrów muszą być zakodowane na potrzeby adresu URL.
Standardowe parametry zapytania
Parametry zapytania, które mają zastosowanie do wszystkich operacji interfejsu Books API, są wymienione w sekcji Parametry systemowe.
Parametry zapytania specyficzne dla interfejsu API
W tabeli poniżej podsumowaliśmy parametry żądań, które mają zastosowanie tylko do konkretnych operacji w interfejsie Books API.
| Parametr | Znaczenie | Notatki | Obowiązywanie |
|---|---|---|---|
download |
Ogranicz do woluminów według dostępności pobierania. |
|
|
filter |
Filtruj wyniki wyszukiwania według typu woluminu i dostępności. |
|
|
langRestrict |
Ogranicza woluminy zwrócone do tych, które zostały oznaczone tagiem w wybranym języku. |
|
|
maxResults |
Maksymalna liczba elementów do zwrócenia w odpowiedzi na to żądanie. |
|
|
orderBy |
Kolejność wyszukiwania według liczby. |
|
|
printType |
Ogranicz do książek lub czasopism. |
|
|
projection |
Ogranicz informacje o woluminach zwracane do podzbioru pól. |
|
|
q |
Pełny tekst zapytania. |
|
|
startIndex |
Pozycja w kolekcji, od której ma się zaczynać lista wyników. |
|
|
volumeId |
Identyfikuje wolumin powiązany z żądaniem. |
|