此页面由 Cloud Translation API 翻译。

使用 API

简介

本文档适用于想要编写可与 Books API 交互的应用的开发者。Google 图书的使命是将全世界的图书内容数字化，并使其能在网上更容易被用户发现。Books API 可用于搜索和访问相应内容，以及针对相应内容创建和查看个性化内容。

如果您不熟悉 Google 图书中的概念，则应在开始编写代码之前阅读使用入门。

为请求授权并识别您的应用

您的应用向 Books API 发送的每个请求都需要向 Google 标识您的应用。您可以通过两种方式来标识应用：使用 OAuth 2.0 令牌（也用于向请求授权）和/或使用应用的 API 密钥。下文介绍了如何确定使用哪种方式：

如果请求需要授权（例如对个人隐私数据的请求），则应用必须在请求中提供 OAuth 2.0 令牌。应用也可提供 API 密钥，但并非必须如此。
如果请求不需要授权（例如对公开数据的请求），则应用必须提供 API 密钥或 OAuth 2.0 令牌，或者同时提供两者（选择对您而言最方便的方式即可）。

关于授权协议

您的应用必须使用 OAuth 2.0 向请求授权，其他任何授权协议均不受支持。如果您的应用使用使用 Google 帐号登录，系统会代您执行授权方面的某些操作。

使用 OAuth 2.0 向请求授权

针对非公开用户数据向 Books API 发出的请求必须由经过身份验证的用户授权。

根据您所开发的应用的类型，OAuth 2.0 的具体授权流程可能会有所不同。下面是适用于所有应用类型的大致流程：

开发应用时，您需要使用 Google API 控制台注册该应用。然后，Google 会提供您稍后需要用到的信息，例如客户端 ID 和客户端密钥。
在 Google API 控制台中激活 Books API。（如果 API 控制台中未列出该 API，请跳过此步骤。）
当您的应用需要访问用户数据时，它会请求 Google 提供特定范围的访问权限。
Google 会向相应用户显示权限请求页面，让用户授权您的应用请求他们的某些数据。
待该用户同意后，Google 会为您的应用提供一个时效很短的访问令牌。
您的应用会请求获取用户数据，并在请求中附上该访问令牌。
如果 Google 确定您的请求及令牌有效，就会返回您所请求的数据。

有些流程还包含其他步骤，例如使用刷新令牌获取新的访问令牌。如需详细了解适用于各类应用的不同流程，请参阅 Google 的 OAuth 2.0 文档。

以下是 Books API 的 OAuth 2.0 范围信息：

https://www.googleapis.com/auth/books

要通过 OAuth 2.0 请求访问权限，您的应用既需要范围信息，也需要您注册应用时 Google 提供的相关信息，如客户端 ID 和客户端密钥。

提示：Google API 客户端库可代您处理部分授权流程，并且支持多种编程语言。如需了解详情，请参阅包含库和示例的页面。

获取和使用 API 密钥

针对 Books API 发出的针对公共数据的请求必须附带标识符，该标识符可以是 API 密钥或访问令牌。

要获取 API 密钥，请执行以下操作：

打开 API 控制台中的“凭据”页面。
此 API 支持两种类型的凭据。创建适合您的项目的凭据：
- OAuth 2.0：当您的应用请求非公开用户数据时，该应用必须将 OAuth 2.0 令牌随请求一起发送。要获取令牌，您的应用应先发送客户端 ID（也可能需要发送客户端密钥）。您可以为网页应用、服务帐号或已安装应用生成 OAuth 2.0 凭据。
  
  如需了解详情，请参阅 OAuth 2.0 文档。
- API 密钥：未提供 OAuth 2.0 令牌的请求必须发送 API 密钥。该密钥用于标识您的项目，并提供 API 访问权限、配额和报告。
  
  此 API 支持多种类型的 API 密钥限制。如果您需要的 API 密钥尚不存在，可以在控制台中通过点击创建凭据 > API 密钥来创建 API 密钥。您可以先对密钥设定相关限制，然后再在生产环境中使用密钥，方法是点击限制密钥，然后选择限制之一。

为保障 API 密钥的安全，请遵循以安全的方式使用 API 密钥的最佳做法。

在您获得 API 密钥后，您的应用便可在所有请求网址后附加查询参数 key=yourAPIKey。

API 密钥可以安全地嵌入网址中，而无需进行任何编码。

Google 图书 ID

您需要通过特定 API 方法调用指定 ID 字段。Google 图书中有三种类型的 ID：

卷 ID - 提供给 Google 图书已知的每个卷的唯一字符串。卷 ID 的一个示例是 _LettPDhwR0C。您可以使用 API 通过发出返回卷资源的请求来获取卷 ID；您可以在其 id 字段中找到卷 ID。
书架 ID - 分配给用户书架中的书架的数字值。Google 为每位用户提供了以下 ID 对应的一些预定义书架：
- 收藏数：0
- 购买的内容数：1
- 阅读：2
- 正在阅读：3
- 已读：4
- 已审核：5
- 最近浏览过：6
- 我的电子书：7
- 为您推荐的图书：8如果我们没有推荐给用户，那么此书架不存在。
自定义书架的 ID 大于 1000。每位用户的书架 ID 都是独一无二的您可以使用 API 通过发出返回书架资源的请求来获取书架 ID；您可以在其 id 字段中找到该书架 ID。
用户 ID - 分配给每位用户的唯一数字值。这些值未必与其他 Google 服务中使用的 ID 值相同。目前，检索用户 ID 的唯一方法是从通过身份验证的请求检索到的 Firestore 资源中的 SelfLink 中提取用户 ID。用户也可以从图书网站获取自己的用户 ID。用户无法通过 API 或图书网站获取其他用户的用户 ID；例如，其他用户必须明确分享该信息（例如，通过电子邮件）。

Google 图书网站上的 ID

您在 Books API 中使用的 ID 与 Google 图书网站上使用的 ID 相同。

卷 ID

在网站上查看特定卷时，您可以在 id 网址参数中找到卷 ID。示例如下：
```
https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
```

书架 ID

在网站上查看特定书架时，您可以在 as_coll 网址参数中找到该书架 ID。示例如下：

https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

用户 ID

在网站上查看库时，您可以在 uid 网址参数中找到用户 ID。示例如下：
```
https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
```

设置用户位置

Google 图书尊重与最终用户的位置相关的版权、合同和其他法律限制。因此，某些用户可能无法从特定国家/地区访问图书内容。例如，某些图书只能在美国进行“可试阅”；对于其他国家/地区的用户，我们会忽略此类试阅链接。因此，系统会根据您的服务器或客户端应用的 IP 地址限制 API 结果。

使用卷

执行搜索

您可以通过向以下 URI 发送 HTTP GET 请求来执行卷搜索：

https://www.googleapis.com/books/v1/volumes?q=search+terms

此请求具有一个必需参数：

q - 搜索包含此文本字符串的卷。您可以在搜索字词中指定在特定字段中搜索的特殊关键字，例如：
- intitle: 返回在标题中找到此关键字后面的文本的结果。
- inauthor: 返回在作者中找到此关键字后面的文本的结果。
- inpublisher: 返回在发布商中找到此关键字后面的文本的结果。
- subject: 返回结果，其中此关键字后面的文本列在卷的类别列表中。
- isbn: 返回此关键字后面的文本是 ISBN 编号的结果。
- lccn: 返回以下关键字的结果：此关键字后面的文本是美国国会图书馆控制号。
- oclc: 返回此关键字后面的文本是在线计算机库中心编号的结果。

请求

以下示例显示了搜索 Daniel Keyes' 的“Algernon 鲜花”：

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

注意：执行搜索时不需要进行身份验证，因此您无需在 GET 请求中提供 Authorization HTTP 标头。但是，如果通过身份验证进行调用，每个卷都将包含特定于用户的信息，例如购买状态。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码，并且显示卷结果：

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

可选查询参数

除了标准查询参数之外，您还可以在执行卷搜索时使用以下查询参数。

下载格式

您可以使用 download 参数将返回的结果限制为具有可用下载格式 epub 的卷，方法是将设置为值 epub。

以下示例搜索支持 ePub 下载的图书：

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey

过滤

您可以使用 filter 参数将其设置为以下值之一，以进一步限制返回的结果：

partial - 返回至少部分文本可预览的结果。
full - 仅返回所有文本均可见的结果。
free-ebooks - 仅返回免费的 Google 电子书搜索结果。
paid-ebooks - 仅返回含有价格的 Google 电子书搜索结果。
ebooks - 仅返回 Google 电子书（有偿或免费）的搜索结果。非电子书的示例包括提供有限试阅且不出售的出版商内容或杂志。

以下示例将搜索结果限制为免费电子书提供的搜索结果：

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey

分页

您可以通过在请求的参数中指定两个值来对卷列表进行分页：

startIndex - 集合中的起始位置。第一项的索引为 0。
maxResults - 要返回的结果数上限。默认值为 10，允许的最大值为 40。

打印类型

您可以使用 printType 参数将返回的结果限制为特定打印或发布类型，方法是将其设置为以下值之一：

all - 不按打印类型限制（默认）。
books - 仅返回属于图书的结果。
magazines - 返回杂志的结果。

以下示例将搜索结果限制为杂志：

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey

Projection

您可以将 projection 参数与以下某个值一起使用，以指定要返回的一组预定义音量字段：

full - 返回所有卷字段。
lite - 仅返回特定字段。如需了解包含哪些字段，请参阅卷参考中标有双星号的字段说明。

以下示例返回的信息量有限：

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey

排序

默认情况下，数量搜索请求会返回 maxResults 结果，其中 maxResults 是分页中使用的参数（见上文），按照与搜索字词的相关性排序。

您可以通过将 orderBy 参数设置为以下值之一来更改排序：

relevance - 按搜索字词相关性返回结果（默认）。
newest - 按从新到旧的顺序返回结果。

以下示例会按发布日期（从最新到最旧）列出结果：

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

检索特定卷

您可以通过向卷资源 URI 发送 HTTP GET 请求来检索特定卷的信息：

https://www.googleapis.com/books/v1/volumes/volumeId

将 volumeId 路径参数替换为要检索的卷的 ID。如需详细了解卷 ID，请参阅 Google 图书 ID 部分。

请求

下面是一个获取单个卷的 GET 请求示例：

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

注意：检索卷信息不需要身份验证，因此您无需为 GET 请求提供 Authorization HTTP 标头。但是，如果通过身份验证进行调用，卷将包含特定于用户的信息，例如购买状态。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码以及请求的 Volume 资源：

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}

访问权限信息

在确定电子书可使用哪些功能时，accessInfo 部分特别有用。epub 是一种灵活文本格式电子书，epub 部分有一个 isAvailable 属性，用于指明此类型的电子书是否可用。如果图书有试阅，或者由于用户已购买该图书或用户所在图书位于用户公共领域而导致用户能够阅读该图书，该图书就会显示下载链接。适用于 Google 图书的 pdf 表示相应图书的扫描版，其中包含类似的详细信息，例如该图书是否可用以及是否有下载链接。Google 建议为电子阅读器和智能手机提供 epub 文件，因为扫描设备可能很难在这些设备上阅读。如果没有“accessInfo”部分，则表示相应卷没有 Google 电子书版本。

可选查询参数

除了标准查询参数之外，您还可以在检索特定卷时使用以下查询参数。

Projection

您可以将 projection 参数与以下某个值一起使用，以指定要返回的一组预定义音量字段：

full - 返回所有卷字段。
lite - 仅返回特定字段。如需了解包含哪些字段，请参阅卷参考中标有双星号的字段说明。

以下示例返回单个卷的有限卷信息：

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

使用书架

检索用户的公开书架列表

通过向以下格式的 URI 发送 HTTP GET 请求，可以检索用户的公开书架列表：

https://www.googleapis.com/books/v1/users/userId/bookshelves

将 userId 路径参数替换为您要检索其书架的用户的 ID。如需详细了解用户 ID，请参阅 Google 图书 ID 部分。

请求

示例如下：

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

由于用户无需进行身份验证即可检索公共书架的相关信息，因此您无需向 Authorization HTTP 标头提供 GET 请求。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码和书架列表：

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

可选查询参数

检索用户的公开书架列表时，您可以使用标准查询参数。

检索特定的公开书架

通过向以下 URI 发送 HTTP GET 请求，可以检索特定的公共书架：

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

将 userId 和书架路径参数替换为用于指定用户以及您要检索的书架的 ID。如需了解详情，请参阅 Google 图书 ID 部分。

请求

示例如下：

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

由于用户无需进行身份验证即可检索公共书架的相关信息，因此您无需向 Authorization HTTP 标头提供 GET 请求。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码和书架资源：

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

可选查询参数

检索特定的公开书架时，您可以使用标准查询参数。

检索公共书架上的卷列表

您可以通过发送 HTTP GET 请求以下格式的 URI 来检索用户公共书架上的卷列表：

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

请求

示例如下：

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

将 userId 和书架路径参数替换为用于指定用户以及您要检索的书架的 ID。如需了解详情，请参阅 Google 图书 ID 部分。

由于用户无需进行身份验证即可检索公共书架的相关信息，因此您无需向 Authorization HTTP 标头提供 GET 请求。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码以及用户书架的列表：

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

可选查询参数

除了标准查询参数之外，在检索公共书架上的卷列表时，您还可以使用以下查询参数。

分页

您可以通过在请求的参数中指定两个值来对卷列表进行分页：

startIndex - 集合中的起始位置。第一项的索引为 0。
maxResults - 要返回的结果数上限。默认值为 10，允许的最大值为 40。

使用“我的书库”中的书架

所有“我的内容库”请求都会应用于通过身份验证的用户的数据。

检索我的书架列表

通过向以下 URI 发送 HTTP GET 请求，可以获取所有经过身份验证的用户书架的列表：

https://www.googleapis.com/books/v1/mylibrary/bookshelves

请求

示例如下：

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

注意：用户必须经过身份验证才能检索“我的书库”书架列表。因此，您必须为 Authorization HTTP 标头提供 GET 请求。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码以及当前经过身份验证的用户的所有书架的列表：

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

可选查询参数

在检索经过身份验证的用户书架的列表时，您可以使用标准查询参数。

检索书架上的卷列表

通过向以下格式的 URI 发出 HTTP GET 请求，可以检索经过身份验证的用户的书架上的卷列表：

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

将书架路径参数替换为书架的 ID。如需详细了解书架 ID，请参阅 Google 图书 ID 部分。

请求

示例如下：

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

注意：用户必须经过身份验证才能检索“我的书库”卷列表。因此，您必须在 GET 请求中提供 Authorization HTTP 标头。

响应

如果请求成功，服务器将返回 200 OK HTTP 状态代码以及书架卷列表：

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

可选查询参数

除了标准查询参数之外，在检索经过身份验证的某位用户的书架上的卷列表时，您还可以使用以下查询参数。

分页

您可以通过在请求的参数中指定两个值来对卷列表进行分页：

startIndex - 集合中的起始位置。第一项的索引为 0。
maxResults - 要返回的结果数上限。默认值为 10。

正在将书架添加到我的书架

如需将卷添加到经过身份验证的用户的书架中，请按以下格式向 URI 发送 HTTP POST 请求：

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

将书架路径参数替换为书架的 ID。如需详细了解书架 ID，请参阅 Google 图书 ID 部分。

该请求具有一个必需的查询参数：

volumeId - 卷的 ID。如需详细了解卷 ID，请参阅 Google 图书 ID 部分。

请求

下面举例说明了如何向“收藏夹”书架添加“阿尔及利亚鲜花”：

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注意：用户必须经过身份验证才能对书架进行修改，因此您必须在 POST 请求中提供 Authorization HTTP 标头。不过，此 POST 不需要任何数据。

响应

如果请求成功，服务器将返回 204 No Content HTTP 状态代码。

可选查询参数

将某个卷添加到经过身份验证的某位用户的书架时，您可以使用标准查询参数。

从书架中移除卷

如需从经过身份验证的用户的书架中移除卷，请按以下格式将 HTTP POST 发送到 URI：

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

将书架路径参数替换为书架的 ID。如需详细了解书架 ID，请参阅 Google 图书 ID 部分。

该请求具有一个必需的查询参数：

volumeId - 卷的 ID。如需详细了解卷 ID，请参阅 Google 图书 ID 部分。

请求

以下示例显示了从“收藏夹”书架中移除“阿尔及利亚鲜花”：

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注意：用户必须经过身份验证才能对书架进行修改，因此您必须在 POST 请求中提供 Authorization HTTP 标头。不过，此 POST 不需要任何数据。

响应

如果请求成功，服务器将返回 204 No Content 状态代码。

可选查询参数

从经过身份验证的用户的一个书架中移除卷时，您可以使用标准查询参数。

清除书架中的所有卷

如需从经过身份验证的用户的书架中移除所有卷，请按以下格式向 URI 发送 HTTP POST：

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

将书架路径参数替换为书架的 ID。如需详细了解书架 ID，请参阅 Google 图书 ID 部分。

请求

以下是清除“收藏夹”书架的示例：

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注意：用户必须经过身份验证才能对书架进行修改，因此您必须在 POST 请求中提供 Authorization HTTP 标头。不过，此 POST 不需要任何数据。

响应

如果请求成功，服务器将返回 204 No Content 状态代码。

可选查询参数

清除某个经过身份验证的用户的书架中的所有卷时，您可以使用标准查询参数。

查询参数参考

本部分总结了可用于 Books API 的查询参数。所有参数值都需要经过网址编码。

标准查询参数

系统参数中记录了适用于所有 Books API 操作的查询参数。

特定 API 的查询参数

下表总结了仅适用于 Books API 中特定操作的请求参数。

参数	含义	备注	适用性
`download`	根据下载可用性进行限制。	目前唯一支持的值是 `epub`。可能需要购买才能下载。	执行搜索
`filter`	按卷类型和可用性过滤搜索结果。	支持的过滤条件包括： `filter=partial` - 将结果限制为至少部分文本可预览的音量。 `filter=full` - 将结果限制为所有文字均可见的音量。 `filter=free-ebooks` - 将搜索结果限制为免费的 Google 电子书。 `filter=paid-ebooks` - 将搜索结果限制为包含购买价格的 Google 电子书。 `filter=ebooks` - 将搜索结果限制为 Google 电子书（付费版或免费版）。非电子书的示例包括提供有限试阅且不可销售的发布商内容或杂志。	执行搜索
`langRestrict`	限制返回使用指定语言的标记所返回的卷。	将 `langRestrict` 指定为由两个字母组成的 ISO-639-1 代码（例如“en”或“fr”），将搜索结果限制为特定语言的用户。	执行搜索
`maxResults`	随该请求返回的元素数上限。	对于集合中所有项的任何请求，您都可以通过在请求的参数中指定 `startIndex` 和 `maxResults` 来对结果进行分页。默认：`maxResults=10` 允许的最大值：`maxResults=40.`	执行搜索列出用户书架列出用户书架卷列出我的书架列出我的书架卷
`orderBy`	卷搜索结果的顺序。	默认情况下，搜索请求会返回 `maxResults` 结果，其中 `maxResults` 是分页中使用的参数，按相关性最高的顺序排列。您可以通过将 `orderBy` 参数设置为以下值之一来更改排序： `orderBy=relevance` - 按相关性由高到低的顺序返回搜索结果（默认）。 `orderBy=newest` - 按从最新发布日期到最早的顺序返回搜索结果。	执行搜索
`printType`	仅限图书或杂志。	支持的值包括： `printType=all` - 返回所有卷内容类型（无限制）。这是默认值。 `printType=books` - 仅返回图书。 `printType=magazines` - 仅返回杂志。	执行搜索
`projection`	将返回的卷信息限制为部分字段。	支持的投影包括： `projection=full` - 包括所有卷元数据（默认）。 `projection=lite` - 仅包含卷和访问元数据的主题。	执行搜索检索卷列出用户书架卷列出我的书架卷
`q`	全文查询字符串。	创建查询时，请以 `q=term1+term2_term3` 的形式列出搜索字词，以 &'+' 分隔。（或者，您也可以使用空格将空格分隔开，但与所有查询参数值一样，空格必须经过网址编码。）API 会返回匹配所有搜索字词的所有条目（例如，在字词之间使用 AND）。与 Google 的网页搜索一样，该 API 会搜索完整字词（和具有相同词干的相关字词），而非子字符串。如需搜索完全匹配的词组，请将词组用引号括起来：`q="exact phrase"`。如需排除与给定字词匹配的条目，请使用 `q=-term` 格式。搜索字词不区分大小写。示例：要搜索包含完全匹配词组 `"Elizabeth Bennet"` 和字词 `"Darcy"`，但不包含字词 `"Austen"` 的所有条目，请使用以下查询参数值：`q="Elizabeth+Bennet"+Darcy-Austen` 您可以在搜索字词中指定在特定字段中搜索的特殊（区分大小写）关键字，例如： `intitle`：返回在标题中找到此关键字后面的文本的结果。 `inauthor`：返回在作者中找到此关键字后面的文本的结果。 `inpublisher`：返回在发布商中找到此关键字后面的文字的结果。 `subject`：返回卷后的关键字列表中包含此关键字后面的文本的结果。 `isbn`：返回此关键字后面的文本是 ISBN 编号的结果。 `lccn`：返回此关键字后面的文本为美国国会图书馆控制号的结果。 `oclc`：返回此关键字后面的文字是 Online Computer Library Center 号码的结果。	执行搜索
`startIndex`	结果列表的起始位置。	对于集合中所有项的任何请求，您都可以通过在请求的参数中指定 `startIndex` 和 `maxResults` 来对结果进行分页。第一项的索引为 0。	执行搜索列出用户书架列出用户书架卷列出我的书架列出我的书架卷
`volumeId`	用于标识与请求相关联的卷。	指定要在书架中添加或移除的卷。	将卷添加到我的书架从书架中移除卷

使用 API

目录

简介

为请求授权并识别您的应用

关于授权协议

使用 OAuth 2.0 向请求授权

获取和使用 API 密钥

Google 图书 ID

Google 图书网站上的 ID

设置用户位置

使用卷

执行搜索

请求

响应

可选查询参数

下载格式

过滤

分页

打印类型

Projection

排序

检索特定卷

请求

响应

访问权限信息

可选查询参数

Projection

使用书架

检索用户的公开书架列表

请求

响应

可选查询参数

检索特定的公开书架

请求

响应

可选查询参数

检索公共书架上的卷列表

请求

响应

可选查询参数

分页

使用“我的书库”中的书架

检索我的书架列表

请求

响应

可选查询参数

检索书架上的卷列表

请求

响应

可选查询参数

分页

正在将书架添加到我的书架

请求

响应

可选查询参数

从书架中移除卷

请求

响应

可选查询参数

清除书架中的所有卷

请求

响应

可选查询参数

查询参数参考

标准查询参数

特定 API 的查询参数