Inhalt
Einführung
Dieses Dokument richtet sich an Entwickler, die Anwendungen schreiben 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 so im Web leichter auffindbar zu machen. Mit der Books API kannst du diese Inhalte suchen und darauf zugreifen sowie Personalisierungen für diese Inhalte erstellen und anzeigen.
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
Alle Anfragen, die Ihre Anwendung an die Books API sendet, müssen 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. eine Anfrage nach privaten Daten einer Person), muss die Anwendung ein OAuth 2.0-Token mit der Anfrage bereitstellen. Die Anwendung kann auch den API-Schlüssel bereitstellen, muss dies jedoch nicht.
- 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:
- 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.
- Aktivieren Sie die Books API in der Google API Console. Überspringe diesen Schritt, falls die API nicht in der API Console aufgeführt ist.
- Wenn deine Anwendung Zugriff auf Nutzerdaten benötigt, bittet sie Google um einen bestimmten Zugriffsbereich.
- Dem Nutzer wird von Google ein Zustimmungsbildschirm angezeigt, auf dem er gebeten wird, deine Anwendung dazu zu autorisieren, einige seiner Daten abzufragen.
- Wenn der Nutzer zustimmt, erhält deine Anwendung von Google ein kurzlebiges Zugriffstoken.
- Die Anwendung fordert Nutzerdaten an, wobei das Zugriffstoken an die Anfrage angehängt wird.
- 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.
Hier 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 muss eine Kennung erfolgen. Diese kann ein API-Schlüssel oder ein Zugriffstoken sein.
So erhalten Sie einen API-Schlüssel:
- Öffnen Sie in der API Console die Seite „Anmeldedaten“.
-
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 erforderliche API-Schlüssel noch nicht vorhanden ist, erstellen Sie einen API-Schlüssel in der Console, indem Sie auf Anmeldedaten erstellen > API-Schlüssel klicken. Sie können den Schlüssel einschränken, bevor Sie ihn in der Produktionsumgebung 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
Sie müssen ID-Felder für bestimmte API-Methodenaufrufe angeben. In Google Books werden drei Arten von IDs verwendet:
- Volume-IDs: eindeutige Strings für jedes Band, das Google Books bekannt ist. Ein Beispiel für eine Volume-ID ist
_LettPDhwR0C
. Sie können die API verwenden, um die Volume-ID abzurufen. Stellen Sie dazu eine Anfrage, bei der eine Volume-Ressource zurückgegeben wird. Sie finden die Volume-ID im Feldid
. - Bücherregal-IDs: Numerische Werte, die einem Bücherregal in der Bibliothek eines Nutzers zugewiesen werden. Google bietet für jeden Nutzer vordefinierte Regale mit den folgenden IDs:
- Favoriten: 0
- Gekauft: 1
- Lesevorgang: 2
- Aktuell gelesen: 3
- Gelesen: 4
- Überprüft: 5
- Zuletzt aufgerufen: 6
- Meine E-Books: 7
- Bücher für dich: 8 Wenn wir keine Empfehlungen für den Nutzer haben, ist dieser Bereich nicht vorhanden.
id
. - Nutzer-IDs: Eindeutige numerische Werte, die jedem Nutzer zugewiesen sind. Diese Werte müssen nicht unbedingt mit dem ID-Wert übereinstimmen, der in anderen Google-Diensten verwendet wird. Derzeit kann die User-ID nur durch Extrahieren aus dem SelfLink in einer mit einer authentifizierten Anfrage abgerufenen Bücherregalressource abgerufen werden. Nutzer können ihre eigene Nutzer-ID auch über die Google Books-Website erhalten. Ein Nutzer kann die Nutzer-ID nicht über die API oder die Google Play Bücher-Website abrufen. Der andere Nutzer muss diese Informationen beispielsweise per E-Mail weitergeben.
IDs auf der Google Books-Website
Die IDs, die Sie mit der Books API verwenden, sind die gleichen wie auf der Google Books-Website.
- Volume-ID
Wenn Sie ein bestimmtes Volume auf der Website aufrufen, finden Sie 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 die Bücherregal-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
Wenn du deine Mediathek auf der Website aufrufst, findest du die User-ID im URL-Parameter
uid
. Hier ein Beispiel:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Standort des Nutzers festlegen
Google Books berücksichtigt Urheberrechte, Verträge und andere rechtliche Einschränkungen, die mit dem Standort des Endnutzers in Verbindung stehen. Deshalb können einige Nutzer möglicherweise aus bestimmten Ländern nicht auf Buchinhalte zugreifen. Beispielsweise können bestimmte Bücher nur in den USA in der Vorschau angesehen werden. Für Nutzer in anderen Ländern werden solche Vorschaulinks nicht angezeigt. Daher sind die API-Ergebnisse auf Grundlage der IP-Adresse Ihres Servers oder Ihrer Clientanwendung beschränkt.
Mit Volumes arbeiten
Suche durchführen
Sie können eine Volume-Suche durchführen, indem Sie eine HTTP-GET
-Anfrage an den folgenden URI senden:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Diese Anfrage hat einen einzigen 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, bei denen der Text nach diesem Keyword im Titel gefunden wird.inauthor:
Gibt Ergebnisse zurück, bei denen der Autor nach diesem Suchbegriff im Autor gefunden wurde.inpublisher:
Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword im Publisher gefunden wurde.subject:
Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword in der Kategorieliste des Volumes 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 Nummer des Online Computer Library Centers ist.
Anfragen
Hier ein Beispiel für die Suche nach Daniel Keyes&#t;Flowers for Algernon":
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 daher den Authorization
-HTTP-Header nicht mit der GET
-Anfrage angeben. Wenn der Aufruf jedoch mit Authentifizierung erfolgt, enthält jedes Volume nutzerspezifische Informationen, z. B. 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 standardmäßigen Abfrageparametern können Sie die folgenden Suchparameter verwenden, um eine Volumensuche durchzuführen.
Downloadformat
Verwenden Sie den Parameter download
, um die zurückgegebenen Ergebnisse auf Volumes mit dem verfügbaren Downloadformat epub
einzuschränken. Legen Sie dazu den
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
Sie können den Parameter filter
verwenden, um die zurückgegebenen Ergebnisse weiter einzuschränken. Legen Sie dazu einen der folgenden Werte fest:
partial
: Gibt Ergebnisse zurück, bei denen mindestens Textabschnitte in der Vorschau angesehen werden können.full
: Gibt nur Ergebnisse zurück, bei denen der gesamte Text sichtbar ist.free-ebooks
: Gibt nur Ergebnisse zurück, die bei Google E-Books kostenlos sind.paid-ebooks
: gibt nur Ergebnisse zurück, bei denen es sich um E-Books von Google mit einem bestimmten Preis handelt.ebooks
: Gibt nur Ergebnisse zurück, die Google Books sind (kostenpflichtig oder kostenlos). Beispiele für Nicht-E-Books sind Inhalte von Verlagen und Webpublishern, die in einer eingeschränkten Vorschau verfügbar und nicht zum Verkauf verfügbar sind, oder Zeitschriften.
Im folgenden Beispiel werden Suchergebnisse auf die kostenlosen Bücher beschränkt:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Seitenumbruch
Sie können die Volumes-Liste paginieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:
startIndex
: die Position in der Sammlung, an der der Ausgangspunkt 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
Sie können den Parameter printType
verwenden, um die zurückgegebenen Ergebnisse auf einen bestimmten Druck- oder Publikationstyp zu beschränken. Legen Sie dazu einen der folgenden Werte fest:
all
– schränkt nicht nach Drucktyp ein (Standardeinstellung).books
: Gibt nur Ergebnisse von Büchern zurück.magazines
: Gibt Ergebnisse zurück, die Zeitschriften sind.
Im folgenden Beispiel werden Suchergebnisse auf Zeitschriften beschränkt:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Projection
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. Welche Felder enthalten sind, entnehmen Sie der Feldbeschreibung mit doppelten Sternchen.
Im folgenden Beispiel werden Suchergebnisse mit begrenztem Volumen zurückgegeben:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Sortieren
Standardmäßig gibt eine Volume-Suchanfrage Ergebnisse vom Typ maxResults
zurück, wobei maxResults
der Parameter für die Paginierung (siehe oben) ist, sortiert nach der Relevanz für Suchbegriffe.
Sie können die Reihenfolge ändern, indem Sie den Parameter orderBy
auf einen dieser Werte festlegen:
relevance
: Gibt Ergebnisse in der Reihenfolge der Relevanz von Suchbegriffen zurück (Standardeinstellung).newest
: Gibt Ergebnisse in der Reihenfolge vom aktuellsten bis zum zuletzt veröffentlichten zurück.
Im folgenden Beispiel werden die Ergebnisse nach Veröffentlichungsdatum (neueste zuerst) aufgelistet:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Bestimmtes Volume abrufen
Sie können Informationen für ein bestimmtes Volume abrufen. Senden Sie dazu eine HTTP-GET
-Anfrage an den URI der Volume-Ressource:
https://www.googleapis.com/books/v1/volumes/volumeId
Ersetzen Sie den Pfadparameter volumeId
durch die ID des abzurufenden Volumes. Weitere Informationen zu Volume-IDs findest du 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 daher den Authorization
-HTTP-Header nicht 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 von besonderem Interesse, um zu bestimmen, welche Funktionen für ein E-Book verfügbar sind. epub
ist ein E-Book mit Fließtextformat und im Abschnitt epub
gibt es die Property isAvailable
, die angibt, ob diese Art von E-Book verfügbar ist.
Wenn es eine Leseprobe für das Buch gibt oder der Nutzer es entweder lesen kann, weil es gekauft wurde, oder weil es sich um eine urheberrechtsfreie Domain am Standort des Nutzers handelt, wird ein Downloadlink angezeigt. Ein pdf
für Google-Bücher gibt eine gescannte Seitenversion des E-Books 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 das Volume nicht als Google-E-Book verfügbar.
Optionale Abfrageparameter
Zusätzlich zu den Standard-Abfrageparametern können Sie beim Abrufen eines bestimmten Volumes den folgenden Abfrageparameter verwenden.
Projection
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. Welche Felder enthalten sind, entnehmen Sie der Feldbeschreibung mit doppelten Sternchen.
Im folgenden Beispiel werden Informationen zu begrenztem Volumen 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 findest du 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, müssen Sie den HTTP-Header Authorization
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 Standard-Abfrageparameter verwenden, wenn Sie die Liste der öffentlichen Bücherregale eines Nutzers abrufen.
Bestimmtes öffentliches Bücherregal abrufen
Zum Abrufen eines bestimmten öffentlichen Bücherregales senden Sie eine HTTP-GET
-Anfrage an den URI im folgenden Format:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Ersetzen Sie die Pfadparameter userId und shelf durch die IDs der Nutzer und des Regals, das abgerufen werden soll. Weitere Informationen findest du 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, müssen Sie den HTTP-Header Authorization
nicht mit der GET
-Anfrage angeben.
Antwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK
und der Bücherregal-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 Standard-Abfrageparameter verwenden, wenn ein bestimmtes öffentliches Bücherregal abgerufen wird.
Liste von Bänden in einem öffentlichen Bücherregal abrufen
Sie können eine Liste der Volumes im öffentlichen Bücherregal eines Nutzers abrufen, indem Sie eine HTTP-GET
-Anfrage an den URI im folgenden Format senden:
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 der Nutzer und des Regals, das abgerufen werden soll. Weitere Informationen findest du im Abschnitt Google Books-IDs.
Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den HTTP-Header Authorization
nicht mit der GET
-Anfrage angeben.
Antwort
Wenn die Anfrage erfolgreich ist, antwortet der Server mit einem 200 OK
-HTTP-Statuscode 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 standardmäßigen Abfrageparametern können Sie beim Abrufen einer Liste von Volumes in einem öffentlichen Bücherregal den folgenden Abfrageparameter verwenden.
Seitenumbruch
Sie können die Volumes-Liste paginieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:
startIndex
: die Position in der Sammlung, an der der Ausgangspunkt 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" bearbeiten
Alle Anfragen aus „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 von Bücherregalen abrufen zu können. Daher musst du 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 der Liste aller Bücherregale für den aktuellen 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
Sie können die Standard-Abfrageparameter verwenden, wenn Sie die Liste der Bücherregale des authentifizierten Nutzers abrufen.
Liste der Bände in meinem Bücherregal abrufen
Sie können eine Liste der Volumes im authentifizierten Bücherregal des authentifizierten Nutzers abrufen. Senden Sie dazu eine HTTP-GET
-Anfrage an den URI im folgenden Format:
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 findest du 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 von Volumes in „Meine Bibliothek“ abzurufen. Daher musst du 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-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 standardmäßigen Abfrageparametern können Sie den folgenden Abfrageparameter verwenden, wenn Sie eine Liste von Bänden in einem der authentifizierten Bücherregale eines Nutzers abrufen.
Seitenumbruch
Sie können die Volumes-Liste paginieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:
startIndex
: die Position in der Sammlung, an der der Ausgangspunkt beginnen soll. Der Index des ersten Elements ist 0.maxResults
: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10.
Hinzufügen eines Bandes zu meinem Bücherregal
Wenn Sie dem Bücherregal des authentifizierten Nutzers ein Volume hinzufügen möchten, 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 findest du im Abschnitt Google Books-IDs.
Die Anfrage enthält nur einen erforderlichen Abfrageparameter:
volumeId
: Die ID des Volumes. Weitere Informationen zu Volume-IDs findest du im Abschnitt Google Books-IDs.
Anfragen
Hier ist ein Beispiel, wie Sie „Blumen für Algernon“ zum 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. Daher müssen Sie den Authorization
-HTTP-Header mit der POST
-Anfrage angeben. Für dieses 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 Standard-Abfrageparameter verwenden, wenn Sie einem der Bücherregale des authentifizierten Nutzers ein Volume hinzufügen.
Volume aus meinem Bücherregal entfernen
Zum Entfernen eines Volumes aus dem Bücherregal des authentifizierten Nutzers senden Sie 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 Bücherregal-IDs findest du im Abschnitt Google Books-IDs.
Die Anfrage enthält nur einen erforderlichen Abfrageparameter:
volumeId
: Die ID des Volumes. Weitere Informationen zu Volume-IDs findest du im Abschnitt Google Books-IDs.
Anfragen
Hier ein Beispiel für das Entfernen von Blumen für Algernon aus dem Bücherregal „Favoriten“:
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. Daher müssen Sie den Authorization
-HTTP-Header mit der POST
-Anfrage angeben. Für dieses 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 Standard-Abfrageparameter verwenden, wenn Sie ein Volume aus einem der authentifizierten Bücherregale entfernen.
Alle Bände aus meinem Bücherregal löschen
Wenn Sie alle Volumes aus dem authentifizierten Bücherregal entfernen möchten, senden Sie eine HTTP-POST
im folgenden Format an den URI:
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 findest du im Abschnitt Google Books-IDs.
Anfragen
So löschen Sie das Bücherregal „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. Daher müssen Sie den Authorization
-HTTP-Header mit der POST
-Anfrage angeben. Für dieses 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 Standard-Abfrageparameter verwenden, wenn Sie alle Bände aus einem der Bücherregale des authentifizierten Nutzers löschen.
Abfrageparameterreferenz
Die Suchparameter, 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.
Parameter | Bedeutung | Hinweise | Geltungsbereich |
---|---|---|---|
download |
Auf Downloads anhand der Downloadverfügbarkeit beschränken |
|
|
filter |
Suchergebnisse nach Volume-Typ und Verfügbarkeit filtern |
|
|
langRestrict |
Beschränkt die zurückgegebenen Volumes auf diejenigen, die mit der angegebenen Sprache getaggt sind. |
|
|
maxResults |
Die maximale Anzahl von Elementen, die mit dieser Anfrage zurückgegeben werden sollen. |
|
|
orderBy |
Reihenfolge der Ergebnisse der Volumensuche. |
|
|
printType |
Auf Bücher oder Zeitschriften beschränken |
|
|
projection |
Beschränken Sie Volumeninformationen, die auf eine Teilmenge von Feldern zurückgegeben werden. |
|
|
q |
Volltext-Abfragestring. |
|
|
startIndex |
Die Position in der Sammlung, an der die Liste der Ergebnisse gestartet werden soll. |
|
|
volumeId |
Kennzeichnet ein mit der Anfrage verknüpftes Volume. |
|