使用入门

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

简介

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

前期准备

获取 Google 帐户

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

熟悉图书

如果您不熟悉 Google 图书中的概念,则应先阅读本文档并试用界面,然后再开始编写代码。本文档假定您熟悉 Web 编程概念和 Web 数据格式。

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

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

具体而言,Google 图书 API 中“我的书库”下的所有操作都会被视为私有操作,需要进行身份验证和授权。此外,任何修改 Google 图书数据的操作都只能由拥有相应数据的用户执行。

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

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

Books API 背景

图书概念

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

  • 数量:卷代表 Google 图书托管的图书或杂志数据。它是 Books API 中的主要资源。此 API 中的所有其他资源均包含或注释卷。
  • 书架:书架是卷的集合。Google 图书为每位用户提供了一组预定义的书架,其中有些书架是完全由用户管理的,有些则会根据用户的活动自动填充,而有些则混在一起。用户可以创建、修改或删除其他始终会手动填充卷的书架。用户可以将书架设为私有或公开。

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

  • 评价:评价是指对星级和/或文字的评价。用户可以为每卷提交一条评价。评价也可以从外部来源获得,并会进行适当归因。
  • 读取位置:读取位置用于指示卷中用户的最后读取位置。用户在每个卷上只能有一个读取位置。如果用户之前没有打开过该卷,则表示读取位置不存在。读取位置可以存储详细的位置信息,一直到一个单词的分辨率。此信息始终仅对用户公开。

Books API 数据模型

资源是指具有唯一标识符的单个数据实体。Books API 可根据上述概念对两种类型的资源执行操作:

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

Books API 数据模型基于称为“资源集”的资源组:

收集卷
卷集合是指由 Google 图书管理的每个卷资源的集合。因此,您不能列出所有卷资源,但可以列出与一组搜索字词匹配的所有卷。
书架
书架集合由 Google 图书管理的所有书架资源组成。必须始终在特定用户的库的上下文中引用书架。书架可以包含零个或更多卷。

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

  • 收藏:可变的书架。
  • 已购买:填充了用户购买的卷。用户无法手动添加或移除卷。
  • 阅读:可变书架。
  • 立即阅读:可变书架。
  • 已读:可变书架。
  • 已审核:填充了用户已审核的卷。用户无法手动添加或移除卷。
  • 最近查看过:填充了用户最近在网络阅读器中打开的卷。用户无法手动添加卷。
  • 我的电子书:可变的书架。系统会自动添加所购买的图书,但您可以手动将其移除。
  • 为您推荐的图书:填充了个性化推荐量。如果我们没有向用户推荐,那么此书架不存在。

书架示例:

  • “收藏夹”
    • “哈利·波特”
  • “我的电子书”
    • “切换”
    • “暮光之城”
    • “The Girl with the Dragon 纹身”

Books API 操作

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

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

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

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

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

调用样式

您可以通过多种方式调用该 API:

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

REST

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

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

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

在 Google 的 REST API 中,客户端会使用 HTTP 动词(如 POSTGETPUTDELETE)指定操作。它通过以下形式的全局唯一 URI 指定资源:

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

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

您可能会发现 HTTP 1.1 标准文档中的方法定义十分有用;这些定义中包含了 GETPOSTPUTDELETE 的规范。

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(也称为 JSON-P)中的 REST 调用 Books API。这样,您无需编写任何服务器端代码,即可编写显示图书数据的丰富应用。

注意:您可以使用 access_token 参数传递 OAuth 2.0 令牌,以调用经过身份验证的方法。要获取 OAuth 2.0 令牌以用于 JavaScript,请按照适用于客户端 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