Korzystanie z interfejsu API

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:

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 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:

1. Otwórz stronę Dane logowania w konsoli interfejsów API.
2. 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 polu id.
• 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.
  Identyfikatory półek niestandardowych są większe niż 1000. Identyfikator półki na książki jest unikalny dla danego użytkownika. Oznacza to, że dwóch użytkowników może mieć półkę z tym samym identyfikatorem odnoszącym się do różnych półek. Możesz użyć interfejsu API, aby uzyskać identyfikator półki na książki, wysyłając żądanie, które zwraca zasób półki. Znajdziesz go w polu 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.