API verwenden

Inhalt

Einführung

Dieses Dokument richtet sich an Entwickler, die Anwendungen erstellen möchten, die mit der Books API interagieren können. Google Books hat es sich zur Aufgabe gemacht, die Buchinhalte der Welt zu digitalisieren und im Web leichter auffindbar zu machen. Mit der Books API können Sie nach diesen Inhalten suchen und darauf zugreifen sowie personalisierte Inhalte erstellen und ansehen.

Wenn Sie mit den Google Books-Konzepten nicht vertraut sind, sollten Sie den Artikel Einstieg lesen, bevor Sie mit dem Codieren beginnen.

Anfragen autorisieren und Ihre Anwendung identifizieren

Jede Anfrage, die Ihre Anwendung an die Books API sendet, muss Ihre Anwendung gegenüber 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, beispielsweise für private Daten einer Person, muss die Anwendung ein OAuth 2.0-Token mit der Anfrage bereitstellen. Die Anwendung kann auch den API-Schlüssel bereitstellen, dies ist jedoch nicht notwendig.
• 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 in Bezug auf nicht öffentliche Nutzerdaten müssen durch einen 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 OAuth 2.0-Bereich 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 für öffentliche Daten müssen eine Kennzeichnung enthalten. Das 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 für Ihr Projekt geeignete Anmeldedaten:

   • 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 existiert, können Sie ihn in der Konsole erstellen, indem Sie auf Anmeldedaten erstellen  > API-Schlüssel klicken. Sie können Einschränkungen für diesen Schlüssel festlegen, bevor Sie ihn in der Produktion einsetzen. Klicken Sie dazu auf Schlüssel einschränken und wählen Sie dann 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

Sie müssen ID-Felder bei bestimmten API-Methodenaufrufen angeben. In Google Books werden drei Arten von IDs verwendet:

• Band-IDs: Eindeutige Strings, die jedem Band zugewiesen werden, der Google Books bekannt ist. Ein Beispiel für eine Volume-ID ist _LettPDhwR0C. Sie können die Volume-ID mithilfe der API abrufen, indem Sie eine Anfrage stellen, die eine Volume-Ressource zurückgibt. Die Volume-ID finden Sie im Feld id.
• Bookshelf-IDs: Numerische Werte, die einem Bücherregal in der Mediathek eines Nutzers zugewiesen werden. Google stellt jedem Nutzer einige vordefinierte Bereiche mit den folgenden IDs zur Verfügung:
  • Favoriten: 0
  • Gekauft: 1
  • Zu lesen: 2
  • Aktuell gelesen: 3
  • Gelesen: 4
  • Überprüft: 5
  • Zuletzt angesehen: 6
  • Meine E-Books: 7
  • Bücher für mich: 8 Wenn wir keine Empfehlungen für den Nutzer haben, existiert dieses Regal nicht.
  Benutzerdefinierte Bereiche haben IDs, die größer als 1.000 sind. Eine 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 unterschiedliche Bücherregale bezieht. Sie können die Bookshelf-ID mithilfe der API abrufen, indem Sie eine Anfrage stellen, die eine Bookshelf-Ressource zurückgibt. Die Bookshelf-ID finden Sie im Feld id.
• Nutzer-IDs: Eindeutige numerische Werte, die jedem Nutzer zugewiesen sind. Diese Werte stimmen nicht unbedingt mit den ID-Werten überein, die in anderen Google-Diensten verwendet werden. Derzeit kann die Nutzer-ID nur aus dem Selflink in einer Bookshelf-Ressource extrahiert werden, die mit einer authentifizierten Anfrage abgerufen wurde. Nutzer können ihre eigene Nutzer-ID auch auf der Bücher-Website abrufen. Ein Nutzer kann die Nutzer-ID eines anderen Nutzers nicht über die API oder die Google Books-Website abrufen. Der andere Nutzer muss diese Informationen ausdrücklich freigeben, z. B. per E-Mail.

IDs auf der Google Books-Website

Die IDs, die Sie mit der Books API verwenden, sind dieselben IDs, die auf der Website Google Books verwendet werden.

• Volume-ID
  

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

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

• Bookshelf-ID
  

  Wenn du dir eine bestimmte Leseliste auf der Website ansiehst, findest du die ID der Leseliste 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
  

  In der Bibliothek auf der Website finden Sie die Nutzer-ID im URL-Parameter uid. Hier ein Beispiel:

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

Nutzerstandort festlegen

Google Books hält Urheberrechte, Vertragsbedingungen und andere rechtliche Einschränkungen ein, die mit dem Standort des Endnutzers verbunden sind. Daher können einige Nutzer möglicherweise nicht auf Buchinhalte aus bestimmten Ländern zugreifen. Bestimmte Bücher können beispielsweise nur in den USA in der Vorschau angesehen werden. Für Nutzer in anderen Ländern werden solche Vorschaulinks nicht angezeigt. Daher werden die API-Ergebnisse basierend auf der IP-Adresse Ihrer Server- oder Clientanwendung eingeschränkt.

Mit Volumes arbeiten

Suche ausführen

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

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

Für diese Anfrage ist nur ein Parameter erforderlich:

• q: Es wird nach Volumes gesucht, die diesen Textstring enthalten. Es gibt spezielle Keywords, die Sie in den Suchbegriffen angeben können, um in bestimmten Feldern zu suchen, z. B.:
  • intitle: Gibt Ergebnisse zurück, in denen der Text nach diesem Keyword im Titel gefunden wird.
  • inauthor: Gibt Ergebnisse zurück, in denen der Text nach diesem Keyword im Autor gefunden wird.
  • inpublisher: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword im Publisher gefunden wird.
  • subject: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword in der Kategorieliste des Bandes aufgeführt ist.
  • isbn: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die ISBN-Nummer ist.
  • lccn: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die Library of Congress Control Number ist.
  • oclc: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die OCLC-Nummer ist.

Anfrage

Hier ein Beispiel für die Suche nach „Flowers for Algernon“ von Daniel Keyes:

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

Hinweis: Für die Suche ist keine Authentifizierung erforderlich. Du musst also den Authorization-HTTP-Header nicht mit der GET-Anfrage senden. 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 Ergebnissen für die Lautstärke:

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 der Suche nach Datenträgern die folgenden Abfrageparameter verwenden.

Downloadformat

Mit dem Parameter download können Sie die zurückgegebenen Ergebnisse auf Volumes beschränken, für die das Downloadformat epub verfügbar ist. Legen Sie dazu auf den Wert epub fest.

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

Filtern

Mit dem Parameter filter können Sie die zurückgegebenen Ergebnisse weiter eingrenzen, indem Sie einen der folgenden Werte festlegen:

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

Im folgenden Beispiel werden die Suchergebnisse auf Titel beschrä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 Liste der Bände paginatisieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:

• startIndex: Die Position in der Sammlung, an der begonnen werden soll. Der Index des ersten Artikels ist 0.
• maxResults: Maximale Anzahl der zurückzugebenden Ergebnisse. Der Standardwert ist 10 und der maximal zulässige Wert ist 40.

Drucktyp

Mit dem Parameter printType können Sie die zurückgegebenen Ergebnisse auf einen bestimmten Druck- oder Publikationstyp beschränken, indem Sie einen der folgenden Werte festlegen:

• all – Beschränkt nicht nach Drucktyp (Standardeinstellung).
• books: Es werden nur Ergebnisse zurückgegeben, die Bücher sind.
• magazines – Gibt Ergebnisse zurück, die Magazine 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 eine vordefinierte Gruppe von Volume-Feldern anzugeben, die zurückgegeben werden sollen:

• full: Gibt alle Volume-Felder zurück.
• lite: Es werden nur bestimmte Felder zurückgegeben. Welche Felder enthalten sind, sehen Sie in den Feldbeschreibungen, die in der Volume-Referenz mit doppelten Sternchen gekennzeichnet sind.

Im folgenden Beispiel werden Suchergebnisse mit eingeschränkten Informationen zum Volumen zurückgegeben:

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

Sortieren

Standardmäßig werden bei einer Suchanfrage für Datenträger maxResults Ergebnisse zurückgegeben, wobei maxResults der Parameter ist, der oben für die Paginierung verwendet wird. Die Ergebnisse werden nach Relevanz für die Suchbegriffe sortiert.

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

• relevance – Die Ergebnisse werden in der Reihenfolge der Relevanz der Suchbegriffe zurückgegeben (Standardeinstellung).
• newest – Die Ergebnisse werden in der Reihenfolge der letzten Veröffentlichung zurückgegeben.

Im folgenden Beispiel sind die Ergebnisse nach Veröffentlichungsdatum sortiert, vom neuesten zum ältesten:

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

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 Band-IDs finden Sie im Abschnitt Google Books-IDs.

Anfrage

Hier ein Beispiel für eine GET-Anfrage, mit der ein einzelnes Volume abgerufen wird:

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

Hinweis: Für das Abrufen von Volumeninformationen ist keine Authentifizierung erforderlich. Sie müssen also keinen Authorization-HTTP-Header mit der GET-Anfrage angeben. Wenn der Aufruf jedoch mit Authentifizierung erfolgt, enthält „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 Bereich accessInfo ist besonders interessant, um festzustellen, welche Funktionen für ein E-Book verfügbar sind. Ein epub ist ein E-Book im Format „Dynamische Textanpassung“. Der Bereich epub enthält das Attribut isAvailable, das angibt, ob diese Art von E-Book verfügbar ist. Ein Downloadlink ist vorhanden, wenn es ein Sample für das Buch gibt oder der Nutzer das Buch lesen kann, weil er es gekauft hat oder es sich an seinem Standort in der öffentlichen Domain befindet. Ein pdf für Google Bücher steht für eine Version des E-Books mit gescannten Seiten mit ähnlichen Details wie Verfügbarkeit und Downloadlink. Google empfiehlt epub-Dateien für eReader und Smartphones, da gescannte Seiten auf diesen Geräten möglicherweise schwer zu lesen sind. Wenn kein Abschnitt accessInfo vorhanden ist, ist das Buch nicht als Google-E-Book verfügbar.

Optionale Abfrageparameter

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

Projektion

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

• full: Gibt alle Volume-Felder zurück.
• lite: Es werden nur bestimmte Felder zurückgegeben. Welche Felder enthalten sind, sehen Sie in den Feldbeschreibungen, die in der Volume-Referenz mit doppelten Sternchen gekennzeichnet sind.

Im folgenden Beispiel werden eingeschränkte Informationen zu einem einzelnen 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 Leselisten Sie abrufen möchten. Weitere Informationen zu Nutzer-IDs finden Sie im Abschnitt Google Books-IDs.

Anfrage

Hier ein Beispiel:

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

Da ein Nutzer nicht authentifiziert werden muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den Authorization-HTTP-Header nicht mit 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, um die Liste der öffentlichen Bücherregale eines Nutzers abzurufen.

Bestimmte öffentliche Bücherwand abrufen

Sie können eine bestimmte öffentliche Bücherei 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 Bücherregal angeben, das Sie abrufen möchten. Weitere Informationen finden Sie im Abschnitt Google Books-IDs.

Anfrage

Hier ein Beispiel:

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

Da ein Nutzer nicht authentifiziert werden muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den Authorization-HTTP-Header nicht mit der GET-Anfrage angeben.

Antwort

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

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, um eine bestimmte öffentliche Leseliste abzurufen.

Liste der Bände in einer öffentlichen Bücherei abrufen

Sie können eine Liste der Bände auf der öffentlichen Bücherwand eines Nutzers abrufen, indem Sie eine HTTP-GET-Anfrage an einen URI im folgenden Format senden:

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

Anfrage

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 Bücherregal angeben, das Sie abrufen möchten. Weitere Informationen finden Sie im Abschnitt Google Books-IDs.

Da ein Nutzer nicht authentifiziert werden muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den Authorization-HTTP-Header nicht mit der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste der Leselisten 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 den folgenden Abfrageparameter verwenden, um eine Liste der Bände in einem öffentlichen Bücherregal abzurufen.

Seitenumbruch

Sie können die Liste der Bände paginatisieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:

• startIndex: Die Position in der Sammlung, an der begonnen werden soll. Der Index des ersten Artikels ist 0.
• maxResults: Maximale Anzahl der zurückzugebenden Ergebnisse. Der Standardwert ist 10 und der maximal zulässige Wert ist 40.

Bücherregale in „Meine Bibliothek“ verwenden

Alle Anfragen für „Meine Bibliothek“ beziehen sich auf 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

Anfrage

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 in „Meine Bibliothek“ abzurufen. Daher musst du den Authorization-HTTP-Header mit der GET-Anfrage angeben.

Antwort

Ist die Anfrage erfolgreich, gibt der Server den HTTP-Statuscode 200 OK und die Liste aller Bücherregale für den aktuell authentifizierten Nutzer zurück:

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

Sie können die Standardabfrageparameter verwenden, um die Liste der Bücherregale des authentifizierten Nutzers abzurufen.

Liste der Bücher auf meinem Bücherregal abrufen

Du kannst eine Liste der Bände auf dem Bücherregal des authentifizierten Nutzers abrufen, indem du eine HTTP-GET-Anfrage an den URI im folgenden Format sendest:

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

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

Anfrage

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 in „Meine Bibliothek“ abzurufen. Du musst also den Authorization-HTTP-Header mit der GET-Anfrage angeben.

Antwort

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

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, um eine Liste der Bände in einem der Bücherregale des authentifizierten Nutzers abzurufen.

Seitenumbruch

Sie können die Liste der Bände paginatisieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:

• startIndex: Die Position in der Sammlung, an der begonnen werden soll. Der Index des ersten Artikels ist 0.
• maxResults: Maximale Anzahl der zurückzugebenden Ergebnisse. Der Standardwert ist 10.

Meiner Bookshelf ein Buch hinzufügen

Wenn du dem Bücherregal des authentifizierten Nutzers ein Buch hinzufügen möchtest, sende 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 Bookshelf-IDs finden Sie im Abschnitt Google Books-IDs.

Die Anfrage enthält einen einzelnen erforderlichen Abfrageparameter:

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

Anfrage

Hier ist ein Beispiel, wie Sie „Blumen für Algernon“ dem Bücherregal „Favoriten“ hinzufügen:

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 vorzunehmen. Du musst also den Authorization-HTTP-Header mit der POST-Anfrage senden. Für diese 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 ein Buch hinzufügen.

Band aus der Bücherwand entfernen

Wenn du ein Buch aus dem Bücherregal des authentifizierten Nutzers entfernen möchtest, sende eine HTTP-POST 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 Bookshelf-IDs finden Sie im Abschnitt Google Books-IDs.

Die Anfrage enthält einen einzelnen erforderlichen Abfrageparameter:

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

Anfrage

Hier ist ein Beispiel, wie Sie „Blumen für 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 vorzunehmen. Du musst also den Authorization-HTTP-Header mit der POST-Anfrage senden. Für diese 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 ein Buch aus einem der Bücherregale des authentifizierten Nutzers entfernen möchten.

Alle Bände aus meinem Bücherregal entfernen

Wenn du alle Bände aus dem Bücherregal des authentifizierten Nutzers entfernen möchtest, sende eine HTTP-POST 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 Bookshelf-IDs finden Sie im Abschnitt Google Books-IDs.

Anfrage

Hier ein Beispiel zum Leeren 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 vorzunehmen. Du musst also den Authorization-HTTP-Header mit der POST-Anfrage senden. Für diese POST sind jedoch keine Daten erforderlich.

Antwort

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

Optionale Abfrageparameter

Du kannst die Standardabfrageparameter verwenden, um alle Bände aus den Bücherregalen eines authentifizierten Nutzers zu entfernen.

Suchparameterreferenz

In diesem Abschnitt werden die Suchparameter zusammengefasst, die Sie mit der Books API verwenden können. 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

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