Informationen für Einsteiger

In diesem Dokument finden Sie die Hintergrundinformationen, die Sie für die Verwendung der Google Books API benötigen.

Einführung

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 der Welt zu digitalisieren. Mit der Google Books API können Sie Inhalte suchen, die persönliche Bibliothek eines authentifizierten Nutzers organisieren und sie auch ändern.

Vorbereitung

Google-Konto erstellen

Für Testzwecke benötigen Sie ein Google-Konto. Wenn Sie bereits ein Testkonto haben, können Sie die Benutzeroberfläche von Google Books aufrufen, um Ihre Testdaten einzurichten, zu bearbeiten oder anzusehen.

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 Webprogrammierkonzepten und Webdatenformaten vertraut sind.

Informationen zum Autorisieren von Anfragen und 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 alle Vorgänge unter „Meine Bibliothek“ in der Google Books API gelten als privat und erfordern Authentifizierung und Autorisierung. Außerdem kann jeder Vorgang, mit dem Google Books-Daten geändert werden, nur von dem Nutzer ausgeführt werden, dem diese Daten gehören.

Fordert Ihre Anwendung dagegen öffentliche Daten an, muss die Anfrage nicht autorisiert werden. Sie benötigt jedoch eine Kennung, z. B. einen API-Schlüssel.

Informationen zum Autorisieren von Anfragen und zur Verwendung von API-Schlüsseln finden Sie im Dokument „Using the API“ (API verwenden) unter Authorizing requests and identifying your application (Anfragen autorisieren und Anwendung identifizieren).

Hintergrundinformationen zur Books API

Konzepte für Bücher

Google Books basiert auf vier grundlegenden Konzepten:

• Band: Ein Band stellt die Daten dar, die Google Books zu einem Buch oder einer Zeitschrift hostet. Sie ist die primäre Ressource in der Books API. Alle anderen Ressourcen in dieser API enthalten oder annotieren ein Volume.
• Bücherregal: Ein Bücherregal ist eine Sammlung von Bänden. Google Books bietet für jeden Nutzer eine Reihe vordefinierter Bücherregale. Einige davon werden vollständig vom Nutzer verwaltet, andere werden automatisch auf Grundlage der Nutzeraktivitäten gefüllt und wieder andere sind eine Mischung aus beidem. Nutzer können andere Bücherregale erstellen, ändern oder löschen. Diese werden immer manuell mit Büchern gefüllt. Nutzer können ihre Bücherregale privat oder öffentlich machen.

  Hinweis:Das Erstellen und Löschen von Bücherregalen sowie das Ändern der Datenschutzeinstellungen für Bücherregale ist derzeit nur über die Google Books-Website möglich.

• Rezension: Eine Rezension eines Bandes ist eine Kombination aus einer Sternebewertung und/oder Text. Ein Nutzer kann pro Band eine Rezension schreiben. Rezensionen sind auch aus externen Quellen verfügbar und werden entsprechend zugeordnet.
• Leseposition: Eine Leseposition gibt die zuletzt gelesene Position in einem Band für einen Nutzer an. Ein Nutzer kann nur eine Leseposition pro Band haben. Wenn der Nutzer diesen 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 privat.

Books API-Datenmodell

Eine Ressource ist ein individuelles Datenobjekt mit einer eindeutigen ID. Die Books API arbeitet mit zwei Arten von Ressourcen, die auf den oben beschriebenen Konzepten basieren:

• Volume-Ressource: Stellt ein Volume dar.
• Bookshelf-Ressource: Stellt ein einzelnes Bücherregal für einen bestimmten Nutzer dar.

Das Datenmodell der Books API basiert auf Ressourcengruppen, sogenannten Sammlungen:

Volume Collection

Die Sammlung von Bänden ist eine Sammlung aller Bandressourcen, die von Google Books verwaltet werden. Daher können Sie nicht alle Volume-Ressourcen auflisten, aber Sie können alle Volumes auflisten, die einer Reihe von Suchbegriffen entsprechen.

Bücherregal-Sammlung

Eine Bookshelf-Sammlung besteht aus allen Bookshelf-Ressourcen, die von Google Books verwaltet werden. Auf Bücherregale muss immer im Kontext der Bibliothek eines bestimmten Nutzers verwiesen werden. Ein Bücherregal kann null oder mehr Bände enthalten.

Google stellt jedem Nutzer eine Reihe vordefinierter Regale zur Verfügung:

• Favoriten: Veränderliches Bücherregal.
• Gekauft: Enthält die vom Nutzer gekauften Volumes. Der Nutzer kann keine Volumes manuell hinzufügen oder entfernen.
• „Lesen“: Veränderbares Bücherregal.
• „Aktuell gelesen“: Veränderliches Bücherregal.
• Gelesen: Veränderliches Bücherregal.
• Gelesen: Hier werden die Bände angezeigt, die der Nutzer gelesen hat. Der Nutzer kann keine Volumes manuell hinzufügen oder entfernen.
• Zuletzt angesehen: Hier werden Bände angezeigt, die der Nutzer kürzlich in einem Webreader geöffnet hat. Der Nutzer kann keine Volumes manuell hinzufügen.
• Meine E-Books: Veränderbares Bücherregal. Gekaufte Bücher werden automatisch hinzugefügt, können aber manuell entfernt werden.
• „Für dich“: Hier werden personalisierte Empfehlungen für Bücher angezeigt. Wenn wir keine Empfehlungen für den Nutzer haben, ist dieses Bücherregal nicht vorhanden.

Beispielregale:

• „Favoriten“
• „Harry Potter“
• „Meine E‑Books“
• „Wechseln“
• „Dämmerung“
• „Verblendung“

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.

Die Vorgänge, die für die verschiedenen Ressourcentypen unterstützt werden, sind in der folgenden Tabelle zusammengefasst. Vorgänge, die sich auf die privaten Daten eines Nutzers beziehen, werden als „Meine Mediathek“-Vorgänge bezeichnet und erfordern alle eine Authentifizierung.

*Sowohl AUTHENTICATED- als auch nicht authentifizierte Versionen dieser Vorgänge sind verfügbar. Bei authentifizierten Anfragen werden die privaten Daten des Nutzers unter „Meine Mediathek“ verwendet, bei nicht authentifizierten Anfragen nur öffentliche Daten.

Aufrufstile

Es gibt mehrere Möglichkeiten, die API aufzurufen:

• REST direkt verwenden
• REST über 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.

Der Begriff REST steht für Representational State Transfer. Im Zusammenhang mit Google-APIs bezieht es sich auf die Verwendung von HTTP-Verben zum Abrufen und Ändern von Darstellungen von Daten, die von Google gespeichert sind.

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 Googles RESTful APIs spezifiziert der Client eine Aktion mit einem HTTP-Verb wie POST, GET, PUT oder DELETE. Eine Ressource wird anhand eines weltweit eindeutigen URIs im folgenden Format spezifiziert:

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 API-Vorgänge sind REST-HTTP-Verben direkt zugeordnet, wie unter Books API-Vorgänge beschrieben.

Für Books API-URIs gelten folgende spezielle Formate:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

Dabei ist resourceID die Kennzeichnung für eine Volume- oder Bücherregalressource und parameters sind alle Parameter, die auf die Abfrage angewendet werden sollen. Weitere Informationen finden Sie in der Referenz zu Abfrageparametern.

Anhand des Formats der resourceID-Pfaderweiterungen können Sie die Ressource identifizieren, mit der Sie gerade arbeiten, z. B.:

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

Vorgänge mit mylibrary im URI gelten nur für die privaten Bibliotheksdaten des aktuell authentifizierten Nutzers. Eine vollständige Liste der URIs für jeden unterstützten Vorgang in der API finden Sie im Referenzdokument zur Books API.

Hier sind einige Beispiele für die Funktionsweise in der Books API.

Führen Sie eine Suche nach Quilten durch:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

Informationen zum Volume s1gVAAAAYAAJ abrufen:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST über JavaScript

Sie können die Books API über REST aus JavaScript aufrufen (auch JSON-P genannt). Verwenden Sie dazu den Abfrageparameter callback und eine Callback-Funktion. So können Sie umfangreiche Anwendungen entwickeln, in denen Buchdaten angezeigt werden, ohne serverseitigen 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. Wenn Sie ein OAuth 2.0-Token für die Verwendung mit JavaScript abrufen möchten, folgen Sie der Anleitung unter OAuth 2.0 für clientseitige Webanwendungen. Richten Sie auf dem Tab „API-Zugriff“ der APIs Console eine Client-ID für Webanwendungen ein und verwenden Sie diese OAuth 2.0-Anmeldedaten, wenn Sie Ihr Token abrufen.

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

JSON

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.