API verwenden

Inhalt

Einleitung

Dieses Dokument richtet sich an Entwickler, die Anwendungen schreiben möchten, die mit der Books API interagieren können. Das Ziel von Google Books ist es, die Buchinhalte dieser Welt zu digitalisieren und im Web leichter auffindbar zu machen. Mit der Books API können Sie diese Inhalte suchen und darauf zugreifen sowie personalisierte Inhalte rund um diese Inhalte erstellen und ansehen.

Wenn Sie mit den Konzepten von Google Books nicht vertraut sind, sollten Sie den Artikel Erste Schritte lesen, bevor Sie mit dem Programmieren beginnen.

Anfragen autorisieren und Ihre Anwendung identifizieren

Jede Anfrage, die Ihre Anwendung an die Books API sendet, muss Ihre Anwendung bei Google identifizieren. Dafür gibt es zwei Möglichkeiten: die Verwendung eines OAuth 2.0-Tokens, das auch die Anfrage autorisiert, und/oder die Verwendung des API-Schlüssels der Anwendung. Welche dieser Optionen Sie nutzen sollten, hängt von Folgendem ab:

• Wenn die Anfrage eine Autorisierung erfordert (z. B. wenn die privaten Daten einer Person angefordert werden), muss die Anwendung ein OAuth 2.0-Token zusammen mit der Anfrage bereitstellen. Die Anwendung kann auch den API-Schlüssel bereitstellen, muss dies jedoch nicht tun.
• Wenn die Anfrage keine Autorisierung erfordert, beispielsweise bei einer Anfrage in Bezug auf öffentliche Daten, muss die Anwendung entweder den API-Schlüssel oder ein OAuth 2.0-Token oder beides bereitstellen, je nachdem, was für Sie am bequemsten ist.

Über Autorisierungsprotokolle

Ihre Anwendung muss zur Autorisierung von Anfragen OAuth 2.0 verwenden. Andere Autorisierungsprotokolle werden nicht unterstützt. Wenn deine Anwendung Über Google anmelden verwendet, werden einige Schritte der Autorisierung automatisch ausgeführt.

Anfragen mit OAuth 2.0 autorisieren

Anfragen an die Books API für nicht öffentliche Nutzerdaten müssen von einem authentifizierten Nutzer autorisiert werden.

Die Details dieses Autorisierungsablaufs für OAuth 2.0 hängen davon ab, welche Art von Anwendung du schreibst. Die folgende allgemeine Vorgehensweise gilt für alle Arten von Anwendungen:

1. Wenn Sie Ihre Anwendung erstellen, registrieren Sie diese über die Google API Console. Google stellt Ihnen dann die Informationen bereit, die du später benötigst, z. B. eine Client-ID und einen Clientschlüssel.
2. Aktivieren Sie die Books API in der Google API Console. Überspringe diesen Schritt, falls die API nicht in der API Console aufgeführt ist.
3. Wenn deine Anwendung Zugriff auf Nutzerdaten benötigt, bittet sie Google um einen bestimmten Zugriffsbereich.
4. Dem Nutzer wird von Google ein Zustimmungsbildschirm angezeigt, auf dem er gebeten wird, deine Anwendung dazu zu autorisieren, einige seiner Daten abzufragen.
5. Wenn der Nutzer zustimmt, erhält deine Anwendung von Google ein kurzlebiges Zugriffstoken.
6. Die Anwendung fordert Nutzerdaten an, wobei das Zugriffstoken an die Anfrage angehängt wird.
7. Stellt Google fest, dass Ihre Anfrage und das Token gültig sind, werden die angeforderten Daten zurückgegeben.

Einige Abläufe enthalten zusätzliche Schritte, beispielsweise die Verwendung von Aktualisierungstoken zum Erhalt neuer Zugriffstoken. Weitere Informationen über die Abläufe für die unterschiedlichen Anwendungstypen findest du in der OAuth 2.0-Dokumentation.

Im Folgenden finden Sie die Informationen zum Umfang von OAuth 2.0 für die Books API:

https://www.googleapis.com/auth/books

Zur Anforderung eines Zugriffs mit OAuth 2.0 benötigt Ihre Anwendung die Informationen zum Umfang sowie die Informationen, die Google bei der Registrierung Ihrer Anwendung bereitstellt, z. B. die Client-ID und den Clientschlüssel.

Tipp: Die Google APIs-Clientbibliotheken können einige Schritte des Autorisierungsvorgangs für Sie übernehmen. Diese sind in zahlreichen Programmiersprachen verfügbar. Weitere Informationen dazu finden Sie auf der Seite mit Bibliotheken und Beispielen.

API-Schlüssel erhalten und nutzen

Anfragen an die Books API nach öffentlichen Daten muss eine Kennung angehängt werden. Diese kann ein API-Schlüssel oder ein Zugriffstoken sein.

So erhalten Sie einen API-Schlüssel:

1. Öffnen Sie in der API Console die Seite Anmeldedaten.
2. Diese API unterstützt zwei Arten von Anmeldedaten. Erstellen Sie die Anmeldedaten, die für Ihr Projekt geeignet sind:

   • OAuth 2.0: Wenn Ihre Anwendung private Nutzerdaten anfordert, muss sie zusammen mit der Anfrage ein OAuth 2.0-Token senden. Die Anwendung sendet zuerst eine Client-ID und möglicherweise einen Clientschlüssel, um ein Token zu erhalten. Sie können OAuth 2.0-Anmeldedaten für Webanwendungen, Dienstkonten oder installierte Anwendungen generieren.

     Weitere Informationen finden Sie in der OAuth 2.0-Dokumentation.

   • API-Schlüssel: Eine Anfrage, die kein OAuth 2.0-Token bereitstellt, muss einen API-Schlüssel senden. Mit diesem Schlüssel werden Ihr Projekt identifiziert sowie der API-Zugriff, das Kontingent und Berichte bereitgestellt.

     Die API unterstützt mehrere Arten von Einschränkungen für API-Schlüssel. Wenn der API-Schlüssel, den Sie benötigen, noch nicht vorhanden ist, erstellen Sie einen API-Schlüssel in der Console. Klicken Sie dazu auf Anmeldedaten erstellen > API-Schlüssel. Sie können Einschränkungen für den Schlüssel festlegen, bevor Sie ihn in der Produktion verwenden. Klicken Sie dazu auf Schlüssel einschränken und wählen Sie eine der Einschränkungen aus.

Folgen Sie zur Wahrung der Sicherheit Ihrer API-Schlüssel den Best Practices zur sicheren Verwendung von API-Schlüsseln.

Nachdem Sie einen API-Schlüssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anhängen.

Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.

Google Books-IDs

Bei bestimmten API-Methodenaufrufen müssen Sie ID-Felder angeben. In Google Books gibt es drei Arten von IDs:

• Band-IDs: eindeutige Strings für jeden Band, der Google Books bekannt ist. Ein Beispiel für eine Volume-ID ist _LettPDhwR0C. Sie können die API verwenden, um die Volume-ID abzurufen, indem Sie eine Anfrage stellen, die eine Volume-Ressource zurückgibt. Sie finden die Volume-ID im Feld id.
• Bücherregal-IDs: Numerische Werte, die einem Bücherregal in der Bibliothek eines Nutzers zugewiesen werden. Google stellt einige vordefinierte Bereiche für jeden Nutzer mit den folgenden IDs zur Verfügung:
  • Favoriten: 0
  • Gekauft: 1
  • Lesen: 2
  • Jetzt lesen: 3
  • Gelesen: 4
  • Überprüft: 5
  • Zuletzt angesehen: 6
  • Meine E-Books: 7
  • Bücher für dich: 8 Wenn wir keine Empfehlungen für den Nutzer haben, gibt es dieses Regal nicht.
  Benutzerdefinierte Regale haben IDs größer als 1.000. Die Bücherregal-ID ist für einen bestimmten Nutzer eindeutig. Das heißt, zwei Nutzer können ein Bücherregal mit derselben ID haben, die sich auf verschiedene Bücherregale beziehen. Sie können die API verwenden, um die Bookshelf-ID abzurufen. Stellen Sie dazu eine Anfrage, die eine Bookshelf-Ressource zurückgibt. Sie finden die Bookshelf-ID im Feld id.
• Nutzer-IDs: eindeutige numerische Werte, die jedem Nutzer zugewiesen sind Diese Werte entsprechen nicht unbedingt den ID-Werten, die in anderen Google-Diensten verwendet werden. Derzeit besteht die einzige Möglichkeit zum Abrufen der Nutzer-ID darin, sie aus dem SelfLink in einer Bookshelf-Ressource zu extrahieren, die mit einer authentifizierten Anfrage abgerufen wurde. Nutzer können auch ihre eigene Nutzer-ID auf der Google Books-Website abrufen. Ein Nutzer kann die Nutzer-ID für einen anderen Nutzer nicht über die API oder die Website von Google Books abrufen. Der andere Nutzer muss diese Informationen explizit per E-Mail weitergeben.

IDs auf der Google Books-Website

Die IDs, die du mit der Books API verwendest, sind dieselben wie auf der Google Books-Website.

• Volume-ID
  

  Wenn du dir ein bestimmtes Volume auf der Website ansiehst, findest du die Volume-ID im URL-Parameter id. Hier ein Beispiel:

  https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

• Bücherregal-ID
  

  Wenn du ein bestimmtes Bücherregal auf der Website aufrufst, findest du seine ID im URL-Parameter as_coll. Hier ein Beispiel:

  https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

• Nutzer-ID
  

  Du findest die Nutzer-ID im URL-Parameter uid, wenn du deine Bibliothek auf der Website aufrufst. Hier ein Beispiel:

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

Nutzerstandort festlegen

Google Books respektiert Urheberrechts-, Vertrags- und andere rechtliche Einschränkungen, die mit dem Standort des Endnutzers verbunden sind. Dies kann dazu führen, dass einige Nutzer aus bestimmten Ländern nicht auf Buchinhalte zugreifen können. So sind beispielsweise bestimmte Bücher nur in den USA als Vorschau verfügbar. Für Nutzer in anderen Ländern werden solche Links nicht angezeigt. Daher werden die API-Ergebnisse auf Grundlage der IP-Adresse Ihrer Server- oder Clientanwendung eingeschränkt.

Mit Volumes arbeiten

Eine Suche ausführen

Sie können eine Volume-Suche ausführen, indem Sie eine HTTP-GET-Anfrage an den folgenden URI senden:

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

Diese Anfrage enthält einen einzelnen erforderlichen Parameter:

• q: Nach Volumes suchen, die diesen Textstring enthalten. Es gibt spezielle Suchbegriffe, die Sie in den Suchbegriffen angeben können, um in bestimmten Feldern zu suchen, z. B.:
  • intitle: Gibt Ergebnisse zurück, in denen der auf diesen Suchbegriff folgende Text im Titel enthalten ist.
  • inauthor: gibt Ergebnisse zurück, in denen der auf diesen Suchbegriff folgende Text im Autor gefunden wurde.
  • inpublisher: Gibt Ergebnisse zurück, in denen der auf dieses Keyword folgende Text beim Verlag oder Webpublisher gefunden wurde.
  • subject:: Gibt Ergebnisse zurück, in denen der auf diesen Suchbegriff folgende Text in der Kategorieliste des Bandes aufgeführt ist.
  • isbn:: Gibt Ergebnisse zurück, bei denen der Text nach diesem Suchbegriff die ISBN ist.
  • lccn: gibt Ergebnisse zurück, bei denen der Text nach diesem Suchbegriff die Kontrollnummer der Library of Congress ist.
  • oclc: gibt Ergebnisse zurück, bei denen der Text nach diesem Suchbegriff die Nummer des Online Computer Library Center ist.

Anfragen

Hier ist ein Beispiel für eine Suche nach „Blumen für Algernon“ von Daniel Keyes:

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

Hinweis: Für eine Suche ist keine Authentifizierung erforderlich. Sie müssen also nicht den HTTP-Header Authorization in der GET-Anfrage angeben. Wenn der Aufruf jedoch mit Authentifizierung erfolgt, enthält jedes Volume nutzerspezifische Informationen wie den Kaufstatus.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und den Volume-Ergebnissen:

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
}

Optionale Abfrageparameter

Zusätzlich zu den Standardabfrageparametern können Sie bei einer Volume-Suche die folgenden Suchparameter verwenden.

Downloadformat

Mit dem Parameter download können Sie die zurückgegebenen Ergebnisse auf Volumes mit dem verfügbaren Downloadformat epub beschränken. Dazu setzen Sie auf den Wert epub.

Im folgenden Beispiel wird nach Büchern gesucht, für die ein EPUB-Download verfügbar ist:

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey

Wird gefiltert

Mit dem Parameter filter können Sie die zurückgegebenen Ergebnisse weiter einschränken. Legen Sie dazu einen der folgenden Werte fest:

• partial: gibt Ergebnisse zurück, bei denen mindestens Teile des Textes in der Vorschau angezeigt werden können.
• full: gibt nur Ergebnisse zurück, bei denen der gesamte Text sichtbar ist.
• free-ebooks: gibt nur kostenlose Google E-Books zurück.
• paid-ebooks: gibt nur Google-E-Books mit Preis zurück.
• ebooks: gibt nur Ergebnisse zurück, die kostenpflichtig oder kostenlos sind. Beispiele für Nicht-E-Books sind Publisher-Inhalte, die nur in einer eingeschränkten Vorschau verfügbar sind und nicht zum Verkauf angeboten werden, oder Zeitschriften.

Im folgenden Beispiel werden die Suchergebnisse auf diejenigen eingeschränkt, die als kostenlose E-Books verfügbar sind:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey

Seitenumbruch

Sie können die Volume-Liste paginieren, indem Sie in den Parametern der Anfrage zwei Werte angeben:

• startIndex: die Position in der Sammlung, an der die Sammlung beginnen soll. Der Index des ersten Elements ist 0.
• maxResults: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10 und der maximal zulässige Wert ist 40.

Druckart

Mit dem Parameter printType können Sie die zurückgegebenen Ergebnisse auf einen bestimmten Druck- oder Publikationstyp beschränken. Legen Sie dazu einen der folgenden Werte fest:

• all: Keine Einschränkung auf Drucktyp (Standardeinstellung).
• books: gibt nur Ergebnisse zurück, die Bücher sind.
• magazines: Gibt Ergebnisse zurück, die Zeitschriften sind.

Im folgenden Beispiel werden die Suchergebnisse auf Zeitschriften beschränkt:

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

Projektion

Sie können den Parameter projection mit einem der folgenden Werte verwenden, um einen vordefinierten Satz von Volume-Feldern anzugeben, die zurückgegeben werden sollen:

• full: Gibt alle Volume-Felder zurück.
• lite: Gibt nur bestimmte Felder zurück. In den Feldbeschreibungen, die in der Volume-Referenz mit doppelten Sternchen gekennzeichnet sind, ist angegeben, welche Felder enthalten sind.

Im folgenden Beispiel werden Suchergebnisse mit begrenzten Volumeninformationen zurückgegeben:

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

Sortieren

Standardmäßig gibt eine Anfrage für eine Volume-Suche maxResults-Ergebnisse zurück, wobei maxResults der für die Paginierung verwendete Parameter (siehe oben) ist, sortiert nach Relevanz für die Suchbegriffe.

Sie können die Reihenfolge ändern, indem Sie den Parameter orderBy auf einen der folgenden Werte festlegen:

• relevance: gibt Ergebnisse in der Reihenfolge der Relevanz der Suchbegriffe zurück (Standardeinstellung).
• newest: gibt die Ergebnisse absteigend nach Veröffentlichungsdatum zurück.

Im folgenden Beispiel werden die Ergebnisse nach dem Veröffentlichungsdatum von neu nach alt aufgelistet:

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

Ein bestimmtes Volume abrufen

Sie können Informationen zu einem bestimmten Volume abrufen, indem Sie eine HTTP-GET-Anfrage an den URI der Volume-Ressource senden:

https://www.googleapis.com/books/v1/volumes/volumeId

Ersetzen Sie den Pfadparameter volumeId durch die ID des abzurufenden Volumes. Weitere Informationen zu Volume-IDs finden Sie im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel für eine GET-Anfrage, die ein einzelnes Volume erhält:

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

Hinweis: Das Abrufen von Volume-Informationen erfordert keine Authentifizierung. Sie müssen also nicht den HTTP-Header Authorization mit der GET-Anfrage angeben. Wenn der Aufruf jedoch mit Authentifizierung erfolgt, enthält das Volume nutzerspezifische Informationen wie den Kaufstatus.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der angeforderten Volume-Ressource:

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"
 }
}

Zugriffsinformationen

Der Abschnitt accessInfo ist vor allem bei der Entscheidung, welche Funktionen für ein E-Book verfügbar sind, von Interesse. epub ist ein E-Book im Fließtextformat. Der Abschnitt epub hat die Eigenschaft isAvailable, die angibt, ob diese Art von E-Book verfügbar ist. Es enthält einen Downloadlink, wenn es ein Beispiel für das Buch gibt oder wenn der Nutzer das Buch lesen kann, weil es entweder gekauft wurde oder am Standort des Nutzers öffentlich zugänglich ist. Ein pdf für Google Books gibt eine Version des E-Books mit gescannten Seiten mit ähnlichen Details an, z. B. ob es verfügbar ist, und einen Downloadlink. Google empfiehlt epub-Dateien für E-Reader und Smartphones, da gescannte Seiten auf diesen Geräten möglicherweise schwer zu lesen sind. Wenn kein accessInfo-Abschnitt vorhanden ist, ist der Band nicht als Google-E-Book verfügbar.

Optionale Abfrageparameter

Zusätzlich zu den Standardabfrageparametern können Sie beim Abrufen eines bestimmten Volumes den folgenden Abfrageparameter verwenden.

Projektion

Sie können den Parameter projection mit einem der folgenden Werte verwenden, um einen vordefinierten Satz von Volume-Feldern anzugeben, die zurückgegeben werden sollen:

• full: Gibt alle Volume-Felder zurück.
• lite: Gibt nur bestimmte Felder zurück. In den Feldbeschreibungen, die in der Volume-Referenz mit doppelten Sternchen gekennzeichnet sind, ist angegeben, welche Felder enthalten sind.

Im folgenden Beispiel werden eingeschränkte Volume-Informationen für ein einzelnes Volume zurückgegeben:

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

Mit Bücherregalen arbeiten

Liste der öffentlichen Bücherregale eines Nutzers abrufen

Sie können eine Liste der öffentlichen Bücherregale eines Nutzers abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

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

Ersetzen Sie den Pfadparameter userId durch die ID des Nutzers, dessen Bücherregale Sie abrufen möchten. Weitere Informationen zu Nutzer-IDs finden Sie im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel:

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

Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, musst du den HTTP-Header Authorization nicht in der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste der Bücherregale:

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"
  },
  ...
 ]
}

Optionale Abfrageparameter

Sie können die Standardabfrageparameter verwenden, wenn Sie die Liste der öffentlichen Bücherregale eines Nutzers abrufen.

Ein bestimmtes öffentliches Bücherregal abrufen

Sie können ein bestimmtes öffentliches Bücherregal abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

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

Ersetzen Sie die Pfadparameter userId und shelf durch die IDs, die den Nutzer und das abzurufende Bücherregal angeben. Weitere Informationen finden Sie im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel:

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

Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, musst du den HTTP-Header Authorization nicht in der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Bookshelf-Ressource:

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"
}

Optionale Abfrageparameter

Sie können die Standardabfrageparameter verwenden, wenn Sie ein bestimmtes öffentliches Bücherregal abrufen.

Liste der Bände in einem öffentlichen Bücherregal abrufen

Sie können eine Liste der Volumes im öffentlichen Bücherregal eines Nutzers abrufen. Senden Sie dazu eine HTTP-GET-Anfrage an den URI im folgenden Format:

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

Anfragen

Hier ein Beispiel:

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

Ersetzen Sie die Pfadparameter userId und shelf durch die IDs, die den Nutzer und das abzurufende Bücherregal angeben. Weitere Informationen finden Sie im Abschnitt Google Books-IDs.

Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, musst du den HTTP-Header Authorization nicht in der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste der Bücherregale des Nutzers:

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
}

Optionale Abfrageparameter

Zusätzlich zu den Standardabfrageparametern können Sie beim Abrufen einer Liste von Volumes in einem öffentlichen Bücherregal den folgenden Abfrageparameter verwenden.

Seitenumbruch

Sie können die Volume-Liste paginieren, indem Sie in den Parametern der Anfrage zwei Werte angeben:

• startIndex: die Position in der Sammlung, an der die Sammlung beginnen soll. Der Index des ersten Elements ist 0.
• maxResults: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10 und der maximal zulässige Wert ist 40.

Bücherregale in „Meine Bibliothek“ verwenden

Alle Anfragen unter „Meine Bibliothek“ gelten für die Daten des authentifizierten Nutzers.

Liste meiner Bücherregale abrufen

Sie können eine Liste aller Bücherregale des authentifizierten Nutzers abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

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

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

Hinweis: Der Nutzer muss authentifiziert sein, um eine Liste der Bücherregale unter „Meine Bibliothek“ abzurufen. Daher musst du in der GET-Anfrage den HTTP-Header Authorization angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste aller Bücherregale für den aktuell authentifizierten Nutzer:

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"
  }
 ]
}

Optionale Abfrageparameter

Beim Abrufen der Liste der Bücherregale des authentifizierten Nutzers können Sie die Standardabfrageparameter verwenden.

Liste der Bände in meinem Bücherregal abrufen

Eine Liste der Volumes im Bücherregal des authentifizierten Nutzers können Sie abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

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

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs finden Sie im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

Hinweis: Der Nutzer muss authentifiziert sein, um eine Liste der Bände unter „Meine Bibliothek“ abrufen zu können. Sie müssen also in der GET-Anfrage den HTTP-Header Authorization angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste der Bookshelf-Volumes:

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
}

Optionale Abfrageparameter

Zusätzlich zu den Standardabfrageparametern können Sie den folgenden Abfrageparameter verwenden, wenn Sie eine Liste von Bänden in einem der Bücherregale des authentifizierten Nutzers abrufen.

Seitenumbruch

Sie können die Volume-Liste paginieren, indem Sie in den Parametern der Anfrage zwei Werte angeben:

• startIndex: die Position in der Sammlung, an der die Sammlung beginnen soll. Der Index des ersten Elements ist 0.
• maxResults: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10.

Band zu meinem Bücherregal hinzufügen

Um dem Bücherregal des authentifizierten Nutzers ein Volume hinzuzufügen, senden Sie eine HTTP-POST-Anfrage an den URI im folgenden Format:

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

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs finden Sie im Abschnitt Google Books-IDs.

Die Anfrage enthält einen einzigen erforderlichen Suchparameter:

• volumeId: Die ID des Volumes. Weitere Informationen zu Band-IDs finden Sie im Abschnitt Google Books-IDs.

Anfragen

Hier ist ein Beispiel für das Hinzufügen von "Blumen für Algernon" zum Bücherregal "Favoriten":

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

Hinweis: Der Nutzer muss authentifiziert sein, um Änderungen an einem Bücherregal vornehmen zu können. Daher musst du den HTTP-Header Authorization mit der POST-Anfrage angeben. Bei diesem POST sind jedoch keine Daten erforderlich.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 204 No Content.

Optionale Abfrageparameter

Sie können die Standardabfrageparameter verwenden, wenn Sie einem der Bücherregale des authentifizierten Nutzers einen Band hinzufügen.

Einen Band aus meinem Bücherregal entfernen

Um ein Volume aus dem Bücherregal des authentifizierten Nutzers zu entfernen, senden Sie eine HTTP-POST-Anfrage an den URI im folgenden Format:

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

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs finden Sie im Abschnitt Google Books-IDs.

Die Anfrage enthält einen einzigen erforderlichen Suchparameter:

• volumeId: Die ID des Volumes. Weitere Informationen zu Band-IDs finden Sie im Abschnitt im Abschnitt Google Books-IDs.

Anfragen

Hier ist ein Beispiel, wie Sie „Flowers for Algernon“ aus dem Bücherregal „Favoriten“ entfernen:

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

Hinweis: Der Nutzer muss authentifiziert sein, um Änderungen an einem Bücherregal vornehmen zu können. Daher musst du den HTTP-Header Authorization mit der POST-Anfrage angeben. Bei diesem POST sind jedoch keine Daten erforderlich.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode 204 No Content.

Optionale Abfrageparameter

Sie können die Standardabfrageparameter verwenden, wenn Sie einen Band aus einem der Bücherregale des authentifizierten Nutzers entfernen.

Alle Bände aus meinem Bücherregal löschen

Wenn Sie alle Volumes aus dem Bücherregal des authentifizierten Nutzers entfernen möchten, senden Sie eine HTTP-POST-Anfrage an den URI im folgenden Format:

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

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs finden Sie im Abschnitt Google Books-IDs.

Anfragen

Hier ist ein Beispiel zum Löschen des Bücherregals "Favoriten":

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
  

Hinweis: Der Nutzer muss authentifiziert sein, um Änderungen an einem Bücherregal vornehmen zu können. Daher musst du den HTTP-Header Authorization mit der POST-Anfrage angeben. Bei diesem POST sind jedoch keine Daten erforderlich.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode 204 No Content.

Optionale Abfrageparameter

Sie können die Standardabfrageparameter verwenden, wenn Sie alle Bände aus einem der Bücherregale des authentifizierten Nutzers löschen.

Referenz zu Abfrageparametern

Die Abfrageparameter, die Sie mit der Books API verwenden können, sind in diesem Abschnitt zusammengefasst.Alle Parameterwerte müssen URL-codiert sein.

Standardabfrageparameter

Abfrageparameter, die für alle Books API-Vorgänge gelten, sind unter Systemparameter dokumentiert.

API-spezifische Abfrageparameter

Anfrageparameter, die nur für bestimmte Vorgänge in der Books API gelten, sind in der folgenden Tabelle zusammengefasst.