repo_zf1/documentation/manual/de/module_specs/Zend_Gdata_Books.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.books">
    <title>Die Buchsuche Daten API verwenden</title>

    <para>
        Die Buchsuche Daten <acronym>API</acronym> von Google erlaubt Client Anwendungen Inhalte
        von Buchsuchen zu sehen und in der Form von Google Daten <acronym>API</acronym> Feeds
        zu aktualisieren.
    </para>

    <para>
        Die Client Anwendung kann die Buchsuche Daten <acronym>API</acronym> 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
        <ulink url="http://books.google.com/googlebooks/mylibrary/">Sammlungen von
        Benutzerbibliotheken und öffentlichen Kommentaren</ulink>. 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.
    </para>

    <para>
        Für weitere Informationen über die Buchsuche Daten <acronym>API</acronym> referieren Sie
        bitte zum offiziellen <ulink
            url="http://code.google.com/apis/books/gdata/developers_guide_php.html">PHP Developer's
            Guide</ulink> auf code.google.com.
    </para>

    <sect2 id="zend.gdata.books.authentication">
        <title>Beim Buchsuche Service authentifizieren</title>

        <para>
            Man kann sowohl auf öffentliche als auch private Feeds zugreifen indem man
            die Buchsuche Daten <acronym>API</acronym> 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 <ulink
                url="http://code.google.com/apis/books/gdata/developers_guide_php.html#Authentication">Authentifizierungs
                Kapitel im <acronym>PHP</acronym> Developer Guide</ulink> für weitere Details.
        </para>
    </sect2>

    <sect2 id="zend.gdata.books.searching_for_books">
        <title>Nach Büchern suchen</title>

        <para>
            Die Buchsuche Daten <acronym>API</acronym> bietet eine Anzahl an Feeds die Sammlungen
            von Büchern auflisten.
        </para>

        <para>
            Die am meisten übliche Aktion ist das empfangen von Bücherlisten die einer
            Suchanfrage entsprechen. Um das zu tun muß ein <classname>VolumeQuery</classname>
            Objekt erstellt und an die <methodname>Books::getVolumeFeed()</methodname> Methode
            übergeben werden.
        </para>

        <para>
            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 <methodname>setMinViewability()</methodname> und
            <methodname>()</methodname> Methoden des <classname>VolumeQuery</classname> Objekts
            verwendet werden. Der folgende Codeschnipsel zeigt Titel und Sichtbarkeit aller Volumes
            deren Metadaten oder Texte dem Suchbegriff "domino" entsprechen:
        </para>

        <programlisting language="php"><![CDATA[
$books = new Zend_Gdata_Books();
$query = $books->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();
}
]]></programlisting>

        <para>
            Die <classname>Query</classname> Klasse, und Subklassen wie
            <classname>VolumeQuery</classname>, sind dafür zuständig das Feed <acronym>URL</acronym>
            erzeugt werden. Der VolumeQuery der vorher gezeigt wurde erzeugt eine
            <acronym>URL</acronym> die der folgenden entspricht:
        </para>

        <programlisting language="php"><![CDATA[
http://www.google.com/books/feeds/volumes?q=keyword&amp;min-viewability=partial
]]></programlisting>

        <para>
            Beachte: Da die Ergebnisse von Buchsuchen öffentlich sind, können Buchsuche
            Abfragen ohne Authentifizierung durchgeführt werden.
        </para>

        <para>
            Hier sind einige der üblichsten <classname>VolumeQuery</classname> Methoden für das
            Setzen von Suchparametern:
        </para>

        <para>
            <methodname>setQuery()</methodname>: 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
            <acronym>URL</acronym>-escaped werden müssen. (Verwende ein Plus
            (<emphasis>+</emphasis>) 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 <property>q</property> Parameter
            auf <command>%22spy+plane%22</command> gesetzt werden. Man kann jede der <ulink
                url="http://books.google.com/advanced_book_search">zusätzlichen
                Suchoperatoren</ulink> verwenden die von der Buchsuche unterstützt werden. Zum
            Beispiel gibt <command>jane+austen+-inauthor:austen</command> Entsprechungen zurück die
            Jane Austen erwähnen (aber nicht von Ihr geschrieben wurden).
        </para>

        <para>
            <methodname>setStartIndex()</methodname>: 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 <property>start-index</property> Parameter auf
            <emphasis>21</emphasis> und der max-results Parameter auf <emphasis>10</emphasis>
            gesetzt werden. Es ist zu beachten dass dies kein genereller Cursor Mechanismus ist.
            Wenn man zuerst eine Abfrage mit <command>?start-index=1&amp;max-results=10</command>
            und anschließend eine andere Anfrage mit
            <command>?start-index=11&amp;max-results=10</command>, 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.
        </para>

        <para>
            <methodname>setMaxResults()</methodname>: 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
            <emphasis>10</emphasis> und der Maximalwert ist <emphasis>20</emphasis>.
        </para>

        <para>
            <methodname>setMinViewability()</methodname>: Erlaubt es Ergebnisse entsprechend dem
            <ulink
                url="http://code.google.com/apis/books/docs/dynamic-links.html#terminology">Status
                der Sichtbarkeit</ulink> der Bücher zu filtern. Dieser Parameter akzeptiert einen
            von drei Werten: <emphasis>'none'</emphasis> (der Standardwert, der alle passenden
            Bücher zurückgibt Unabhängigkeit von der Sichtbarkeit),
            <emphasis>'partial_view'</emphasis> (was nur Bücher zurückgibt die der Benutzer komplett
            oder teilweise sehen kann), oder <emphasis>'full_view'</emphasis> (was nur Bücher
            zurückgibt die der Benutzer in Ihrer Komplettheit sehen kann).
        </para>

        <sect3 id="zend.gdata.books.partner_restrict">
            <title>Partner Co-Branded Suche</title>

            <para>
                Die Google Buchsuche bietet eine <ulink
                    url="http://books.google.com/support/partner/bin/answer.py?hl=en&amp;answer=65113">Co-Branded
                    Suche</ulink> an, die Inhaltspartner erlaubt Volltextsuchen Ihrer Bücher von
                deren Webseite anzubieten.
            </para>

            <para>
                Wenn man ein Partner ist der eine Co-Branded Suche durchführen will indem die
                Buchsuche Daten <acronym>API</acronym> verwendet wird, kann man das tun indem die
                Feed <acronym>URL</acronym> von vorher so angepasst wird das Sie auf die eigene
                Co-Branded Suchimplementation zeigt. Wenn zum Beispiel, eine Co-Branded Suche unter
                der folgenden <acronym>URL</acronym> vorhanden ist:
            </para>

            <programlisting language="php"><![CDATA[
http://www.google.com/books/p/PARTNER_COBRAND_ID?q=ball
]]></programlisting>

            <para>
                kann man die gleichen Ergebnisse erhalten indem die Buchsuche Daten
                <acronym>API</acronym> mit der folgenden <acronym>URL</acronym> verwendet wird:
            </para>

            <programlisting language="php"><![CDATA[
http://www.google.com/books/feeds/p/PARTNER_COBRAND_ID/volumes?q=ball+-soccer
]]></programlisting>

            <para>
                Um eine alternative <acronym>URL</acronym> zu spezifizieren wenn ein Volume Feed
                abgefragt wird, kann ein extra Parameter an
                <methodname>newVolumeQuery()</methodname> übergeben werden
            </para>

            <programlisting language="php"><![CDATA[
$query =
    $books->newVolumeQuery('http://www.google.com/books/p/PARTNER_COBRAND_ID');
]]></programlisting>

            <para>
                Für zusätzliche Informationen oder Support, sehen Sie in unser
                <ulink url="http://books.google.com/support/partner/">Partner Help Center</ulink>.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.books.community_features">
        <title>Übliche Features verwenden</title>

        <sect3 id="zend.gdata.books.adding_ratings">
            <title>Eine Bewertung hinzufügen</title>

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

            <para>
                Um eine Bewertung hinzuzufügen, muß ein <classname>Rating</classname> an
                <classname>VolumeEntry</classname> hinzugefügt werden und an den Anmerkungsfeed
                gesendet werden. Im unten gezeigten Beispiel starten wir von einem leeren
                <classname>VolumeEntry</classname> Objekt.
            </para>

            <programlisting language="php"><![CDATA[
$entry = new Zend_Gdata_Books_VolumeEntry();
$entry->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);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.books.reviews">
            <title>Reviews</title>

            <para>
                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 <ulink
                    url="#zend.gdata.books.retrieving_annotations">Empfangen von
                    Anmerkungen</ulink>.
            </para>

            <sect4 id="zend.gdata.books.adding_review">
                <title>Eine Review hinzufügen</title>

                <para>
                    Um eine Review hinzuzufügen, muß man ein <classname>Review</classname> Objekt an
                    <classname>VolumeEntry</classname> übergeben und es an den Anmerkungsfeed
                    übertragen. Im unteren Beispiel starten wir von einem bestehenden
                    <classname>VolumeEntry</classname> Objekt.
                </para>

                <programlisting language="php"><![CDATA[
$annotationUrl = $entry->getAnnotationLink()->href;
$review        = new Zend_Gdata_Books_Extension_Review();

$review->setText("Dieses Buch ist aufregend!");
$entry->setReview($review);
$books->insertVolume($entry, $annotationUrl);
]]></programlisting>
            </sect4>

            <sect4 id="zend.gdata.books.editing_review">
                <title>Eine Review bearbeiten</title>

                <para>
                    Um eine bestehende Review zu aktualisieren muß man zuerst die Review die
                    bearbeitet werden soll empfangen, diese modifizieren, und dann an den
                    Anmerkungsfeed übertragen.
                </para>

                <programlisting language="php"><![CDATA[
$entryUrl = $entry->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);
]]></programlisting>
            </sect4>
        </sect3>

        <sect3 id="zend.gdata.books.labels">
            <title>Labels</title>

            <para>
                Die Buchsuche Daten <acronym>API</acronym> kann verwendet werden um Volumes mit
                Label über Schlüsselwörtern zu versehen. Ein Benutzer kann diese übertragen,
                empfangen und verändern. Siehe <ulink
                    url="#zend.gdata.books.retrieving_annotations">Anmerkungen empfangen</ulink>
                dafür wie vorher übertragene Label gelesen werden können.
            </para>

            <sect4 id="zend.gdata.books.submitting_labels">
                <title>Ein Set von Label übermitteln</title>

                <para>
                    Um Label zu übermitteln muß ein <classname>Category</classname> Objekt mit dem
                    Schema <constant>LABELS_SCHEME</constant> an <classname>VolumeEntry</classname>
                    hinzugefügt und an den Anmerkungsfeed übergeben werden.
                </para>

                <programlisting language="php"><![CDATA[
$annotationUrl = $entry->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);
]]></programlisting>
            </sect4>
        </sect3>

        <sect3 id="zend.gdata.books.retrieving_annotations">
            <title>Empfangen von Anmerkungen: Reviews, Bewertungen und Label</title>

            <para>
                Die Buchsuche Daten <acronym>API</acronym> 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 <emphasis>me</emphasis> als BenutzerID verwendet werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $books->getVolumeFeed(
            'http://www.google.com/books/feeds/users/USER_ID/volumes');
<i>(oder)</i>
$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();
    }
}
]]></programlisting>

            <para>
                Für eine Liste an unterstützten Abfrageparametern, kann man in das Kapitel
                <ulink url="#zend.gdata.books.query_parameters">Abfrageparameter</ulink> sehen.
            </para>
        </sect3>

        <sect3 id="zend.gdata.books.deleting_annotations">
            <title>Anmerkungen löschen</title>

            <para>
                Wenn man einen Anmerkungseintrag empfängt der Bewertungen, Reviews und/oder Label
                enthält können alle Anmerkungen entfernt werden indem
                <methodname>deleteVolume()</methodname> an diesem Eintrag aufgerufen wird.
            </para>

            <programlisting language="php"><![CDATA[
$books->deleteVolume($entry);
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.books.sharing_with_my_library">
        <title>Büchersammlungen und My Library</title>

        <para>
            Die Google Buchsuche bietet eine Anzahl von Benutzerspezifischen Buchsammlungen,
            jede mit Ihrem eigenen Feed.
        </para>

        <para>
            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
            <ulink url="http://books.google.com/books?op=library">My Library Seite</ulink>
            zugreift.
        </para>

        <sect3 id="zend.gdata.books.retrieving_books_in_library">
            <title>Bücher auf der Benutzerbibliothek erhalten</title>

            <para>
                Die folgenden Kapitel beschreiben wie eine Liste von Büchern von der Bibliothek
                eines Benutzers, mit oder ohne Abfrageparameter, empfangen werden können.
            </para>

            <para>
                Man kann den öffentlichen Feed einer Buchsuche ohne Authentifizierung abfragen.
            </para>

            <sect4 id="zend.gdata.books.retrieving_all_books_in_library">
                <title>Alle Bücher in einer Benutzerbibliothek empfangen</title>

                <para>
                    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ß <emphasis>me</emphasis> statt der <constant>USER_ID</constant>
                    verwendet werden.
                </para>

                <programlisting language="php"><![CDATA[
$feed = $books->getUserLibraryFeed();
]]></programlisting>

                <para>
                    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 <property>max-results</property>
                    Abfrageparameter in <ulink url="#zend.gdata.books.searching_for_books">Suchen
                        nach Büchern</ulink>.
                </para>
            </sect4>

            <sect4 id="zend.gdata.books.retrieving_books_in_library_with_query">
                <title>Nach Büchern in einer Benutzerbibliothek suchen</title>

                <para>
                    Genauso wie man
                    <ulink url="#zend.gdata.books.searching_for_books">über alle Bücher suchen
                        kann</ulink>, 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 <classname>VolumeQuery</classname> Objekt gesetzt werden.
                </para>

                <para>
                    Zum Beispiel gibt die folgende Abfrage alle Bücher in der eigenen Bibliothek
                    zurück die das Word "Bär" enthalten:
                </para>

                <programlisting language="php"><![CDATA[
$query = $books->newVolumeQuery(
    'http://www.google.com/books/feeds/users/' .
    'USER_ID/collections/library/volumes');
$query->setQuery('Bär');
$feed = $books->getVolumeFeed($query);
]]></programlisting>

                <para>
                    Für eine Liste von unterstützten Abfrageparametern können Sie in das Kapitel
                    <ulink url="#zend.gdata.books.query_pParameters">Abfrageparameter</ulink> sehen.
                    Zusätzlich kann nach Büchern gesucht werden die <ulink
                        url="#zend.gdata.books.labels">von einem Benutzer gelabelt wurden</ulink>:
                </para>

                <programlisting language="php"><![CDATA[
$query = $books->newVolumeQuery(
    'http://www.google.com/books/feeds/users/' .
    'USER_ID/collections/library/volumes');
$query->setCategory(
$query->setCategory('favorites');
$feed = $books->getVolumeFeed($query);
]]></programlisting>
            </sect4>
        </sect3>

        <sect3 id="zend.gdata.books.updating_library">
            <title>Bücher in einer Benutzerbibliothek aktualisieren</title>

            <para>
                Die Buchsuche Daten <acronym>API</acronym> 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
                <ulink url="#zend.gdata.books.community_features">Verwendung üblicher
                    Features</ulink>).
            </para>

            <sect4 id="zend.gdata.books.library_book_add">
                <title>Ein Buch zu einer Bibliothek hinzufügen</title>

                <para>
                    Nach der Authentifizierung können Bucher zur aktuellen Benutzerbibliothek
                    hinzugefügt werden.
                </para>

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

                <para>
                    Das folgende Beispiel erstellt einen neuen Eintrag und fügt Ihn der Bibliothek
                    hinzu:
                </para>

                <programlisting language="php"><![CDATA[
$entry = new Zend_Gdata_Books_VolumeEntry();
$entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID));
$books->insertVolume(
    $entry,
    Zend_Gdata_Books::MY_LIBRARY_FEED_URI
);
]]></programlisting>

                <para>
                    Das folgende Beispiel fügt ein bestehendes <classname>VolumeEntry</classname>
                    Objekt in der Bibliothek hinzu:
                </para>

                <programlisting language="php"><![CDATA[
$books->insertVolume(
    $entry,
    Zend_Gdata_Books::MY_LIBRARY_FEED_URI
);
]]></programlisting>
            </sect4>

            <sect4 id="zend.gdata.books.library_book_remove">
                <title>Ein Buch von einer Bibliothek entfernen</title>

                <para>
                    Um ein Buch von einer Benutzerbibliothek zu entfernen, muß
                    <methodname>deleteVolume()</methodname> auf dem
                    <classname>VolumeEntry</classname> Objekt aufgerufen werden.
                </para>

                <programlisting language="php"><![CDATA[
$books->deleteVolume($entry);
]]></programlisting>
            </sect4>
        </sect3>
    </sect2>
</sect1>