Spis treści
Wprowadzenie
Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje mogące korzystać z interfejsu API Książek. Książki Google zakładają digitalizację treści książek z całego świata i zwiększają ich widoczność w internecie. Książki API umożliwiają wyszukiwanie i dostęp do tych treści oraz tworzenie i personalizację tych treści.
Jeśli nie znasz się na pojęciach z Książek Google, najpierw przeczytaj artykuł Pierwsze kroki.
Autoryzacja żądań i identyfikacja aplikacji
Każde żądanie wysyłane do aplikacji przez aplikację Books API musi identyfikować Twoją aplikację w Google. Istnieją 2 sposoby identyfikowania aplikacji: użycie tokenu OAuth 2.0 (który dodatkowo autoryzuje żądanie) i klucza interfejsu API aplikacji. Jak określić, których z tych opcji użyć:
- Jeśli żądanie wymaga autoryzacji (na przykład żądania prywatnych danych konkretnej osoby), aplikacja musi udostępnić token OAuth 2.0. Aplikacja może również udostępnić klucz interfejsu API, ale nie musi.
- Jeśli żądanie nie wymaga autoryzacji (na przykład żądania danych publicznych), aplikacja musi udostępnić klucz interfejsu API lub token OAuth 2.0 (bądź oba z tych rozwiązań) według własnego uznania.
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 do interfejsu Books API dotyczące niepublicznych danych użytkownika 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.
Informacje o zakresie 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
Żądaniem publicznym interfejsu Books API o dostęp do danych publicznych musi towarzyszyć identyfikator, który może być kluczem interfejsu API lub tokenem dostępu.
Aby uzyskać klucz interfejsu API:
- Otwórz stronę Dane logowania w konsoli interfejsu API.
-
Ten interfejs API obsługuje 2 typy danych logowania.
Utwórz odpowiednie dane logowania do swojego projektu:
-
OAuth 2.0: gdy aplikacja żąda prywatnych danych użytkownika, musi wraz z żądaniem wysłać token OAuth 2.0. Aplikacja najpierw wysyła identyfikator klienta, a być może także klucz klienta, aby uzyskać token. Możesz wygenerować dane logowania OAuth 2.0 dla aplikacji internetowych, kont usługi lub zainstalowanych aplikacji.
Więcej informacji znajdziesz w dokumentacji OAuth 2.0.
-
Klucze interfejsu API: Żądanie, które nie udostępnia tokena OAuth 2.0, musi wysłać klucz interfejsu API. Klucz identyfikuje projekt i udostępnia dostęp do interfejsu API, limit oraz raporty.
Interfejs API obsługuje kilka typów ograniczeń dotyczących kluczy interfejsu API. Jeśli klucz interfejsu API, którego potrzebujesz, nie istnieje, utwórz klucz interfejsu API w konsoli, klikając Utwórz dane logowania i klucz interfejsu API. Możesz ograniczyć klucz przed użyciem go w środowisku produkcyjnym, klikając Ogranicz klucz i wybierając jedno z ograniczeń.
-
Aby zapewnić bezpieczeństwo kluczy API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.
Gdy uzyskasz klucz interfejsu API, 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
Musisz określić pola identyfikatorów z określonymi wywołaniami metody interfejsu API. W Książkach Google są 3 rodzaje identyfikatorów:
- Identyfikatory woluminów – unikalne ciągi nadane każdemu znanemu numerowi Książek Google. Przykład identyfikatora woluminu to
_LettPDhwR0C. Identyfikator API możesz uzyskać za pomocą interfejsu API, wysyłając żądanie zwracające zasób woluminu. Identyfikator woluminu znajdziesz w poluid. - Identyfikatory półki – wartości numeryczne przyznawane półki na książki w bibliotece użytkownika. Google udostępnia kilka wstępnie zdefiniowanych półek dla każdego użytkownika o tych identyfikatorach:
- Ulubione: 0
- Kupione: 1
- Do przeczytania: 2
- Czytaj teraz: 3
- Odczyt: 4
- Ocena: 5
- Ostatnio wyświetlane: 6
- Moje e-booki: 7
- Książki dla Ciebie: 8 Jeśli nie mamy rekomendacji dla użytkownika, ta półka nie istnieje.
id. - Identyfikatory użytkowników – niepowtarzalne wartości numeryczne przypisane do każdego użytkownika. Wartości te nie muszą być takie same jak te używane w innych usługach Google. Obecnie jedynym sposobem pobrania identyfikatora użytkownika jest wyodrębnienie go z atrybutu link samodzielny w zasobie Bookshelf pobranym za pomocą uwierzytelnionego żądania. Użytkownicy mogą też uzyskać własnego identyfikatora ze strony Książki. Użytkownik nie może uzyskać identyfikatora użytkownika innego użytkownika przez interfejs API lub stronę Książek, a następnie musi udostępnić te informacje e-mailem.
Identyfikatory w witrynie Książki Google
Identyfikatory używane z interfejsem Books API są takie same jak te na stronie Książki Google.
- Identyfikator woluminu
Gdy wyświetlasz konkretny wolumin w witrynie, 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
Jeśli wyświetlasz konkretną półkę na stronie, jej identyfikator znajduje się w parametrze
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
Podczas przeglądania biblioteki w witrynie identyfikator użytkownika znajdziesz w parametrze
uid. Oto przykład:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Ustawianie lokalizacji użytkownika
W Książkach Google obowiązują prawa autorskie, umowy i inne ograniczenia prawne związane z lokalizacją użytkownika. W rezultacie 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 są „wyłącznie dostępne do podglądu” w Stanach Zjednoczonych. Takie linki pomijamy w przypadku użytkowników z innych krajów. Dlatego wyniki interfejsu API są ograniczone przez adres IP serwera lub aplikacji klienckiej.
Praca z woluminami
Przeprowadzanie wyszukiwania
Możesz przeprowadzić wyszukiwanie woluminów, wysyłając żądanie HTTP GET do tego identyfikatora URI:
https://www.googleapis.com/books/v1/volumes?q=search+terms
To żądanie zawiera 1 wymagany parametr:
q– wyszukaj woluminy zawierające ten ciąg tekstowy. W wyszukiwanych hasłach można używać specjalnych słów kluczowych, takich jak:intitle:Zwraca wyniki, w których tekst po tym słowie kluczowym występuje w tytule.inauthor:Zwraca wyniki, w przypadku których znaleziono po tekście słowo kluczowe.inpublisher:Zwraca wyniki, w przypadku których tekst po słowie kluczowym został znaleziony w wydawcy.subject:Zwraca wyniki, w których tekst po tym słowie kluczowym jest widoczny na liście kategorii woluminu.isbn:Zwraca wyniki, w których tekst po słowie kluczowym to numer ISBN.lccn:Zwraca wyniki, w których tekst występujący po tym słowie kluczowym to numer Biblioteki Kongresu.oclc:Zwraca wyniki, w przypadku których tekst po tym słowie kluczowym to numer online Computer Library Center.
Żądanie
Oto przykład wyszukiwania Daniela Keyesa & „Kwiaty dla Algernon”:
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Uwaga: wyszukiwanie nie wymaga uwierzytelniania, dlatego nie musisz podawać nagłówka HTTP Authorization w żądaniu GET. Jeśli jednak połączenie zostanie wykonane z wykorzystaniem uwierzytelniania, każdy wolumin będzie zawierał informacje związane z użytkownikiem, takie jak stan zakupu.
Odpowiedź
Jeśli żądanie się powiedzie, serwer wyśle kod stanu HTTP 200 OK i otrzyma wyniki:
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ć tych parametrów zapytania.
Format pobierania
Parametr download pozwala ograniczyć wyświetlane wyniki do woluminów, które mają dostępny format pobierania epub, ustawiając na wartość epub.
Oto przykłady wyszukiwania książek, które można pobrać z EPUB:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtrowanie
Możesz użyć parametru filter, aby dodatkowo zawęzić zwracane wyniki, ustawiając jedną z tych wartości:
partial– zwraca wyniki, w przypadku których można wyświetlić podgląd co najmniej części tekstu.full– zwraca tylko wyniki, w których widoczny jest cały tekst.free-ebooks– zwraca tylko wyniki, które są bezpłatnymi e-bookami Google.paid-ebooks– zwraca tylko wyniki z e-bookami Google z ceną.ebooks– zwraca tylko wyniki, które są e-bookami Google, płatnymi lub bezpłatnymi. Mogą to być na przykład treści wydawców, które są dostępne w wersji przedpremierowej, ale nie są dostępne w sprzedaży, albo czasopisma.
Poniższy 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
Możesz podzielić listę woluminów, określając 2 wartości w żądaniu:
startIndex– pozycja w kolekcji, od której należy rozpocząć. Indeks pierwszego elementu wynosi 0.maxResults– maksymalna liczba wyników do zwrócenia. Wartością domyślną jest 10, a maksymalna dozwolona wartość to 40.
Typ druku
Za pomocą parametru printType możesz ograniczyć zwracane wyniki do konkretnego typu publikacji lub publikacji, ustawiając ją na jedną z tych wartości:
all– nie ogranicza się według typu drukowania (domyślnie).books– zwraca tylko wyniki, które są książkami.magazines– zwraca wyniki w postaci czasopism.
Ten przykład ogranicza wyniki wyszukiwania do czasopism:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Prognoza
Możesz użyć parametru projection z jedną z tych wartości, aby określić wstępnie zdefiniowany zestaw pól woluminu:
full– zwraca wszystkie pola woluminu.lite– zwraca tylko niektóre pola. Opisy pól znajdziesz w podwójnych gwiazdkach.
Przykład poniżej pokazuje wyniki wyszukiwania z ograniczoną liczbą informacji:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Sortowanie
Domyślnie żądanie wyszukiwania dotyczące woluminu zwraca wynik maxResults, gdzie maxResults to parametr używany w podziale na strony (powyżej), uporządkowany według trafności.
Kolejność możesz zmienić, ustawiając parametr orderBy jako jedną z tych wartości:
relevance– zwraca wyniki w kolejności trafności wyszukiwanych haseł (jest to ustawienie domyślne).newest– wyświetla wyniki w kolejności od najnowszych do najstarszych.
Poniższy przykład zawiera listę wyników według daty opublikowania: od najnowszego do najstarszego.
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Pobieram określoną głośność
Informacje o określonej woluminie możesz 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, który chcesz pobrać. Więcej informacji o identyfikatorach woluminu znajdziesz w sekcji o identyfikatorach Książek Google.
Żądanie
Oto przykład żądania GET, które otrzymuje pojedynczy wolumin:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Uwaga: pobieranie informacji o woluminach nie wymaga uwierzytelniania, więc nie musisz podawać nagłówka HTTP Authorization w żądaniu GET. Jeśli jednak wywołanie zostanie wykonane z wykorzystaniem uwierzytelniania, wolumin będzie zawierał informacje dotyczące użytkownika, takie jak stan zakupu.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer wyśle 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
W szczególności chodzi o sekcję funkcji accessInfo dostępnych w przypadku e-booków. epub to e-book w formie tekstu ciągłego, a w sekcji epub właściwość isAvailable określa, czy jest on dostępny.
Zawiera ona link do pobrania książki, jeśli istnieje jej próbka lub użytkownik może ją przeczytać ze względu na zakup w lokalizacji użytkownika lub w domenie publicznej. pdf w przypadku książek Google wskazuje zeskanowaną wersję e-booka z podobnymi informacjami, np. czy jest on dostępny i link do pobrania. Google zaleca korzystanie z plików epub w przypadku czytników e-booków i smartfonów, 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 użyć poniższego parametru zapytania, aby pobrać konkretną liczbę zapytań.
Prognoza
Możesz użyć parametru projection z jedną z tych wartości, aby określić wstępnie zdefiniowany zestaw pól woluminu:
full– zwraca wszystkie pola woluminu.lite– zwraca tylko niektóre pola. Opisy pól znajdziesz w podwójnych gwiazdkach.
Ten przykład zwraca informacje o ograniczonym woluminie dla pojedynczego woluminu:
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 użytkownika
Możesz pobrać listę publicznych półek użytkownika, wysyłając żądanie HTTP o identyfikatorze 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 chcesz pobrać. Identyfikatory użytkowników znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie
Oto przykład.
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Ponieważ użytkownik nie musi uwierzytelniać się, aby uzyskać informacje dotyczące publicznych półek, nie musisz podawać nagłówka HTTP Authorization w żądaniu GET.
Odpowiedź
Jeśli żądanie się powiedzie, serwer wyśle kod stanu HTTP 200 OK i listę półek:
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 użytkownika możesz użyć standardowych parametrów zapytania.
Pobieram określoną publiczną półkę
Konkretną publiczną półkę na książki możesz pobrać, wysyłając żądanie HTTP GET do identyfikatora URI w formacie:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Zastąp parametry ścieżki userId i półka identyfikatorami dotyczącymi konta użytkownika i półki, którą chcesz pobrać. Więcej informacji znajdziesz w sekcji o identyfikatorach Książek Google.
Żądanie
Oto przykład.
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Ponieważ użytkownik nie musi uwierzytelniać się, aby uzyskać informacje dotyczące publicznych półek, nie musisz podawać nagłówka HTTP Authorization w żądaniu GET.
Odpowiedź
Jeśli żądanie się powiedzie, serwer wyśle kod stanu HTTP 200 OK i zasoby z 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
Jeśli pobierasz konkretną półkę na książki, możesz użyć standardowych parametrów zapytania.
Pobieram listę tomów na publicznej półce
Możesz pobrać listę tomów na publicznej półce użytkownika, wysyłając identyfikator URI w formacie HTTP:GET w następującym formacie:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Żądanie
Oto przykład.
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Zastąp parametry ścieżki userId i półka identyfikatorami dotyczącymi konta użytkownika i półki, którą chcesz pobrać. Więcej informacji znajdziesz w sekcji o identyfikatorach Książek Google.
Ponieważ użytkownik nie musi uwierzytelniać się, aby uzyskać informacje dotyczące publicznych półek, nie musisz podawać nagłówka HTTP Authorization w żądaniu GET.
Odpowiedź
Jeśli żądanie się powiedzie, serwer wyśle kod stanu HTTP 200 OK i listę półek 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ć tego parametru zapytania podczas pobierania listy tomów na publicznej półce.
Podział na strony
Możesz podzielić listę woluminów, określając 2 wartości w żądaniu:
startIndex– pozycja w kolekcji, od której należy rozpocząć. Indeks pierwszego elementu wynosi 0.maxResults– maksymalna liczba wyników do zwrócenia. Wartością domyślną jest 10, a maksymalna dozwolona wartość to 40.
Praca z półkami w sekcji „Moja biblioteka”
Wszystkie żądania &Mojej biblioteki mają zastosowanie do danych uwierzytelnionego użytkownika.
Pobieranie listy moich półek na książki
Możesz pobrać listę wszystkich uwierzytelnionych półek użytkownika, wysyłając żądanie HTTP GET do identyfikatora URI w następującym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Żądanie
Oto przykład.
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Uwaga: użytkownik musi być uwierzytelniony, aby pobrać listę „Półek z książkami”. Musisz więc podać nagłówek HTTP Authorization z żądaniem GET.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer wyśle kod stanu HTTP 200 OK oraz listę wszystkich półek na bieżące konto 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 uwierzytelnionych półek użytkownika możesz użyć standardowych parametrów zapytania.
Pobieram listę tomów na mojej półce
Możesz pobrać listę tomów na uwierzytelnionej półce użytkownika, wysyłając żądanie HTTP GET do identyfikatora URI w następującym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Zastąp parametr ścieżki półka identyfikatorem półki na książki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie
Oto przykład.
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Uwaga: użytkownik musi być uwierzytelniony, aby pobrać listę woluminów &Mojej biblioteki. Musisz więc podać nagłówek HTTP Authorization z żądaniem GET.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer odpowiada kodem stanu HTTP 200 OK i listą woluminów półki:
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żywać tego parametru zapytania podczas pobierania listy tomów na jednej z uwierzytelnionych półek użytkownika.
Podział na strony
Możesz podzielić listę woluminów, określając 2 wartości w żądaniu:
startIndex– pozycja w kolekcji, od której należy rozpocząć. Indeks pierwszego elementu wynosi 0.maxResults– maksymalna liczba wyników do zwrócenia. Domyślna wartość to 10.
Dodaję wolumin do mojej półki
Aby dodać wolumin do uwierzytelnionej półki użytkownika, wyślij żądanie HTTP POST do identyfikatora URI w następującym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Zastąp parametr ścieżki półka identyfikatorem półki na książki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie zawiera 1 wymagany parametr zapytania:
volumeId– identyfikator woluminu; Więcej informacji o identyfikatorach woluminu znajdziesz w sekcji o identyfikatorach Książek Google.
Żądanie
Oto przykład dodania kwiaty dla Algernon &"Ulubione do półki:
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: użytkownik musi być uwierzytelniony, aby móc modyfikować półkę na książki, więc musisz udostępnić nagłówek HTTP Authorization z żądaniem POST. W przypadku tego elementu POST nie są jednak wymagane żadne dane.
Odpowiedź
Jeśli żądanie się powiedzie, serwer wyśle kod stanu HTTP 204 No Content.
Opcjonalne parametry zapytania
Gdy dodajesz wolumin do jednej z uwierzytelnionych półek użytkownika, możesz użyć standardowych parametrów zapytania.
Usuwanie woluminu z mojej półki
Aby usunąć wolumin z półki z uwierzytelnionym użytkownikiem, wyślij protokół HTTP POST do identyfikatora URI w następującym formacie:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Zastąp parametr ścieżki półka identyfikatorem półki na książki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie zawiera 1 wymagany parametr zapytania:
volumeId– identyfikator woluminu; Więcej informacji o identyfikatorach woluminu znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie
Oto przykład, aby usunąć kwiaty dla algernona z półki „Ulubione” na półce:
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: użytkownik musi być uwierzytelniony, aby móc modyfikować półkę na książki, więc musisz udostępnić nagłówek HTTP Authorization z żądaniem POST. W przypadku tego elementu POST nie są jednak wymagane żadne dane.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer wyśle kod stanu 204 No Content.
Opcjonalne parametry zapytania
Gdy usuwasz wolumin z jednej z zweryfikowanych półek użytkownika, możesz użyć standardowych parametrów zapytania.
Czyszczenie wszystkich tomów z mojej 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ółka identyfikatorem półki na książki. Więcej informacji o identyfikatorach półki na książki znajdziesz w sekcji Identyfikatory Książek Google.
Żądanie
Oto przykład, w jaki można wyczyścić półkę „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: użytkownik musi być uwierzytelniony, aby móc modyfikować półkę na książki, więc musisz udostępnić nagłówek HTTP Authorization z żądaniem POST. W przypadku tego elementu POST nie są jednak wymagane żadne dane.
Odpowiedź
Jeśli żądanie zostanie zrealizowane, serwer wyśle kod stanu 204 No Content.
Opcjonalne parametry zapytania
Jeśli chcesz usunąć wszystkie woluminy z jednej z półek uwierzytelnionych użytkowników, możesz użyć standardowych parametrów zapytania.
Odwołanie do parametru zapytania
W tej sekcji podsumowaliśmy parametry zapytania, których możesz używać z interfejsem Books API.Wszystkie wartości parametrów muszą być zakodowane.
Standardowe parametry zapytania
Parametry zapytania, które mają zastosowanie do wszystkich operacji w interfejsie Books API, są wymienione w Parametrach systemowych.
Parametry zapytania dotyczące interfejsu API
W poniższej tabeli omówiono parametry żądania dotyczące tylko konkretnych operacji w interfejsie Books API.
| Parametr | Znaczenie | Uwagi | 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 wyświetlane do woluminów otagowanych w danym języku. |
|
|
maxResults |
Maksymalna liczba elementów, które zostaną zwrócone z tym żądaniem. |
|
|
orderBy |
Kolejność wyników wyszukiwania woluminów. |
|
|
printType |
Ogranicz do książek lub czasopism. |
|
|
projection |
Ogranicz informacje o woluminach zwrócone do podzbioru pól. |
|
|
q |
Pełny tekst zapytania. |
|
|
startIndex |
Pozycja w kolekcji, w której należy rozpocząć listę wyników. |
|
|
volumeId |
Identyfikuje wolumin powiązany z żądaniem. |
|