使用入门

本文档详细介绍了使用 Google Books API 所需的背景知识。

1. 简介
2. 准备工作
   1. 获取 Google 账号
   2. 熟悉图书
   3. 了解如何向请求授权以及识别应用
3. Books API 背景
   1. 图书概念
   2. Books API 数据模型
   3. Books API 操作
4. 调用样式
   1. REST
5. 数据格式
   1. JSON

简介

本文档适用于希望编写可与 Google Books API 进行交互的应用的开发者。Google 图书的愿景是对全世界的图书进行数字化。您可以使用 Google Books API 搜索内容、整理经过身份验证的用户的个人库，还可以对其进行修改。

前期准备

获取 Google 账户

您需要一个 Google 帐号进行测试。如果您已经拥有测试帐号，那么就大功告成了；您可以访问 Google 图书界面，设置、修改或查看您的测试数据。

熟悉图书

如果您不熟悉 Google 图书中的相关概念，则应在开始编码之前阅读本文档并练习使用界面。本文档假定您熟悉 Web 编程的概念和 Web 数据格式。

了解如何向请求授权和识别应用

当您的应用请求不公开的数据时，该请求必须经过有权访问相应数据并且已经过身份验证的用户授权。

特别是，Google Books API 中“我的图书馆”下的所有操作都被视为私人操作，并且需要身份验证和授权。此外，修改 Google 图书数据的任何操作都只能由拥有这些数据的用户执行。

当您的应用请求公开数据时，该请求不需要授权，但需要附带标识符，例如 API 密钥。

如需了解如何向请求授权和使用 API 密钥，请参阅“使用 API”文档中的向请求授权并识别应用。

Books API 背景

图书概念

Google 图书建立在四个基本概念之上：

• 卷：卷表示 Google 图书托管的关于图书或杂志的数据。它是 Books API 中的主要资源。此 API 中的所有其他资源都包含卷或为卷添加注释。
• Bookshelf：书架是一系列卷的集合。Google 图书为每位用户提供了一组预定义的书架，其中一些书架完全由用户管理，一些会根据用户的活动自动填充，还有一些则是混合书架。用户可以创建、修改或删除其他书架（一律手动填充卷）。书架可由用户设为不公开或公开。

  注意：目前只能通过 Google 图书网站创建和删除书架以及修改书架的隐私设置。

• 评价：卷评价是星级和/或文字的组合。用户可针对每卷提交一条评价。也可以从外部来源获取评价，并进行适当归类。
• 读取位置：读取位置表示用户最后一次在卷中读取的位置。用户在每个音量中只能有一个阅读位置。如果用户之前没有打开过该卷，则读取位置不存在。读取位置可以存储详细位置信息，精确到某个字词的分辨率。此类信息始终只有用户可以看到。

Books API 数据模型

资源是指具有唯一标识符的单个数据实体。根据上述概念，Books API 可以在两种类型的资源上运行：

• 卷资源：表示卷。
• Bookshelf 资源：表示特定用户的单个书架。

Books API 数据模型基于称为集合的资源组：

卷收集

卷集是指由 Google 图书管理的每个卷资源的集合。 因此，您不能 list 所有卷资源，但可以 list 与一组搜索字词匹配的所有卷。

书架集合

bookshelf 集合包含由 Google 图书管理的所有书架资源。书架必须始终在特定用户的图书馆中引用。 书架可以包含 0 卷或更多卷。

Google 为每位用户提供了一组预定义的书架：

• 收藏夹：可变书架。
• 已购买数量：填充用户购买数量。用户无法手动添加或移除卷。
• 待读取：可变书架。
• 正在阅读：可变书架。
• 已阅读：可变书架。
• 已审核：填充用户已审核的卷。用户无法手动添加或移除卷。
• 近期查看过：填充用户最近在网络阅读器中打开的卷。用户无法手动添加卷。
• 我的电子书：可变书架。系统会自动添加您购买的图书，但您也可以手动移除。
• 为您推荐的图书：填充了个性化量推荐。如果我们没有向用户提供推荐，则此书架不存在。

书架示例：

• “收藏夹”
• “哈利波特”
• “我的电子书”
• “切换”
• “暮光”
• “龙纹身的女孩”

Books API 操作

您可以对 Books API 中的集合和资源调用五种不同的方法，如下表所述。

操作	说明	REST HTTP 映射
list	列出集合中的指定资源子集。	对集合 URI 执行 GET。
insert	将新资源插入集合（创建新资源）。	对集合 URI 执行 POST 操作，您可以在其中传入新资源的数据。
get	获取特定资源。	对资源 URI 执行 GET 操作。
update	更新特定资源。	对资源 URI 执行 PUT 操作，您可以在其中传入更新后的资源的数据。
删除	删除特定资源。	对资源 URI 执行 DELETE 操作，您可以在其中传入要删除的资源的数据。

下表总结了各种类型资源支持的操作。适用于用户私有数据的操作称为“我的库”操作，它们都需要进行身份验证。

资源类型	支持的操作
	列表	插入	获取	更新	删除
卷	是*		是
书架	是*	是，经过身份验证	是*	是，经过身份验证	是，经过身份验证
阅读位置		是，经过身份验证	是，经过身份验证	是，经过身份验证	是，经过身份验证

*这些操作的 AUTHENTICATED 和未经过身份验证的版本都可用，其中经过身份验证的请求对用户的私有“我的库”数据执行操作，而未经身份验证的请求仅对公开数据执行。

调用样式

您可以通过以下几种方式调用该 API：

• 直接使用 REST
• 使用 JavaScript 中的 REST（无需服务器端代码）

REST

REST 是一种软件架构样式，可提供便捷且一致的方法用于请求和修改数据。

术语 REST 是“具象状态传输”的简称。在 Google API 的上下文中，指的是使用 HTTP 谓词来检索和修改由 Google 存储的数据的表示法。

在 RESTful 系统中，资源存储在数据存储区中；在客户端发送要求服务器执行特定操作（例如创建、检索、更新或删除资源）的请求之后，服务器便会执行该操作并发送响应，此响应的格式通常为所指定资源的表示法。

在 Google 的 RESTful API 中，客户端使用 HTTP 动词（例如 POST、GET、PUT 或 DELETE）指定操作。它通过以下形式的全局唯一 URI 指定资源：

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

由于所有 API 资源都具有 HTTP 可访问的唯一 URI，因此 REST 启用了数据缓存，而且经过优化以与网络的分布式基础架构一起使用。

您可能会发现 HTTP 1.1 标准文档中的方法定义十分有用；这些定义中包含了 GET、POST、PUT 和 DELETE 的规范。

Books API 中的 REST

受支持的图书操作直接映射到 REST HTTP 动词，如 Books API 操作中所述。

Books API URI 的具体格式为：

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

其中 resourceID 是卷或书架资源的标识符，parameters 是要应用于查询的任何参数。如需了解详情，请参阅查询参数参考。

通过 resourceID 路径扩展的格式，您可以标识当前正在操作的资源，例如：

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

请注意，在 URI 中使用 mylibrary 的操作仅适用于当前经过身份验证的用户的私有库数据。Books API 参考文档文档总结了用于 API 中各项受支持操作的全部 URI。

下面的几个示例展示了它在 Books API 中的工作方式。

搜索“绗缝”效果：

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

获取有关卷 s1gVAAAAYAAJ 的信息：

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

JavaScript 中的 REST

借助 callback 查询参数和回调函数，您可以使用 JavaScript 中的 REST（也称为 JSON-P）调用 Books API。这样，您就可以编写功能丰富的应用来显示 Google 图书数据，而无需编写任何服务器端代码。

注意：您可以使用 access_token 参数传递 OAuth 2.0 令牌，以调用经过身份验证的方法。要获取与 JavaScript 搭配使用的 OAuth 2.0 令牌，请按照适用于客户端 Web 应用的 OAuth 2.0 中的说明操作。在API 控制台的“API 访问权限”标签中，请务必为网络应用设置客户端 ID，并在获取令牌时使用这些 OAuth 2.0 凭据。

以下示例使用此方法显示“哈利·波特”的搜索结果：

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

数据格式

JSON

JSON（JavaScript 对象表示法）是一种与语言无关的常见数据格式，可通过简单的文本来表示任意数据结构。如需了解详情，请参阅 json.org。