开始使用

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

1. 简介
2. 开始前须知
   1. 获取 Google 账号
   2. 熟悉 Google 图书
   3. 了解如何向请求授权并让 Google 识别您的应用
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 图书

如果您不熟悉 Google 图书的概念，请在开始编码之前阅读本文档并试用界面。本文档假定您熟悉 Web 编程概念和 Web 数据格式。

了解如何授权请求和标识您的应用

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

具体而言，Google Books API 中“我的图书馆”下的所有操作都被视为私密操作，需要进行身份验证和授权。此外，只有相应 Google 图书数据的所有者才能执行修改该数据的任何操作。

当您的应用请求公开的数据时，该请求不需要经过授权，但需要附带身份识别标记，如 API 密钥。

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

Books API 背景信息

图书概念

Google 图书基于以下四个基本概念构建：

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

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

• 评价：图书评价是星级评分和/或文字的组合。每本图书只能提交一次评价。我们还会提供来自外部来源的评价，并注明相应来源。
• 阅读位置：阅读位置是指用户在图书中上次阅读的位置。每个用户在每本图书中只能有一个阅读位置。如果用户之前未打开过相应卷，则不存在阅读位置。阅读位置可以存储详细的位置信息，精确到字词级别。此信息始终对用户保密。

Books API 数据模型

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

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

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

音量收集

图书合集是 Google 图书管理的所有图书资源的集合。 因此，您无法列出所有卷资源，但可以列出与一组搜索字词匹配的所有卷。

书架合集

书架集合包含由 Google 图书管理的所有书架资源。 书架必须始终在特定用户的媒体库中引用。 书架可以包含零个或多个图书。

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

• 收藏夹：可变书架。
• 已购买：填充用户已购买的图书。用户无法手动添加或移除卷。
• 待读：可变书架。
• 正在阅读：可变书架。
• 已读：可变书架。
• 已查看：填充用户已查看的图书。用户无法手动添加或移除卷。
• 最近查看：填充用户最近在网络阅读器中打开的图书。用户无法手动添加音量。
• 我的电子书：可变书架。已购图书会自动添加，但可以手动移除。
• 为您推荐的图书：包含个性化的图书推荐。如果我们没有针对用户的任何推荐，则此书架不存在。

书架示例：

• “收藏夹”
• “哈利·波特”
• “我的电子书”
• “切换”
• “Twilight”
• 《龙纹身的女孩》

Books API 操作

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

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

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

资源类型	支持的操作
	list	insert	get	更新	删除
卷	是*		是
书架	是*	是，已通过身份验证	是*	是，已通过身份验证	是，已通过身份验证
阅读位置		是，已通过身份验证	是，已通过身份验证	是，已通过身份验证	是，已通过身份验证

*这些操作提供已通过身份验证和未通过身份验证的版本，其中已通过身份验证的请求可对用户的私密“我的库”数据执行操作，而未通过身份验证的请求只能对公开数据执行操作。

调用样式

您可以通过以下几种方式调用 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

受支持的 Books 操作直接映射到 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

您可以使用 JavaScript（也称为 JSON-P）通过 REST 调用 Books API，方法是使用 callback 查询参数和回调函数。这样一来，您无需编写任何服务器端代码即可编写显示图书数据的丰富应用。

注意：您可以使用 access_token 参数传递 OAuth 2.0 令牌来调用经过身份验证的方法。如需获取用于 JavaScript 的 OAuth 2.0 令牌，请按照适用于客户端 Web 应用的 OAuth 2.0 中的说明操作。在 API 控制台的“API 访问权限”标签页中，请务必为 Web 应用设置客户端 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。