From 06f945f27840b53e57795dadbc38e76f7e11ab1c Mon Sep 17 00:00:00 2001 From: Horus3 Date: Mon, 24 Feb 2014 16:42:14 +0100 Subject: init --- .../manual/core/en/zend.gdata.books.html | 600 +++++++++++++++++++++ 1 file changed, 600 insertions(+) create mode 100644 zend/documentation/manual/core/en/zend.gdata.books.html (limited to 'zend/documentation/manual/core/en/zend.gdata.books.html') diff --git a/zend/documentation/manual/core/en/zend.gdata.books.html b/zend/documentation/manual/core/en/zend.gdata.books.html new file mode 100644 index 0000000..81ffe31 --- /dev/null +++ b/zend/documentation/manual/core/en/zend.gdata.books.html @@ -0,0 +1,600 @@ + + + + + Using the Book Search Data API - Zend Framework Manual + + + + + + + + +
+ + + + + + + + +
+ Authenticating with AuthSub + +
Zend_Gdata
+ Programmer's Reference Guide
+ 		+ +
+
+

Using the Book Search Data API

+ + +

+ The Google Book Search Data API allows client applications to view + and update Book Search content in the form of Google Data API feeds. +

+ +

+ Your client application can use the Book Search Data API to issue + full-text searches for books and to retrieve standard book information, + ratings, and reviews. You can also access individual users' + » library collections and + public reviews. Finally, your application can submit authenticated requests + to enable users to create and modify library collections, ratings, labels, + reviews, and other account-specific entities. +

+ +

+ For more information on the Book Search Data API, please refer to the + official » PHP + Developer's Guide on code.google.com. +

+ +

Authenticating to the Book Search service

+ + +

+ You can access both public and private feeds using the Book Search + Data API. Public feeds don't require any authentication, but they are + read-only. If you want to modify user libraries, submit reviews or + ratings, or add labels, then your client needs to authenticate before + requesting private feeds. It can authenticate using either of two + approaches: AuthSub proxy authentication or ClientLogin username/password + authentication. Please refer to the » Authentication + section in the PHP Developer's Guide for more detail. +

+
+ +

Searching for books

+ + +

+ The Book Search Data API provides a number of feeds that list + collections of books. +

+ +

+ The most common action is to retrieve a list of books that match a + search query. To do so you create a VolumeQuery object + and pass it to the Books::getVolumeFeed() method. +

+ +

+ For example, to perform a keyword query, with a filter on + viewability to restrict the results to partial or full view books, use + the setMinViewability() and setQuery() + methods of the VolumeQuery object. The following code snippet + prints the title and viewability of all volumes whose metadata or text matches + the query term "domino": +

+ +
  1. $books = new Zend_Gdata_Books();
    2. +
  2. $query = $books->newVolumeQuery();
    3. +
  3.  
    4. +
  4. $query->setQuery('domino');
    5. +
  5. $query->setMinViewability('partial_view');
    6. +
  6.  
    7. +
  7. $feed = $books->getVolumeFeed($query);
    8. +
  8.  
    9. +
  9. foreach ($feed as $entry) {
    10. +
  10.     echo $entry->getVolumeId();
    11. +
  11.     echo $entry->getTitle();
    12. +
  12.     echo $entry->getViewability();
    13. +
  13. }
+ + +

+ The Query class, and subclasses like + VolumeQuery, are responsible for constructing feed + URLs. The VolumeQuery shown above constructs a URL + equivalent to the following: +

+ +
  1. http://www.google.com/books/feeds/volumes?q=keyword&min-viewability=partial
+ + +

+ Note: Since Book Search results are + public, you can issue a Book Search query without authentication. +

+ +

+ Here are some of the most common VolumeQuery + methods for setting search parameters: +

+ +

+ setQuery(): Specifies a search + query term. Book Search searches all book metadata and full text for + books matching the term. Book metadata includes titles, keywords, + descriptions, author names, and subjects. + Note that any spaces, quotes or other punctuation in the parameter + value must be URL-escaped (Use a plus (+) for a + space). To search for an exact phrase, enclose the phrase in quotation marks. + For example, to search for books matching the phrase "spy plane", set + the q parameter to %22spy+plane%22. + You can also use any of the » + advanced search operators supported by Book Search. For example, + jane+austen+-inauthor:austen returns matches that mention + (but are not authored by) Jane Austen. +

+ +

+ setStartIndex(): Specifies + the index of the first matching result that should be included in the + result set. This parameter uses a one-based index, meaning the first + result is 1, the second result is 2 and so forth. This parameter works + in conjunction with the max-results + parameter to determine which results to return. For example, to + request the third set of 10 results—results 21-30—set + the start-index parameter to 21 and the + max-results parameter to 10. + Note: This isn't a general cursoring + mechanism. If you first send a query with + ?start-index=1&max-results=10 and then send another + query with ?start-index=11&max-results=10, the + service cannot guarantee that the results are equivalent to + ?start-index=1&max-results=20, because insertions and + deletions could have taken place in between the two queries. +

+ +

+ setMaxResults(): + Specifies the maximum number of results that should be included + in the result set. This parameter works in conjunction with the + start-index parameter to determine which + results to return. The default value of this parameter is + 10 and the maximum value is 20. +

+ +

+ setMinViewability(): Allows you to filter the results according + to the books' » viewability + status. This parameter accepts one of three values: + 'none' (the default, returning all matching books regardless of + viewability), 'partial_view' (returning only books + that the user can preview or view in their entirety), or + 'full_view' (returning only books that the user can + view in their entirety). +

+ +

Partner Co-Branded Search

+ + +

+ Google Book Search provides » Co-Branded + Search, which lets content partners provide full-text search of + their books from their own websites. +

+ +

+ If you are a partner who wants to do Co-Branded Search using the + Book Search Data API, you may do so by modifying the feed + URL above to point to your Co-Branded Search implementation. if, + for example, a Co-Branded Search is available at the following + URL: +

+ +
  1. http://www.google.com/books/p/PARTNER_COBRAND_ID?q=ball
+ + +

+ then you can obtain the same results using the Book Search Data + API at the following URL: +

+ +
  1. http://www.google.com/books/feeds/p/PARTNER_COBRAND_ID/volumes?q=ball+-soccer
+ + +

+ To specify an alternate URL when querying a volume feed, you can + provide an extra parameter to newVolumeQuery() +

+ +
  1. $query =
    2. +
  2.     $books->newVolumeQuery('http://www.google.com/books/p/PARTNER_COBRAND_ID');
+ + +

+ For additional information or support, visit our + » Partner help center. +

+
+
+ +

Using community features

+ + +

Adding a rating

+ + +

+ A user can add a rating to a book. Book Search uses a 1-5 + rating system in which 1 is the lowest rating. Users cannot + update or delete ratings. +

+ +

+ To add a rating, add a Rating object to a + VolumeEntry and post it to the annotation feed. In the + example below, we start from an empty VolumeEntry object. +

+ +
  1. $entry = new Zend_Gdata_Books_VolumeEntry();
    2. +
  2. $entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID));
    3. +
  3. $entry->setRating(new Zend_Gdata_Extension_Rating(3, 1, 5, 1));
    4. +
  4. $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI);
+ +
+ +

Reviews

+ + +

+ In addition to ratings, authenticated users can submit reviews or + edit their reviews. For information on how to request previously + submitted reviews, see » Retrieving annotations. +

+ +

Adding a review

+ + +

+ To add a review, add a Review object to a + VolumeEntry and post it to the annotation + feed. In the example below, we start from an existing + VolumeEntry object. +

+ +
  1. $annotationUrl = $entry->getAnnotationLink()->href;
    2. +
  2. $review        = new Zend_Gdata_Books_Extension_Review();
    3. +
  3.  
    4. +
  4. $review->setText("This book is amazing!");
    5. +
  5. $entry->setReview($review);
    6. +
  6. $books->insertVolume($entry, $annotationUrl);
+ +
+ +

Editing a review

+ + +

+ To update an existing review, first you retrieve the + review you want to update, then you modify it, and + then you submit it to the annotation feed. +

+ +
  1. $entryUrl = $entry->getId()->getText();
    2. +
  2. $review   = new Zend_Gdata_Books_Extension_Review();
    3. +
  3.  
    4. +
  4. $review->setText("This book is actually not that good!");
    5. +
  5. $entry->setReview($review);
    6. +
  6. $books->updateVolume($entry, $entryUrl);
+ +
+
+ +

Labels

+ + +

+ You can use the Book Search Data API to label volumes with + keywords. A user can submit, retrieve and modify labels. See + » Retrieving + annotations for how to read previously submitted labels. +

+ +

Submitting a set of labels

+ + +

+ To submit labels, add a Category object + with the scheme LABELS_SCHEME to a + VolumeEntry and post it to the annotation feed. +

+ +
  1. $annotationUrl = $entry->getAnnotationLink()->href;
    2. +
  2. $category      = new Zend_Gdata_App_Extension_Category(
    3. +
  3.     'rated',
    4. +
  4.     'http://schemas.google.com/books/2008/labels');
    5. +
  5. $entry->setCategory(array($category));
    6. +
  6. $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI);
+ +
+
+ +

Retrieving annotations: reviews, ratings, and labels

+ + +

+ You can use the Book Search Data API to retrieve annotations + submitted by a given user. Annotations include reviews, ratings, and + labels. To retrieve any user's annotations, you can send an + unauthenticated request that includes the user's user ID. To retrieve the + authenticated user's annotations, use the value me as the user + ID. +

+ +
  1. $feed = $books->getVolumeFeed(
    2. +
  2.             'http://www.google.com/books/feeds/users/USER_ID/volumes');
    3. +
  3. <i>(or)</i>
    4. +
  4. $feed = $books->getUserAnnotationFeed();
    5. +
  5.  
    6. +
  6. // print title(s) and rating value
    7. +
  7. foreach ($feed as $entry) {
    8. +
  8.     foreach ($feed->getTitles() as $title) {
    9. +
  9.         echo $title;
    10. +
  10.     }
    11. +
  11.     if ($entry->getRating()) {
    12. +
  12.         echo 'Rating: ' . $entry->getRating()->getAverage();
    13. +
  13.     }
    14. +
  14. }
+ + +

+ For a list of the supported query parameters, see the + » query parameters + section. +

+
+ +

Deleting Annotations

+ + +

+ If you retrieved an annotation entry containing ratings, + reviews, and/or labels, you can remove all annotations + by calling deleteVolume() on that entry. +

+ +
  1. $books->deleteVolume($entry);
+ +
+
+ +

Book collections and My Library

+ + +

+ Google Book Search provides a number of user-specific + book collections, each of which has its own feed. +

+ +

+ The most important collection is the user's My Library, which + represents the books the user would like to remember, organize, and + share with others. This is the collection the user sees when accessing + his or her » My Library + page. +

+ +

Retrieving books in a user's library

+ + +

+ The following sections describe how to retrieve a list + of books from a user's library, with or without query + parameters. +

+ +

+ You can query a Book Search public feed without authentication. +

+ +

Retrieving all books in a user's library

+ + +

+ To retrieve the user's books, send a query to the + My Library feed. To get the library of the authenticated + user, use me in place of USER_ID. +

+ +
  1. $feed = $books->getUserLibraryFeed();
+ + +

+ Note: The feed may not contain all of the user's books, because + there's a default limit on the number of results returned. For + more information, see the max-results query parameter in + » Searching for books. +

+
+ +

Searching for books in a user's library

+ + +

+ Just as you can » search across all books, + you can do a full-text search over just the books in a + user's library. To do this, just set the appropriate + paramters on the VolumeQuery object. +

+ +

+ For example, the following query returns all the books in + your library that contain the word "bear": +

+ +
  1. $query = $books->newVolumeQuery(
    2. +
  2.     'http://www.google.com/books/feeds/users' .
    3. +
  3.     '/USER_ID/collections/library/volumes');
    4. +
  4. $query->setQuery('bear');
    5. +
  5. $feed = $books->getVolumeFeed($query);
+ + +

+ For a list of the supported query parameters, see the + » query parameters + section. In addition, you can search for books that have been + » labeled by the user: +

+ +
  1. $query = $books->newVolumeQuery(
    2. +
  2.     'http://www.google.com/books/feeds/users/' .
    3. +
  3.     'USER_ID/collections/library/volumes');
    4. +
  4. $query->setCategory(
    5. +
  5. $query->setCategory('favorites');
    6. +
  6. $feed = $books->getVolumeFeed($query);
+ +
+
+ +

Updating books in a user's library

+ + +

+ You can use the Book Search Data API to add a book to, or remove + a book from, a user's library. Ratings, reviews, and labels are valid + across all the collections of a user, and are thus edited using the + annotation feed (see » Using community features). +

+ +

Adding a book to a library

+ + +

+ After authenticating, you can add books to the current user's library. +

+ +

+ You can either create an entry from scratch if you + know the volume ID, or insert an entry read from any feed. +

+ +

+ The following example creates a new entry and adds it to the library: +

+ +
  1. $entry = new Zend_Gdata_Books_VolumeEntry();
    2. +
  2. $entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID));
    3. +
  3. $books->insertVolume(
    4. +
  4.     $entry,
    5. +
  5.     Zend_Gdata_Books::MY_LIBRARY_FEED_URI
    6. +
  6. );
+ + +

+ The following example adds an existing + VolumeEntry object to the library: +

+ +
  1. $books->insertVolume(
    2. +
  2.     $entry,
    3. +
  3.     Zend_Gdata_Books::MY_LIBRARY_FEED_URI
    4. +
  4. );
+ +
+ +

Removing a book from a library

+ + +

+ To remove a book from a user's library, call + deleteVolume() on the + VolumeEntry object. +

+ +
  1. $books->deleteVolume($entry);
+ +
+
+
+
+
+ + + + + + + + + +
+ Authenticating with AuthSub + +
Zend_Gdata
+ Programmer's Reference Guide
+ 		+ +
+		 + +
+ + \ No newline at end of file -- cgit v1.2.3