Die Buchsuche Daten API von Google erlaubt Client Anwendungen Inhalte von Buchsuchen zu sehen und in der Form von Google Daten API Feeds zu aktualisieren. Die Client Anwendung kann die Buchsuche Daten API verwenden um Volltextsuchen nach Büchern durchzuführen und um Standardinformationen von Büchern zu erhalten, diese zu bewerten und zu kommentieren. Man kann auch individuelle Sammlungen von Benutzerbibliotheken und öffentlichen Kommentaren. Letztendlich kann eine Anwendung authentifizierte Anfragen abschicken um es Benutzern zu ermöglichen Bibliothekssammlungen zu erstellen, zu modifizieren, zu bewerten, zu benennen, zu kommentieren und andere Accountspezifische Dinge zu erlauben. Für weitere Informationen über die Buchsuche Daten API referieren Sie bitte zum offiziellen PHP Developer's Guide auf code.google.com. Man kann sowohl auf öffentliche als auch private Feeds zugreifen indem man die Buchsuche Daten API verwendet. Öffentliche Feeds benötigen keine Authentifizierung, aber man kann Sie nur lesen. Wenn man Benutzerbibliotheken verändern oder bewerden will, oder Label hinzufügen will muß der eigene Client authentifiziert werden bevor man private Feeds anfragt. Er kann sich authentifizieren indem einer von zwei Möglichkeiten verwendet wird: AuthSub Proxy Authentifizierung oder ClientLogin Benutzername/Passwort Authentifizierung. Bitte referieren Sie zum Authentifizierungs Kapitel im PHP Developer Guide für weitere Details. Die Buchsuche Daten API bietet eine Anzahl an Feeds die Sammlungen von Büchern auflisten. Die am meisten übliche Aktion ist das empfangen von Bücherlisten die einer Suchanfrage entsprechen. Um das zu tun muß ein VolumeQuery Objekt erstellt und an die Books::getVolumeFeed() Methode übergeben werden. Um zum Beispiel eine Schlüsselwortabfrage, mit einem Filter auf der Sichtbarkeit um die Ergebnisse auf partielle oder komplette sichtbare Bücher zu gegrenzen, durchzuführen müssen die setMinViewability() und () Methoden des VolumeQuery Objekts verwendet werden. Der folgende Codeschnipsel zeigt Titel und Sichtbarkeit aller Volumes deren Metadaten oder Texte dem Suchbegriff "domino" entsprechen: newVolumeQuery(); $query->setQuery('domino'); $query->setMinViewability('partial_view'); $feed = $books->getVolumeFeed($query); foreach ($feed as $entry) { echo $entry->getVolumeId(); echo $entry->getTitle(); echo $entry->getViewability(); } ]]> Die Query Klasse, und Subklassen wie VolumeQuery, sind dafür zuständig das Feed URL erzeugt werden. Der VolumeQuery der vorher gezeigt wurde erzeugt eine URL die der folgenden entspricht: Beachte: Da die Ergebnisse von Buchsuchen öffentlich sind, können Buchsuche Abfragen ohne Authentifizierung durchgeführt werden. Hier sind einige der üblichsten VolumeQuery Methoden für das Setzen von Suchparametern: setQuery(): Spezifiziert einen Suchabfragebegriff. Buchsuchen durchsuchen alle Metadaten der Bücher und des kompletten Textes nach Büchern die dem Begriff entsprechen. Buchmetadaten enthalten Titel, Schlüsselwörter, Beschreibungen, Namen von Autoren, und Untertitel. Es ist zu beachten das alle Leerzeichen, Hochkomma oder andere Punktierungen im Parameterwert URL-escaped werden müssen. (Verwende ein Plus (+) für ein Leerzeichen.) Um nach einer exakten Phrase zu suchen muß die Phrase in Hochkomma eingeschlossen werden. Um zum Beispiel nach einem Buch zu suchen das der Phrase "spy plane" entspricht, muß der q Parameter auf %22spy+plane%22 gesetzt werden. Man kann jede der zusätzlichen Suchoperatoren verwenden die von der Buchsuche unterstützt werden. Zum Beispiel gibt jane+austen+-inauthor:austen Entsprechungen zurück die Jane Austen erwähnen (aber nicht von Ihr geschrieben wurden). setStartIndex(): Spezifiziert den Index des ersten passenden Ergebnisses das im Ergebnisset enthalten sein sollte. Dieser Parameter verwendet einen eins-basierenden Index, was bedeutet dass das erste Ergebnis 1 ist, das zweite Ergebnis 2 und so weiter. Dieser Parameter arbeitet in Verbindung mit dem max-results Parameter um festzustellen welche Ergebnisse zurückzugeben sind. Um zum Beispiel das dritte Set von 10er Ergebnissen zu erhalten, 21-30-set, muß der start-index Parameter auf 21 und der max-results Parameter auf 10 gesetzt werden. Es ist zu beachten dass dies kein genereller Cursor Mechanismus ist. Wenn man zuerst eine Abfrage mit ?start-index=1&max-results=10 und anschließend eine andere Anfrage mit ?start-index=11&max-results=10, kann der Service nicht garantieren das die Ergebnisse äquivalent sind, weil zwischen den zwei Anfragen Einfügungen oder Löschungen durchgeführt worden sein können. setMaxResults(): Spezifiziert die maximale Anzahl an Ergebnissen die im Ergebnisset enthalten sein sollen. Dieser Parameter arbeitet in Verbindung mit dem start-index Parameter um festzustellen welche Ergebnisse zurückgegeben werden sollen. Der Standardwert dieses Parameters ist 10 und der Maximalwert ist 20. setMinViewability(): Erlaubt es Ergebnisse entsprechend dem Status der Sichtbarkeit der Bücher zu filtern. Dieser Parameter akzeptiert einen von drei Werten: 'none' (der Standardwert, der alle passenden Bücher zurückgibt Unabhängigkeit von der Sichtbarkeit), 'partial_view' (was nur Bücher zurückgibt die der Benutzer komplett oder teilweise sehen kann), oder 'full_view' (was nur Bücher zurückgibt die der Benutzer in Ihrer Komplettheit sehen kann). Die Google Buchsuche bietet eine Co-Branded Suche an, die Inhaltspartner erlaubt Volltextsuchen Ihrer Bücher von deren Webseite anzubieten. Wenn man ein Partner ist der eine Co-Branded Suche durchführen will indem die Buchsuche Daten API verwendet wird, kann man das tun indem die Feed URL von vorher so angepasst wird das Sie auf die eigene Co-Branded Suchimplementation zeigt. Wenn zum Beispiel, eine Co-Branded Suche unter der folgenden URL vorhanden ist: kann man die gleichen Ergebnisse erhalten indem die Buchsuche Daten API mit der folgenden URL verwendet wird: Um eine alternative URL zu spezifizieren wenn ein Volume Feed abgefragt wird, kann ein extra Parameter an newVolumeQuery() übergeben werden newVolumeQuery('http://www.google.com/books/p/PARTNER_COBRAND_ID'); ]]> Für zusätzliche Informationen oder Support, sehen Sie in unser Partner Help Center. Ein Benutzer kann einem Buch eine Bewertung hinzufügen. Die Buchsuche verwendet eie 1-5 Bewertungssystem in dem 1 die geringste Bewertung ist. Benutzer können Ihre Bewertungen nicht aktualisieren oder löschen. Um eine Bewertung hinzuzufügen, muß ein Rating an VolumeEntry hinzugefügt werden und an den Anmerkungsfeed gesendet werden. Im unten gezeigten Beispiel starten wir von einem leeren VolumeEntry Objekt. setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID)); $entry->setRating(new Zend_Gdata_Extension_Rating(3, 1, 5, 1)); $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI); ]]> Zusätzlich zu Bewertungen, können authentifizierte Benutzer Reviews übermitteln oder Ihre eigenen Reviews bearbeiten. Für Informationen darüber wie vorher übermittelte Reviews angefragt werden können, siehe Empfangen von Anmerkungen. Um eine Review hinzuzufügen, muß man ein Review Objekt an VolumeEntry übergeben und es an den Anmerkungsfeed übertragen. Im unteren Beispiel starten wir von einem bestehenden VolumeEntry Objekt. getAnnotationLink()->href; $review = new Zend_Gdata_Books_Extension_Review(); $review->setText("Dieses Buch ist aufregend!"); $entry->setReview($review); $books->insertVolume($entry, $annotationUrl); ]]> Um eine bestehende Review zu aktualisieren muß man zuerst die Review die bearbeitet werden soll empfangen, diese modifizieren, und dann an den Anmerkungsfeed übertragen. getId()->getText(); $review = new Zend_Gdata_Books_Extension_Review(); $review->setText("Dieses Buch ist leider nicht sehr gut!"); $entry->setReview($review); $books->updateVolume($entry, $entryUrl); ]]> Die Buchsuche Daten API kann verwendet werden um Volumes mit Label über Schlüsselwörtern zu versehen. Ein Benutzer kann diese übertragen, empfangen und verändern. Siehe Anmerkungen empfangen dafür wie vorher übertragene Label gelesen werden können. Um Label zu übermitteln muß ein Category Objekt mit dem Schema LABELS_SCHEME an VolumeEntry hinzugefügt und an den Anmerkungsfeed übergeben werden. getAnnotationLink()->href; $category = new Zend_Gdata_App_Extension_Category( 'rated', 'http://schemas.google.com/books/2008/labels'); $entry->setCategory(array($category)); $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI); ]]> Die Buchsuche Daten API kann verwendet werden um Anmerkungen zu empfangen die von einen angegebenen Benutzer übermittelt wurden. Anmerkungen enthalten Reviews, Bewertungen und Label. Um irgendwelche Anmerkungen von Benutzern zu empfangen muß eine nicht authentifizierte Anfrage gesendet werden die die BenutzerID des Benutzers enthält. Um die Anmerkungen des authentifizierten Benutzers zu empfangen muß der Wert me als BenutzerID verwendet werden. getVolumeFeed( 'http://www.google.com/books/feeds/users/USER_ID/volumes'); (oder) $feed = $books->getUserAnnotationFeed(); // Gibt Titel und Bewertungswerte aus foreach ($feed as $entry) { foreach ($feed->getTitles() as $title) { echo $title; } if ($entry->getRating()) { echo 'Bewertung: ' . $entry->getRating()->getAverage(); } } ]]> Für eine Liste an unterstützten Abfrageparametern, kann man in das Kapitel Abfrageparameter sehen. Wenn man einen Anmerkungseintrag empfängt der Bewertungen, Reviews und/oder Label enthält können alle Anmerkungen entfernt werden indem deleteVolume() an diesem Eintrag aufgerufen wird. deleteVolume($entry); ]]> Die Google Buchsuche bietet eine Anzahl von Benutzerspezifischen Buchsammlungen, jede mit Ihrem eigenen Feed. The wichtigste Sammlung ist die My Library des Benutzers, welche die Bücher repräsentiert die sich der Benutzer merken, organisieren und mit anderen Teilen will. Das ist die Sammlung die der Benutzer sieht wenn er auf seine oder ihre My Library Seite zugreift. Die folgenden Kapitel beschreiben wie eine Liste von Büchern von der Bibliothek eines Benutzers, mit oder ohne Abfrageparameter, empfangen werden können. Man kann den öffentlichen Feed einer Buchsuche ohne Authentifizierung abfragen. Um alle Bücher eines Benutzers zu empfangen muß eine Anfrage an den My Library Feed gesendet werden. Um die Bibliothek des authentifizierten Benutzers zu erhalten muß me statt der USER_ID verwendet werden. getUserLibraryFeed(); ]]> Es ist zu beachten das es sein kann das der Feed nicht alle Bücher des Benutzers enthält, weil es ein Standardlimit der Anzahl der zurückgegebenen Ergebnisse gibt. Für weitere Information siehe den max-results Abfrageparameter in Suchen nach Büchern. Genauso wie man über alle Bücher suchen kann, kann man auch eine Volltextsuche über die Bücher in einer Benutzerbibliothek durchführen. Um das zu tun müssen einfach die betreffenden Parameter am VolumeQuery Objekt gesetzt werden. Zum Beispiel gibt die folgende Abfrage alle Bücher in der eigenen Bibliothek zurück die das Word "Bär" enthalten: newVolumeQuery( 'http://www.google.com/books/feeds/users/' . 'USER_ID/collections/library/volumes'); $query->setQuery('Bär'); $feed = $books->getVolumeFeed($query); ]]> Für eine Liste von unterstützten Abfrageparametern können Sie in das Kapitel Abfrageparameter sehen. Zusätzlich kann nach Büchern gesucht werden die von einem Benutzer gelabelt wurden: newVolumeQuery( 'http://www.google.com/books/feeds/users/' . 'USER_ID/collections/library/volumes'); $query->setCategory( $query->setCategory('favorites'); $feed = $books->getVolumeFeed($query); ]]> Die Buchsuche Daten API kann dazu verwendet werden um ein Buch einer Benutzerbibliothek hinzuzufügen oder es aus Ihr zu entfernen. Bewertungen, Reviews und Label sind über alle Sammlungen eines Benutzers gültig, und können deswegen bearbeitet werden indem der Anmerkungsfeed verwendet wird (siehe Verwendung üblicher Features). Nach der Authentifizierung können Bucher zur aktuellen Benutzerbibliothek hinzugefügt werden. Man kann entweder einen Eintrag von Null auf erstellen wenn man die Volume ID weiß, oder einen Eintrag einfügen wenn von irgendeinem Feed gelesen wird. Das folgende Beispiel erstellt einen neuen Eintrag und fügt Ihn der Bibliothek hinzu: setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID)); $books->insertVolume( $entry, Zend_Gdata_Books::MY_LIBRARY_FEED_URI ); ]]> Das folgende Beispiel fügt ein bestehendes VolumeEntry Objekt in der Bibliothek hinzu: insertVolume( $entry, Zend_Gdata_Books::MY_LIBRARY_FEED_URI ); ]]> Um ein Buch von einer Benutzerbibliothek zu entfernen, muß deleteVolume() auf dem VolumeEntry Objekt aufgerufen werden. deleteVolume($entry); ]]>