借助 Google 图书动态链接功能,您可以创建更加可自定义、可靠的链接,以便从自己的网站指向 Google 图书。例如,您可以利用此工具生成“智能”链接(仅当图书编入我们的索引时才显示),或生成一些链接,向用户指明图书是否可以在 Google 图书上试阅。通过动态链接功能,您还可以在指向 Google 图书的链接中添加缩略图。本文档旨在帮助您快速将此功能添加到您的网站。
注意:此功能以前称为 Book Viewability API。
预览向导是一款基于动态链接构建的工具,可让您更轻松地从网站链接到图书预览,只需复制几行代码即可。本文档适用于希望自定义其图书搜索链接方式的更高级开发者。
目录
观众
动态链接文档适用于要编写链接到 Google 图书中图书的网络应用的程序员。本文档假定您熟悉 HTTP 协议和基本 JavaScript。
图书搜索术语
Google 图书尊重用户当地的版权限制,因此某些图书的试阅或全书浏览功能仅在部分地区提供。可见度划分为以下类:
- 全屏视图
- 整本图书均可查看。这些图书可能属于公共领域。
- 有限预览
- 图书的一部分内容可供查看。此图书受版权保护,Google 图书已获得相应的授权,允许用户访问这些书页。此类图书与“摘录视图”图书的不同之处在于,用户可以查看整页内容。
- 摘要视图和无预览
- 用户只会看到“图书信息”页面。最多只能提供图书中的简短摘录。此图书尚未被扫描,或者受版权保护且 Google 图书尚未获得显示与用户搜索字词相关的多个“片段”的许可。
简介
静态链接文档介绍了一种非常简单的方法,可生成指向 Google 图书上特定图书页面的网址。遗憾的是,有时可能会发生这样的情况:特定图书未编入 Google 图书索引,或特定地理位置的用户无法预览。由于静态链接是“盲目”的,因此它们有时无法产生预期效果。
动态链接提供了一种备选的程序化客户端方法,可让您使用 JavaScript 查询图书的可见度。这样,您就可以加入更加可靠且可预测的图书搜索链接,从而为用户提供更加一致的体验。由于可见度因最终用户所在的位置而异,因此动态链接界面不适用于服务器端或离线查询。
要了解动态链接的功能,请跳至本文末尾的代码示例。
品牌推广指南
呈现动态链接时,您必须遵守 Google Books API 系列规定的品牌推广指南。具体而言,
- 您必须保留指向 Google 图书的出处和链接。
- 链接到 Google 图书上的试阅时,您只能使用已获批准的 Google 预览按钮。
- 所有文本链接、按钮、文档或说明性文字均应符合已获批准的命名惯例。例如,在链接到 Google 图书预览时,不应使用动词“download”(下载)或“read”(阅读),因为只有属于公共领域的作品才能完整下载。
品牌信息示例
![](https://developers-dot-devsite-v2-prod.appspot.com/static/books/images/gbs_preview_button1.gif?authuser=4&hl=zh-cn)
本文档末尾的“示例”部分提供了符合当前品牌推广指南的其他示例。
客户端 API
客户端动态链接的核心是网址格式,开发者可以通过该网址构建网址来请求一本或多本图书的相关信息,并使用 <script>
标记向 Google 图书发送请求。
- 语法示例:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
请求格式
网址格式类似于用于链接到图书的网址语法,但图书 ID 字段可以包含多个用逗号分隔的图书 ID,并且还有其他“jscmd”和“callback”参数。您还可以选择提供其他参数来控制可见度过滤条件。
Dynamic Links 支持多种不同的图书标识方法:ISBN、OCLC 编号和 LCCN 键。该 API 允许最多达到 GET 请求大小上限的批量查询。
- ISBN
&bibkeys=ISBN:0451526538
(API 支持 ISBN 10 和 13。)- OCLC
&bibkeys=OCLC:36792831
- 伦敦证券交易委员会
&bibkeys=LCCN:96072233
JSON 结果格式
此调用的响应将是与所请求图书相关的信息,以一个或多个 JSON 对象的形式返回。JSON 对象使用以下结构:
JsonSearchResult { string bib_key; string info_url; string preview_url; string thumbnail_url; string preview; };
这些字段提供以下信息:
- bib_key
- 用于查询此图书的标识符。
- info_url
- 指向 Google 图书中包含图书信息的页面(即“图书信息”页面)的网址。
- preview_url
- 指向图书预览的网址,用户点击后可以直接转到图书的封面。如果请求只能提供“摘录视图”或“不提供试阅”图书,则系统不会返回试阅网址。
- thumbnail_url
- 指向图书封面缩略图的网址。
- 预览版
- 一个值,用于指示图书的可见状态:
full
(对于全书浏览的图书)、partial
(对于小范围预览图书)或noview
(对于摘录或不提供试阅的图书)。 - 嵌入式
- 如果图书可以使用嵌入式阅读器嵌入到第三方网页中,则此布尔值为
true
。 - jscmd
- 向 Google 图书提出的要求。
- callback
- 我们向其传递返回值的 JavaScript 函数的名称。
- 问:我是否需要 API 密钥或其他权限才能使用动态链接?
- 答:无需 API 密钥或其他授权即可使用动态链接。首先,复制并粘贴我们的一个示例,然后开始修改。
- 问:如果浏览器不支持或停用了 JavaScript,该怎么办?
- 答:如果用户的浏览器未启用 JavaScript,则无法测试 Google 图书中是否有相应图书。对于不支持 JavaScript 的浏览器,我们建议您使用 Google 图书提供的静态链接结构;但请注意,您无法事先得知 Google 图书中是否有您要链接到的图书。
- 问:一次可以搜索多少本图书?
- 答:您可以搜索的图书数量仅受 GET 请求的长度限制。在 Microsoft Internet Explorer 中,网址长度上限(2,083 个字符)会限制 GET 请求的长度。
- 问:Google 图书刚刚返回了一本图书的搜索结果。为什么现在不返回结果?
- 答:由于开发者发出的请求数量经常超出正常范围,因此您可能会不小心提示 Google 图书中提供的安全防范措施。要检查是否发生了这种情况,请查看 API 返回的内容。如果是要求填写人机识别系统的请求,则说明您发出的查询过多。我们建议您登录 Google 图书并重试。
- 问:在隐私保护方面会有哪些变化?
- 答:在回答图书可见度查询时,Google 会收到不含个人身份信息的服务器日志数据。我们十分重视用户隐私,并会按照我们的隐私权政策来处理这些数据。如果您向用户提供的服务包含图书可见度,则可能需要告知用户您的服务还会通过动态链接向 Google 提交查询。
- 图书页的“预览”按钮
如果您打算使用动态链接向您网站上的各个图书页添加“预览”按钮,可以参考下面这个示例。此实现使用对 Google 图书的同步调用。 - 课程阅读清单
此示例显示了学术课程的典型图书清单。我们使用单个同步调用来链接到 Google 图书上的图书页面、添加封面/封底图片以及指明试阅服务提供情况。 - 备选图书列表
与上一个示例类似,此示例使用异步 API 回调添加了指向图书搜索的链接。 - 交互式 AJAX
您可能有兴趣在高度互动的 AJAX 应用中使用动态链接。此示例展示了如何在不刷新页面的情况下发出多个不同的调用。
该响应是一个 JSON 对象,包含两个字段:“books”(包含图书对象映射的值)和“options”(包含为该请求启用的选项列表)。如果未指定选项,响应中可以省略“options”字段。例如:
Request: https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo Response: ProcessGBSBookInfo({ "0596000278":{ "bib_key":"0596000278", "info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI", "preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI", "thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg", "preview":"partial" }, "ISBN0765304368":{ "bib_key":"ISBN0765304368", "info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI", "preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI", "thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg", "preview":"full" }, "0439554934":{ "bib_key":"0439554934", "info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI", "preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI", "thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM", "preview":"noview"} });
然后,开发者可以根据从 GBS 服务器检索到的 JSON 结果,更改网页的内容和外观。目前,GBS 未提供用于修改 DOM 的库。
参数和其他字段
同步与异步模式
异步模式
在异步模式下,开发者将 <script>
代码置于文档的 <head>
中,并使用呈现网页所需的所有标识符构建网址。数据是通过变量的 调用接收的。这样图书的信息就可供文档的其余部分使用,而且用户还可以通过 HTML 和 JavaScript 立即访问这些信息。
同步模式
在同步模式下,开发者会使用 HTML <body>
中间的网址;系统会使用 JavaScript 回调来处理响应。
常见问题解答
代码示例
本部分提供的示例说明了使用动态链接的不同方法。您可以点击任意示例,查看其实际效果。如需查看底层代码,请在您的浏览器中“查看源代码”。