Korzystanie z interfejsu API

Spis treści

Wprowadzenie

Ten dokument jest przeznaczony dla deweloperów, którzy chcą pisać aplikacje, które mogą wchodzić w interakcję z interfejsem Books API. Książki Google mają na celu zdigitalizowanie treści książek z całego świata i zwiększenie ich widoczności w internecie. Interfejs Books API umożliwia wyszukiwanie i dostęp do tych treści, a także tworzenie i wyświetlanie personalizacji.

Jeśli nie znasz pojęć związanych z Książkami Google, przed rozpoczęciem kodowania przeczytaj Wprowadzenie.

Autoryzowanie żądań i identyfikowanie aplikacji

Każde żądanie wysyłane przez aplikację do interfejsu Books API musi identyfikować Twoją aplikację w Google. Aplikację można zidentyfikować na 2 sposoby: za pomocą tokena OAuth 2.0 (który autoryzuje też żądanie) lub za pomocą klucza interfejsu API aplikacji. Aby zdecydować, który z nich wybrać:

• Jeśli żądanie wymaga autoryzacji (np. żądanie prywatnych danych osoby), aplikacja musi przesłać z nim token OAuth 2.0. Aplikacja może też podać klucz interfejsu API, ale nie musi tego robić.
• Jeśli żądanie nie wymaga autoryzacji (np. żądanie danych publicznych), aplikacja musi podać klucz API lub token OAuth 2.0 albo oba te elementy – w zależności od tego, co jest wygodniejsze.

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 wysyłane do Books API o niepubliczne dane 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:

1. 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.
2. Aktywuj interfejs Books API w konsoli interfejsów API Google. (jeśli interfejsu API nie ma na liście w konsoli, pomijasz ten krok).
3. Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
4. Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
5. Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
6. Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
7. 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 zakres danych 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

Żądaniom przesyłanym do interfejsu Books API w celu uzyskania danych publicznych musi towarzyszyć identyfikator, którym może być klucz API lub token dostępu.

Aby uzyskać klucz interfejsu API:

1. W Konsoli interfejsów API otwórz stronę Dane logowania.
2. Ten interfejs API obsługuje 2 rodzaje danych logowania. Utwórz dane logowania odpowiednie do Twojego projektu:

   • OAuth 2.0: gdy aplikacja prosi o prywatne dane użytkownika, musi przesłać token OAuth 2.0 wraz z żądaniem. Aby uzyskać token, aplikacja najpierw wysyła identyfikator klienta i opcjonalnie tajny klucz klienta. Możesz generować 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 zawiera tokena OAuth 2.0, musi zawierać klucz interfejsu API. Klucz identyfikuje projekt i zapewnia dostęp do interfejsu API, limitów oraz raportów.

     Interfejs API obsługuje kilka typów ograniczeń kluczy API. Jeśli klucz interfejsu API, którego potrzebujesz, nie istnieje, utwórz go w Konsoli, klikając Utwórz dane logowania  > Klucz interfejsu API. Możesz ograniczyć klucz przed jego użyciem w środowisku produkcyjnym. Aby to zrobić, kliknij Ogranicz klucz i wybierz jedną z opcji Ograniczenia.

Aby zabezpieczyć klucze interfejsu API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja będzie mogła dołączać parametry zapytania key=yourAPIKey do adresów URL wszystkich żądań.

Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.

Identyfikatory Książek Google

W przypadku niektórych wywołań metod interfejsu API musisz podać pola identyfikatora. W Książkach Google używane są 3 typy identyfikatorów:

• Identyfikatory woluminów – unikalne ciągi znaków przypisane do każdego woluminu, który jest znany Książkom Google. Przykładem identyfikatora woluminu jest _LettPDhwR0C. Aby uzyskać identyfikator woluminu, możesz użyć interfejsu API, wysyłając żądanie, które zwróci zasób Volume. Identyfikator woluminu znajdziesz w polu id.
• Identyfikatory półek – wartości liczbowe przypisane do półki w bibliotece użytkownika. Google udostępnia wstępnie zdefiniowane półki dla każdego użytkownika z tymi identyfikatorami:
  • Ulubione: 0
  • Kupiono: 1
  • Do przeczytania: 2
  • Czytanie teraz: 3
  • Przeczytane: 4
  • Sprawdzono: 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.
  Półki niestandardowe mają identyfikatory większe niż 1000. Identyfikator półki jest unikalny dla danego użytkownika, co oznacza, że dwóch użytkowników może mieć półkę z tym samym identyfikatorem, która odwołuje się do różnych półek. Aby uzyskać identyfikator półki, możesz użyć interfejsu API, wysyłając żądanie, które zwróci zasób Bookshelf. Identyfikator półki znajdziesz w polu id.
• Identyfikatory użytkowników – unikalne wartości liczbowe przypisane do każdego użytkownika. Te wartości nie muszą być takie same jak wartości identyfikatorów używanych w innych usługach Google. Obecnie jedynym sposobem na pobranie identyfikatora użytkownika jest wyodrębnienie go z linku samoobsługowego w zasobie półki z książkami pobranym za pomocą uwierzytelnionego żądania. Użytkownicy mogą też uzyskać swój identyfikator użytkownika na stronie Książki. Użytkownik nie może uzyskać identyfikatora innego użytkownika za pomocą interfejsu API ani na stronie Google Play; użytkownik, którego identyfikator ma zostać udostępniony, musi udostępnić te informacje w wyraźny sposób, na przykład przez e-maila.

Identyfikatory w Książkach Google

Identyfikatory używane w interfejsie Books API są takie same jak identyfikatory używane na stronie Książki Google.

• Identyfikator woluminu
  

  Podczas wyświetlania konkretnego tomu w witrynie identyfikator tomu można znaleźć 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
  

  Podczas wyświetlania konkretnej półki w witrynie możesz znaleźć jej identyfikator 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 wyświetlasz swoją bibliotekę w witrynie, możesz znaleźć identyfikator użytkownika w parametrze adresu URL uid. Oto przykład:

  https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

Konfigurowanie lokalizacji użytkownika

Książki Google respektują prawa autorskie, umowy i inne ograniczenia prawne związane z lokalizacją użytkownika. W efekcie 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 „przeglądać” tylko w Stanach Zjednoczonych. W przypadku użytkowników z innych krajów pomijamy takie linki. Dlatego wyniki interfejsu API są ograniczone na podstawie adresu IP Twojego serwera lub aplikacji klienta.

Praca z tomami

Wyszukiwanie

Aby przeprowadzić wyszukiwanie wolumenów, wyślij żądanie HTTP GET do tego identyfikatora URI:

https://www.googleapis.com/books/v1/volumes?q=search+terms

Ta prośba ma 1 wymagany parametr:

• q – wyszukiwanie woluminów zawierających ten ciąg tekstowy. W wyszukiwanych hasłach możesz podać specjalne słowa kluczowe, aby wyszukiwać w określonych polach, np.:
  • intitle: Zwraca wyniki, w których tytule występuje tekst po tym słowie kluczowym.
  • inauthor: Zwraca wyniki, w których tekście znajduje się tekst po tym słowie kluczowym.
  • inpublisher: Zwraca wyniki, w których w wydawcy występuje tekst następujący po tym słowie kluczowym.
  • subject: Zwraca wyniki, w których tekst po tym słowie kluczowym znajduje się na liście kategorii tomu.
  • isbn: Zwraca wyniki, w których tekst po tym słowie kluczowym to numer ISBN.
  • lccn: Zwraca wyniki, w których tekst po tym haśle to numer LCCN.
  • oclc: Zwraca wyniki, w których tekst po tym słowie kluczowym to numer OCLC.

Żądanie

Oto przykład wyszukiwania książki Daniela Keyesa „Flowers for Algernon”:

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

Uwaga: wykonanie wyszukiwania nie wymaga uwierzytelnienia, więc nie musisz podawać nagłówka HTTP Authorization w żądaniu GET. Jeśli jednak połączenie jest nawiązywane z weryfikacją, każda z tomów będzie zawierać informacje o użytkowniku, takie jak stan zakupu.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie kodem stanu HTTP 200 OK i wynikami dotyczącymi głośności:

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 wolumenów możesz używać tych parametrów zapytania.

Format pobierania

Parametr download służy do ograniczania zwracanych wyników do woluminów, które mają dostępny format pobierania epub. Aby to zrobić, ustaw wartość na epub.

W tym przykładzie wyszukujemy książki, które można pobrać w formacie epub:

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 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 dotyczące bezpłatnych e-booków Google.
• paid-ebooks – zwraca tylko wyniki dotyczące e-booków Google z określoną ceną.
• ebooks – zwraca tylko wyniki dotyczące e-booków Google, płatnych lub bezpłatnych. Przykładami treści innych niż e-booki są treści wydawców dostępne w ramach ograniczonego podglądu, które nie są przeznaczone do sprzedaży, lub czasopisma.

W tym przykładzie ograniczamy wyniki wyszukiwania do tych, które są dostępne 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, podając 2 wartości w parametrach żądania:

• startIndex – pozycja w kolekcji, od której ma się rozpocząć. Indeks pierwszego elementu to 0.
• maxResults – maksymalna liczba wyników do zwrócenia. Wartość domyślna to 10, a maksymalna dopuszczalna wartość to 40.

Typ wydruku

Parametr printType możesz użyć, aby ograniczyć zwracane wyniki do konkretnego typu publikacji lub publikacji drukowanej. Aby to zrobić, ustaw go na jedną z tych wartości:

• all – nie ogranicza drukowania według typu (ustawienie domyślne).
• books – zwraca tylko wyniki, które są książkami.
• magazines – zwraca wyniki, które są czasopismami.

W tym przykładzie wyniki wyszukiwania są ograniczone do czasopism:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey

Odwzorowanie

Aby określić zwracany wstępnie zdefiniowany zbiór pól Volume, możesz użyć parametru projection z jednym z tych wartości:

• full – zwraca wszystkie pola Volume.
• lite – zwraca tylko niektóre pola. Aby dowiedzieć się, które pola są uwzględnione, zapoznaj się z opisami pól oznaczonymi podwójnym gwiazdką w pliku Reference Volume.

Ten przykład zwraca 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 danych o wynikach zwraca maxResults wyników, gdzie maxResults to parametr używany w podziale na strony (powyżej), uporządkowanych według trafności dla wyszukiwanych słów.

Możesz zmienić kolejność, ustawiając parametr orderBy na jedną z tych wartości:

• relevance – zwraca wyniki według trafności wyszukiwanych haseł (wartość domyślna).
• newest – zwraca wyniki w kolejności od najnowszego do najstarszego.

W tym przykładzie wyniki są posortowane według daty publikacji od najnowszej do najstarszej:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

Pobieranie konkretnego woluminu

Aby pobrać informacje o konkretnym woluminie, wyślij żądanie HTTPGET do URI zasobu Volume:

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 książek znajdziesz w sekcji Identyfikatory książek Google.

Żądanie

Oto przykład GET, który zwraca pojedynczy wolumen:

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 połączenie jest realizowane z weryfikacją, Volume będzie zawierać informacje o użytkowniku, takie jak stan zakupu.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie kodem stanu HTTP 200 OK i żądanym zasobem Volume:

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 jest szczególnie przydatna do określenia, jakie funkcje są dostępne w przypadku danej książki. epub to ebook w formacie tekstu płynnego. W sekcji epub znajduje się właściwość isAvailable wskazująca, czy ebook tego typu jest dostępny. Jeśli jest dostępna próbka książki lub użytkownik może ją przeczytać, ponieważ ją kupił lub jest ona dostępna w publicznej domenie w jego lokalizacji, link do pobrania będzie widoczny. pdf w Książkach Google oznacza wersję e-booka ze zeskanowanymi stronami z podobnymi szczegółami, takimi jak dostępność i link do pobrania. Google zaleca używanie plików epub na czytnikach i smartfonach, ponieważ zeskanowane strony mogą być na tych urządzeniach trudne do odczytania. Jeśli nie ma sekcji accessInfo, to tom nie jest dostępny jako e-book w Google.

Opcjonalne parametry zapytania

Oprócz standardowych parametrów zapytania możesz używać tego parametru zapytania podczas pobierania konkretnego tomu.

Odwzorowanie

Aby określić zwracany wstępnie zdefiniowany zbiór pól Volume, możesz użyć parametru projection z jednym z tych wartości:

• full – zwraca wszystkie pola Volume.
• lite – zwraca tylko niektóre pola. Aby dowiedzieć się, które pola są uwzględnione, zapoznaj się z opisami pól oznaczonymi podwójnym gwiazdką w pliku Reference Volume.

W tym przykładzie zwracane są ograniczone informacje o woluminie:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

Praca z półkami

Pobieranie listy publicznych półek z książkami użytkownika

Aby pobrać listę publicznych półek użytkownika, wyślij żądanie HTTP GET do adresu URI w tym 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ć. Więcej informacji o identyfikatorach 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

Użytkownik nie musi się uwierzytelnić, aby pobrać informacje dotyczące publicznych półek z książkami, dlatego nie musisz podawać nagłówka HTTP Authorization w żądaniu GET.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie kodem 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 z książkami użytkownika możesz używać standardowych parametrów zapytania.

Pobieranie konkretnej publicznej półki

Aby pobrać konkretną publiczną półkę, wyślij żądanie HTTP GET do identyfikatora URI w tym formacie:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

Zastąp parametry ścieżki userId i shelf identyfikatorami, które określają użytkownika i półkę, które chcesz pobrać. Więcej informacji znajdziesz w sekcji Identyfikatory Książek Google.

Żądanie

Oto przykład:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

Użytkownik nie musi się uwierzytelnić, aby pobrać informacje dotyczące publicznych półek z książkami, dlatego nie musisz podawać nagłówka HTTP Authorization w żądaniu GET.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie z kodem stanu HTTP 200 OK i zasobem 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 konkretnej publicznej półki możesz użyć standardowych parametrów zapytania.

Pobieranie listy książek na publicznej półce

Możesz pobrać listę książek na publicznej półce użytkownika, wysyłając żądanie HTTP GET do URI o tym 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 shelf identyfikatorami, które określają użytkownika i półkę, które chcesz pobrać. Więcej informacji znajdziesz w sekcji Identyfikatory Książek Google.

Użytkownik nie musi się uwierzytelnić, aby pobrać informacje dotyczące publicznych półek z książkami, dlatego nie musisz podawać nagłówka HTTP Authorization w żądaniu GET.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie kodem stanu HTTP 200 OKi 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 zapytań możesz używać tego parametru zapytania podczas pobierania listy książek na publicznej półce.

Podział na strony

Listę woluminów możesz podzielić na strony, podając 2 wartości w parametrach żądania:

• startIndex – pozycja w kolekcji, od której ma się rozpocząć. Indeks pierwszego elementu to 0.
• maxResults – maksymalna liczba wyników do zwrócenia. Wartość domyślna to 10, a maksymalna dopuszczalna wartość to 40.

Praca z półkami w sekcji „Moja biblioteka”

Wszystkie żądania dotyczące „Mojej biblioteki” odnoszą się do danych zalogowanego użytkownika.

Pobieranie listy moich półek

Możesz pobrać listę wszystkich półek zalogowanego użytkownika, wysyłając żądanie HTTP GET do adresu URI o takim 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: aby pobrać listę półek „Moja biblioteka”, użytkownik musi się uwierzytelnić. W tym celu musisz podać nagłówek HTTP Authorization w żądaniu GET.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie kodem stanu HTTP 200 OK oraz listą wszystkich półek dla aktualnie 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 zalogowanego użytkownika możesz użyć standardowych parametrów zapytania.

Pobieranie listy woluminów na mojej półce

Aby pobrać listę woluminów na półce uwierzytelnionego użytkownika, wyślij żądanie HTTP GET do adresu URI o takim formacie:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

Zastąp parametr ścieżki shelf identyfikatorem półki. Więcej informacji o identyfikatorach pół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: aby pobrać listę książek z sekcji „Moja biblioteka”, użytkownik musi się uwierzytelnić. W tym celu musisz podać nagłówek HTTP Authorization w żądaniu GET.

Odpowiedź

Jeśli żądanie zakończy się powodzeniem, serwer odpowie kodem stanu HTTP 200 OK i listą woluminów na półce:

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 woluminów na jednej z półek zalogowanego użytkownika.

Podział na strony

Listę woluminów możesz podzielić na strony, podając 2 wartości w parametrach żądania:

• startIndex – pozycja w kolekcji, od której ma się rozpocząć. Indeks pierwszego elementu to 0.
• maxResults – maksymalna liczba wyników do zwrócenia. Wartość domyślna to 10.

Dodawanie książki do półki

Aby dodać tomy do półki z książkami uwierzytelnionego użytkownika, wyślij żądanie HTTP POST do identyfikatora URI w tym formacie:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

Zastąp parametr ścieżki shelf identyfikatorem półki. Więcej informacji o identyfikatorach półki znajdziesz w sekcji Identyfikatory książek Google.

Prośba zawiera 1 wymagany parametr zapytania:

• volumeId – identyfikator woluminu. Więcej informacji o identyfikatorach tomów znajdziesz w sekcji Identyfikatory Ksiąg Google.

Żądanie

Oto przykład dodawania książki „Flowers for 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 wprowadzić zmiany w poręczniku, użytkownik musi się uwierzytelnić, dlatego w żądaniu POST musisz podać nagłówek HTTP Authorization. Nie wymaga on jednak żadnych danych.POST

Odpowiedź

Jeśli żądanie zostanie zrealizowane, serwer odpowie kodem stanu HTTP 204 No Content.

Opcjonalne parametry zapytania

Podczas dodawania tomu do jednej z półek z książkami uwierzytelnionego użytkownika możesz używać standardowych parametrów zapytania.

Usuwanie książki z półki

Aby usunąć tom z półki zalogowanego użytkownika, wyślij HTTP POST do adresu URI w tym formacie:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

Zastąp parametr ścieżki shelf identyfikatorem półki. Więcej informacji o identyfikatorach półki znajdziesz w sekcji Identyfikatory książek Google.

Prośba zawiera 1 wymagany parametr zapytania:

• volumeId – identyfikator woluminu. Więcej informacji o identyfikatorach książek znajdziesz w sekcji Identyfikatory Ksiąg Google.

Żądanie

Oto przykład usuwania książki „Flowers for 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 wprowadzić zmiany w poręczniku, użytkownik musi się uwierzytelnić, dlatego w żądaniu POST musisz podać nagłówek HTTP Authorization. Nie wymaga on jednak żadnych danych.POST

Odpowiedź

Jeśli żądanie zostanie zrealizowane, serwer odpowie kodem stanu 204 No Content.

Opcjonalne parametry zapytania

Podczas usuwania książki z półki jednej z autoryzowanych półek użytkownika możesz użyć standardowych parametrów zapytania.

Wyczyszczenie wszystkich tomów z półki

Aby usunąć wszystkie tomy z półki uwierzytelnionego użytkownika, wyślij HTTP POST do identyfikatora URI w tym formacie:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

Zastąp parametr ścieżki shelf identyfikatorem półki. Więcej informacji o identyfikatorach półki znajdziesz w sekcji Identyfikatory książek Google.

Żądanie

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 wprowadzić zmiany w poręczniku, użytkownik musi się uwierzytelnić, dlatego w żądaniu POST musisz podać nagłówek HTTP Authorization. Nie wymaga on jednak żadnych danych.POST

Odpowiedź

Jeśli żądanie zostanie zrealizowane, serwer odpowie kodem stanu204 No Content.

Opcjonalne parametry zapytania

Możesz użyć standardowych parametrów zapytania, aby wyczyścić wszystkie tomy z półek jednego z uwierzytelnionych użytkowników.

Odwołania do parametrów zapytania

W tej sekcji znajdziesz podsumowanie parametrów zapytania, których możesz używać z interfejsem 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 w interfejsie Books API, są opisane w dokumentacji Parametry systemowe.

Parametry zapytania związane z interfejsem API

Parametry żądania, które mają zastosowanie tylko do określonych operacji w Books API, zostały opisane w tabeli poniżej.