此页面由 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 大于 1,000。书架 ID 对于给定用户而言是唯一的，即两个用户可以拥有同一个 ID 并引用不同书架的书架。您可以使用 API 通过发出返回“书架”资源的请求来获取书架 ID；您可以在其 id 字段中找到书架 ID。
用户 ID - 分配给每位用户的唯一数值。这些值不一定与其他 Google 服务中使用的 ID 值相同。目前，检索用户 ID 的唯一方法是从使用经过身份验证的请求检索的书架资源中的 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 图书尊重与最终用户所在位置相关的版权、合同和其他法律限制。因此，某些用户可能无法从某些国家/地区访问图书内容。例如，某些图书只能在美国“可试阅”；对于其他国家/地区的用户，我们会省略此类试阅链接。因此，API 结果取决于您的服务器或客户端应用的 IP 地址。

使用卷

执行搜索

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

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

此请求有一个必需参数：

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

请求

以下示例搜索的是丹尼尔·凯斯的“给阿尔杰农的花”：

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

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

响应

如果请求成功，服务器将返回 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 状态代码和请求的卷资源：

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

由于用户无需经过身份验证即可检索有关公开书架的信息，因此您无需通过 GET 请求提供 Authorization HTTP 标头。

响应

如果请求成功，服务器将返回 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 和 shelf 路径参数替换为用于指定您要检索的用户和书架的 ID。如需了解详情，请参阅 Google 图书 ID 部分。

请求

示例如下：

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

由于用户无需经过身份验证即可检索有关公开书架的信息，因此您无需通过 GET 请求提供 Authorization HTTP 标头。

响应

如果请求成功，服务器将返回 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 和 shelf 路径参数替换为用于指定您要检索的用户和书架的 ID。如需了解详情，请参阅 Google 图书 ID 部分。

由于用户无需经过身份验证即可检索有关公开书架的信息，因此您无需通过 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，允许的最大值为 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 */

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

响应

如果请求成功，服务器将返回 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"
  }
 ]
}

可选查询参数

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

检索书架中的卷列表

您可以向经过身份验证的用户的书架上按以下格式发送 HTTP GET 请求，以检索这些卷的列表：

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

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

请求

示例如下：

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

注意：用户必须通过身份验证才能检索“My Library”卷列表。因此，您必须在 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

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

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

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

请求

以下示例展示了如何将“Flowers for Algernon”添加到“Favorites”书架：

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 状态代码。

可选查询参数

在向已通过身份验证的用户的任一书架添加卷时，您可以使用标准查询参数。

从我的书架中删除某卷

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

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

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

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

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

请求

以下示例展示了如何从“Favorites”书架中移除“Flowers for Algernon”：

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

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

请求

以下是清除“Favorites”书架的示例：

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 专属查询参数