Google Book Search APIs-----Data API

Data API: 开发者的指南，协议

Google Book Search Data API允许客户端应用程序浏览和更新在Google Data API中的图书内容。

你的客户端程序能够使用Book Searc Data API发布全文检索的图书和检索标准的图书信息、等级、评论。你也可以访问个人用户图书馆和公关评语。最终，你的应用程序能够提交验证后的请求以使用户建立和修改图书馆、等级、标签、评论和其他指定账户的内容。

除了提供一些图书查找数据API的能力外，这个文档还提供了基本的使用xml和http的应用程序接口。当阅读完这个文档，你可以通过阅读这个开发者指南的programming-language-specific部分学习更多的关于使用我们客户端库相互配合的API。

1、 Audience (读者)

这个文档是为想要通过使用xml和http写与Google Book Search相交互的客户端应用程序的程序员准备的。

这里假设你已经了解了Google Data API协议背后的基本概念，并且你熟悉Google Book Search 和My Library特点。

如果你使用的是UNIX系统，并且你想要不写任何代码而尝试这里的例子，你可能发现UNIX命令行工具curl和wget很有用；更多的信息参照它们的指南。对于Book Search Data API索引信息，参照协议索引指南。

2、 Getting started(入门)

建立一个图书查找帐号

出于测试目的，你可能想建立一个图书查找库。Book Search使用Google帐号，所以如果你已经有了一个Google帐号，你就能在我的图书馆使用这个帐号。

3、Authenticating to the Book Search service

使用Book Search Data API你可以访问所有共有和私有的反馈信息。共有的反馈信息不要求任何的认证，但是它们是只读的。如果你打算修改用户图书馆，提交评论、等级或者添加标签，那么你的客户端在请求私有反馈前需要认证。能够使用两种方式认证：AuthSub代理认证和客户端登录用户名/密码认证。

更多的关于Google Data API的认证，参照认证文档。

文档后面的小结的大部分例子假设你已经提供了适当的认证。

AuthSub proxy authentication

AuthSub代理认证是在需要认证账户的web应用程序中使用。网站的操作者和客户端代码不能访问用户名和密码；客户端取得指定的AuthSub令牌，它允许客户端扮演特定用户的行为。更多详细的信息，参照AuthSub文档。

当一个用户第一次访问你的应用程序时，他还没有被认证。这种情况，你需要显示一些信息和链接引导用户到Google网页去认证你的请求以访问他们的帐号。

下面是AuthSubRequest URL中的参数：

next

Google在认证后将要重定向用户的网页URL

scope

指出应用程序在请求一个访问图书查找反馈的令牌。这个Scopi字符串应该使用http://www.google.com/books/feeds/ 。

secure

指出客户端是否请求一个secure令牌。

session

指出对于一个多用途的令牌返回后是否可以被改变。

AuthSubRequest URL可能像这样：https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.google.com%2Fbooks%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

用户使用这个链接去Google网站并且认证他的账户。

用户认证之后，AuthSub系统重新定向之前指定的next参数中的url。AuthSub系统添加一个认证的令牌环到这个URL,作为token参数的值。例如：http://www.example.com/welcome.html?token=yourAuthToken

这个token的值代表一次性的AuthSub令牌。在这个例子中，因为session被指定为1，这个令牌在认证头部，通过调用AuthSubSessionToken服务，可以被变为一个AuthSub回话令牌，如下：

GET /accounts/AuthSubSessionToken HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Authorization: AuthSub token="yourAuthToken"

User-Agent: Java/1.5.0_06

Host: www.google.com

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

Connection: keep-alive

AuthSubSessionToken服务响应包含一个令牌头部和终止头部，令牌头部中有会话令牌，终止头部指出这个令牌还有多久失效。

你的应用程序可以在请求序列的认证头部使用这个会话令牌值与图书查找交互。

这里有一个HTTP请求的例子，包含一个非secure令牌，即你可能发送的图书搜索：

GET http://www.google.com/books/feeds/users/me/volumes HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Authorization: AuthSub token="yourSessionToken"

User-Agent: Java/1.5.0_06

Host: www.google.com

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

Connection: keep-alive

客户端登录用户名/密码认证

如果你的客户端是一个独立的，单用户安装的客户端(如桌面应用程序)，那么使用客户端登录认证。使用客户端登录方法取得认证的令牌，发送一个如下POST请求的URL：https://www.google.com/accounts/ClientLogin

POST中应该包含一组查询参数，就像使用application/x-www-form-urlencoded content type的html表单一样的参数。参数有：

accountType

将要被认证的账户类型，默认是GOOGLE；如果你想要支持Google Apps用户，那么使用HOSTED_OR_GOOGLE。

Email

用户的email地址

Passwd

用户的密码

service

写Book Search服务的名字。(对于其他服务的名字，参照服务名字列表)

source

指出你的客户端应用程序。应该有 公司名-应用程序名-版本id。

关于参数的更多信息，参照安装应用程序文档的认证。

如果认证请求失败，服务器返回HTTP403禁止状态代码。

如果成功，服务器返回HTTP200 OK状态代码，在响应体中加上3个长字母数字代码：SID,LSID,Auth。Auth值是你将要发送给图书所搜的认证令牌，所以保存这个值的拷贝。你可以忽略SID和LSID值。

由于所有私有反馈都要求认证，所以你必须在随后的所以图书搜索交互中设置这个认证头部，使用下面的格式：

Authorization: GoogleLogin auth=yourAuthToken

所有你的认证令牌(AuthToken)都是通过客户端登录请求返回的Auth字符串。

更多的关于客户端登录认证信息，以及request和response的例子，参照安装应用程序文档的认证。

注意：在所给定的会话中的所有请求里使用相同的令牌；不要为每一个图书搜索请求得到一个新的令牌。

4、Setting user location设置用户位置

Google Book Search 尊重版权、合同和最终用户国家的其他相关法律限制。

所以，一些指定国家的用户可能不允许访问一些图书内容。例如，指定的图书只能在美国被预览；我们省略到其他国家用户的这些图书的预览链接。

为确保你的应用程序用户接受到准确且一致的结果，我们建议你应该在发给图书搜索API的每一个查询中添加最终用户的IP地址。Book Search可以通过用户的IP地址高准确性地判定用户所在的国家，相应地也允许Book Search准确地判定那些内容能够提供给用户。我们在Book SearchGUI中使用相同的技术判定一个预览是否可以提供给指定的用户。

图书搜索数据API只提供指定的理想的图书作为搜索结果，这些可以从世界的任何位置访问到。(The Book Search Data API provides only search results--pointers to the desired books--which are accessible from anywhere in the world.这句翻译不好)那么，如果你显示结果给用户，那么用户将不能浏览。所以在请求时请提供用户的IP地址，以避免显示用户不能浏览的结果。

发送含有用户的IP地址的请求，简单地添加或修改你的HTTP请求中X-Forwarded-For头部：

X-Forwarded-For: user's IP address

默认的，API结果指出基于你服务器或客户端应用程序的IP地址的限制

5、Searching for books 搜索图书

Book Search Data API提供一些图书的反馈。

通常的动作是检索匹配搜索词的图书清单。这样做，提交一个HTTP GET请求到下面的URL，添加适当的查询参数：http://books.google.com/books/feeds/volumes

注意图说搜索通常使用volume指明一本书，所以卷标反馈就是图书反馈。

下面的例子搜索第二组图书(10个一组)，这些书中元数据或文本中要批评football但是不能匹配soccer：

http://books.google.com/books/feeds/volumes?

    q=football+-soccer

    &start-index=11

    &max-results=10

你发送完这个GET请求后，Book Search可能返回一个重定向，这取决有各种因素。如果这样，再次发送GET请求的重定向URL。

当你发送GET请求，Book Search返回一个HTTP 200 OK状态代码和包含匹配搜索条件的图书列表反馈。

注意：由于Book Search结果是公共的，你可以发送图书搜索查询而无需认证。

Book Search Data API支持下面的参数：

q

指定搜索查询字词。Book Search搜寻所有图书的元数据和全文以匹配查询的字词。图书元数据包括标题、关键字、描述、作者姓名和科目。

请注意，任何空格，引号或其他标点符号中的参数值必须被网址转译。(使用一个加号(+)替代空格。) 

为了精确搜索词组，附上一句引号把词组包含。例如，要搜索的书籍匹配短语“spy plane” ，设置q参数为%22spy+plane%22。

你也可以通过Book Search使用任何高级的搜索操作支持。例如，jane+austen+-inauthor:austen返回匹配提到的（但不是authored）Jane Austen。

start-index

指定在返回结果集中第一个匹配结果的索引。此参数使用一个基础的索引，这意味着第一个结果是1 ，第二个结果是2 ，等等。