In diesem Dokument werden die Hintergrundkenntnisse beschrieben, die Sie zur Verwendung der Google Books API benötigen.
Einleitung
Dieses Dokument richtet sich an Entwickler, die Anwendungen schreiben möchten, die mit der Google Books API interagieren können. Google Books hat die Vision, die Bücher dieser Welt zu digitalisieren. Mit der Google Books API können Sie Inhalte suchen sowie die persönliche Bibliothek eines authentifizierten Nutzers organisieren und auch ändern.
Hinweis
Google-Konto erstellen
Sie benötigen ein Google-Konto, um Tests durchzuführen. Wenn Sie bereits ein Testkonto haben, sind Sie startklar. Sie können die Benutzeroberfläche von Google Books aufrufen, um Ihre Testdaten einzurichten, zu bearbeiten oder aufzurufen.
Google Books kennenlernen
Wenn Sie mit den Konzepten von Google Books nicht vertraut sind, sollten Sie dieses Dokument lesen und mit der Benutzeroberfläche experimentieren, bevor Sie mit dem Programmieren beginnen. In diesem Dokument wird davon ausgegangen, dass Sie mit Webprogrammierungskonzepten und Webdatenformaten vertraut sind.
Weitere Informationen zum Autorisieren von Anfragen und zum Identifizieren Ihrer Anwendung
Wenn deine Anwendung private Daten anfordert, muss die Anfrage von einem authentifizierten Nutzer autorisiert werden, der Zugriff auf diese Daten hat.
Insbesondere werden alle Vorgänge unter "Meine Bibliothek" in der Google Books API als privat erachtet und erfordern eine Authentifizierung und Autorisierung. Darüber hinaus können alle Vorgänge, die Google Books-Daten ändern, nur von dem Nutzer ausgeführt werden, dem diese Daten gehören.
Wenn Ihre Anwendung öffentliche Daten anfordert, muss die Anfrage nicht autorisiert werden. Sie benötigt jedoch eine Kennung, z. B. einen API-Schlüssel.
Informationen zum Autorisieren von Anfragen und zum Verwenden von API-Schlüsseln finden Sie im Dokument „API verwenden“ unter Anfragen autorisieren und Ihre Anwendung identifizieren.
Books API-Hintergrund
Buchkonzepte
Google Books basiert auf vier Grundkonzepten:
- Volumen: Ein Volumen steht für die Daten, die zu einem Buch oder einer Zeitschrift bei Google Books gehostet werden. Es ist die primäre Ressource in der Books API. Alle anderen Ressourcen in dieser API enthalten entweder ein Volume oder kommentieren es.
- Bookshelf: Ein Bücherregal ist eine Sammlung von Bänden. Google Books bietet eine Reihe vordefinierter Bücherregale für jeden Nutzer. Einige davon werden vollständig vom Nutzer verwaltet, einige davon werden basierend auf den Aktivitäten des Nutzers automatisch ausgefüllt und einige gemischt. Nutzer können andere Bücherregale erstellen, ändern oder löschen, die immer manuell mit Bänden gefüllt werden. Bücherregale können vom Nutzer als privat oder öffentlich festgelegt werden.
Hinweis:Bücherregale können derzeit nur über die Google Books-Website erstellt und gelöscht sowie die Datenschutzeinstellungen für Bücherregale geändert werden.
- Rezension: Eine Rezension ist eine Kombination aus einer Bewertung und/oder einem Text. Ein Nutzer kann pro Band eine Rezension einreichen. Rezensionen sind auch aus externen Quellen verfügbar und werden entsprechend zugeordnet.
- Leseposition: Eine Leseposition gibt die zuletzt von einem Nutzer gelesene Position in einem Band an. Pro Band kann ein Nutzer nur eine Leseposition haben. Wenn der Nutzer dieses Band noch nicht geöffnet hat, ist die Leseposition nicht vorhanden. Die Leseposition kann detaillierte Positionsinformationen bis zur Auflösung eines Wortes speichern. Diese Informationen sind immer für den Nutzer privat.
Books API-Datenmodell
Eine Ressource ist ein individuelles Datenobjekt mit einer eindeutigen ID. Die Books API wird basierend auf den oben beschriebenen Konzepten mit zwei Arten von Ressourcen ausgeführt:
- Volume-Ressource: Steht für ein Volume.
- Bücherregalressource: Stellt ein einzelnes Bücherregal für einen bestimmten Nutzer dar.
Das Books API-Datenmodell basiert auf Gruppen von Ressourcen, die als Sammlungen bezeichnet werden:
- Bände sammeln
- Die Bandsammlung ist eine Sammlung jeder Volume-Ressource, die von Google Books verwaltet wird.
Daher können Sie nicht alle Volume-Ressourcen auflisten, aber Sie können alle Volumes auflisten, die einer Reihe von Suchbegriffen entsprechen.
- Sammlung von Bücherregalen
- Eine Bücherregalsammlung besteht aus allen Bücherregalressourcen, die von Google Books verwaltet werden. Auf Bücherregale muss immer im Kontext der Mediathek eines bestimmten Nutzers verwiesen werden. Bücherregale können null oder mehr Bände enthalten.
- Favoriten: Veränderliches Bücherregal.
- Gekauft: Befüllt mit den Volumes, die der Nutzer gekauft hat. Der Nutzer kann Volumes nicht manuell hinzufügen oder entfernen.
- Lesen: Veränderliches Bücherregal.
- Jetzt lesen: Veränderliches Bücherregal.
- Haben gelesen: Veränderliches Bücherregal.
- Überprüft: Vom Nutzer geprüfte Bände Der Nutzer kann Volumes nicht manuell hinzufügen oder entfernen.
- Zuletzt angesehen: Mit Bänden gefüllt, die der Nutzer vor Kurzem in einem Web Reader geöffnet hat. Der Nutzer kann Volumes nicht manuell hinzufügen.
- Meine E-Books: Veränderliches Bücherregal Gekaufte Bücher werden automatisch hinzugefügt, können aber manuell entfernt werden.
- Bücher für dich: mit personalisierten Empfehlungen zu Band. Wenn es keine Empfehlungen für den Nutzer gibt, existiert dieses Bücherregal nicht.
- „Favoriten“
- Harry Potter
- „Meine E-Books“
- „Wechseln“
- „Dämmerung“
- „Das Mädchen mit dem Drachentattoo“
Google stellt für jeden Nutzer vordefinierte Bücherregale zur Verfügung:
Beispiele für Bücherregale:
Books API-Vorgänge
Sie können fünf verschiedene Methoden für Sammlungen und Ressourcen in der Books API aufrufen, wie in der folgenden Tabelle beschrieben.
Vorgang | Beschreibung | REST-HTTP-Zuordnungen |
---|---|---|
list | Listet eine bestimmte Teilmenge von Ressourcen in einer Sammlung auf. | GET für einen Sammlungs-URI. |
insert | Fügt eine neue Ressource in eine Sammlung ein und erstellt eine neue Ressource. | Für einen Sammlungs-URI ist dies POST , wobei Sie Daten für eine neue Ressource übergeben. |
get | Ruft eine bestimmte Ressource ab. | GET für den Ressourcen-URI. |
Update | Aktualisiert eine bestimmte Ressource. | PUT für den Ressourcen-URI, wobei Sie Daten für die aktualisierte Ressource übergeben. |
delete | Löscht eine bestimmte Ressource. | DELETE für den Ressourcen-URI, wobei Sie Daten für die zu löschende Ressource übergeben. |
Die für die verschiedenen Ressourcentypen unterstützten Vorgänge sind in der folgenden Tabelle zusammengefasst. Vorgänge, die für die privaten Daten eines Nutzers gelten, werden als „My Library“ (Meine Bibliothek) bezeichnet und erfordern alle eine Authentifizierung.
Ressourcentyp |
Unterstützte Vorgänge |
||||
---|---|---|---|---|---|
Liste | einfügen | get | Update | Löschen | |
Volumes | Ja* | Ja | |||
Bücherregale | Ja* | ja, AUTHENTIFIZIERT | Ja* | ja, AUTHENTIFIZIERT | ja, AUTHENTIFIZIERT |
Positionen lesen | ja, AUTHENTIFIZIERT | ja, AUTHENTIFIZIERT | ja, AUTHENTIFIZIERT | ja, AUTHENTIFIZIERT |
*Es sind sowohl AUTHENTICATED als auch nicht authentifizierte Versionen dieser Vorgänge verfügbar, bei denen die authentifizierten Anfragen mit den privaten Daten in "Meine Bibliothek" des Nutzers und nicht authentifizierte Anfragen nur mit öffentlichen Daten verarbeitet werden.
Aufrufstile
Es gibt mehrere Möglichkeiten, die API aufzurufen:
- REST direkt verwenden
- REST von JavaScript verwenden (kein serverseitiger Code erforderlich)
REST
REST ist eine Art Softwarearchitektur, die einen bequemen und einheitlichen Ansatz zur Abfrage und Bearbeitung von Daten bietet.
REST steht für "Representational State Transfer". Im Kontext der Google APIs ist damit die Verwendung von HTTP-Verben gemeint, um Darstellungen von Daten, die bei Google gespeichert sind, abzufragen und zu bearbeiten.
In einem als "RESTful" bezeichneten System werden Ressourcen in einem Datenspeicher abgelegt; ein Client sendet eine Aufforderung, der Server möge eine bestimmte Aktion ausführen (z. B. eine Ressource erstellen, abfragen, aktualisieren oder löschen), und der Server führt die Aktion aus und sendet eine Antwort, oft in Form einer Darstellung der angegebenen Ressource.
In den RESTful APIs von Google gibt der Client eine Aktion mit einem HTTP-Verb wie POST
, GET
, PUT
oder DELETE
an. Eine Ressource wird durch einen global eindeutigen URI im folgenden Format angegeben:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Weil alle API-Ressourcen eindeutige, über HTTP zugängliche URIs haben, ermöglicht REST das Caching von Daten und ist optimal geeignet, mit der verteilten Infrastruktur des Webs zu arbeiten.
Dafür können die Methodendefinitionen in der Dokumentation der HTTP 1.1-Standards hilfreich sein. Hier finden Sie auch die Spezifikationen für GET
, POST
, PUT
und DELETE
.
REST in der Books API
Die unterstützten Books-Vorgänge sind REST-HTTP-Verben direkt zugeordnet. Eine Beschreibung hierzu finden Sie unter Books API-Vorgänge.
Das spezifische Format für Books API-URIs lautet:
https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters
Dabei ist resourceID
die ID für eine Volume- oder Bookshelf-Ressource und parameters
alle Parameter, die auf die Abfrage angewendet werden sollen. Weitere Informationen finden Sie unter Referenz zu Suchparametern.
Anhand des Formats der resourceID
-Pfaderweiterungen können Sie die Ressource identifizieren, mit der Sie derzeit arbeiten. Beispiel:
https://www.googleapis.com/books/v1/volumes https://www.googleapis.com/books/v1/volumes/volumeId https://www.googleapis.com/books/v1/mylibrary/bookshelves https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes ...
Beachten Sie, dass Vorgänge mit mylibrary
im URI nur für die Daten der privaten Bibliothek des aktuell authentifizierten Nutzers gelten. Die vollständige Gruppe von URIs, die für jeden unterstützten Vorgang in der API verwendet wird, ist im Dokument Books API-Referenz zusammengefasst.
Hier sind einige Beispiele dafür, wie dies in der Books API funktioniert.
Eine Suche nach „quilting“ durchführen:
GET https://www.googleapis.com/books/v1/volumes?q=quilting
Informationen zum Volume „s1gVAAAAYAAJ“ erhalten:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST aus JavaScript
Sie können die Books API mit REST aus JavaScript (auch als JSON-P bezeichnet) mithilfe des callback
-Abfrageparameters und einer Callback-Funktion aufrufen. So können Sie umfangreiche Anwendungen erstellen, die Books-Daten anzeigen, ohne serverseitig Code schreiben zu müssen.
Hinweis:Sie können authentifizierte Methoden aufrufen, indem Sie ein OAuth 2.0-Token mit dem Parameter access_token
übergeben. Um ein OAuth 2.0-Token für die Verwendung mit JavaScript zu erhalten, folgen Sie der Anleitung unter OAuth 2.0 für clientseitige Webanwendungen. Richten Sie auf dem Tab "API-Zugriff" der APIs-Konsole eine Client-ID für Webanwendungen ein und verwenden Sie diese OAuth 2.0-Anmeldedaten beim Abrufen Ihres Tokens.
Im folgenden Beispiel wird dieser Ansatz verwendet, um Suchergebnisse für "harry potter" anzuzeigen:
<html> <head> <title>Books API Example</title> </head> <body> <div id="content"></div> <script> function handleResponse(response) { for (var i = 0; i < response.items.length; i++) { var item = response.items[i]; // in production code, item.text should have the HTML entities escaped. document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title; } } </script> <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script> </body> </html>
Datenformat
JavaScript Object Notation
JSON (JavaScript Object Notation) ist ein gängiges sprachunabhängiges Datenformat, das eine einfache Textdarstellung beliebiger Datenstrukturen bietet. Weitere Informationen finden Sie unter json.org.