借助 Google 图书动态链接功能,您可以从自己的网站创建更多可自定义、更可靠的 Google 图书链接。例如,借助此工具,您可以生成“智能”链接(仅当图书编入索引时才会显示),或者显示链接,以表明用户能否在 Google 图书上试阅图书。借助动态链接功能,您还可以在指向 Google 图书的链接中添加缩略图。本文档旨在帮助您快速将此功能添加到您的网站。
注意:此功能以前称为 Book Viewability API。
预览向导是基于动态链接构建的工具,只需复制几行代码,即可更轻松地从网站链接到图书预览。本文档适用于希望自定义如何链接到图书搜索的更高级开发者。
目录
观众
Dynamic Links 文档适用于想要编写链接到 Google 图书中的图书的 Web 应用的程序员。本文档假定您熟悉 HTTP 协议和基本 JavaScript。
图书搜索术语
Google 图书尊重用户当地的版权限制,因此,有些图书只能在部分国家/地区试阅或试阅。可见度被划分为以下类:
- 全屏视图
- 整本图书可供查看。这些图书可能属于公共领域。
- 有限预览
- 图书有部分内容可供阅读。此图书受版权保护,Google 图书已获得相关权限,允许用户访问这些书页。这些图书与“摘录视图”图书不同,用户可能会查看整页内容。
- 摘要视图和无预览
- 用户只能看到“图书信息”页面。该图书最多只能提供简短的摘录。我们未扫描此图书,或者此图书受版权保护,Google 图书尚未获得显示与用户搜索字词相关的多个“摘要”的权限。
简介
静态链接文档介绍了一种非常简单的方法,可生成指向 Google 图书上特定图书页面的网址。遗憾的是,有时某些图书不在 Google 图书索引中,或者特定地理位置的用户无法进行试阅。由于静态链接是“盲化”的,因此它们有时无法达到预期的效果。
Dynamic Links 提供了另一种程序化客户端方法,用于使用 JavaScript 查询图书的可见度。这样,您便可以在图书搜索中添加更可靠且可预测的链接,从而为用户提供更加一致的体验。由于可见度会因最终用户的位置而有所不同,因此动态链接界面不适用于服务器端查询或离线查询。
要了解动态链接的功能,请跳至本文档末尾的代码示例。
品牌推广指南
呈现动态链接时,您必须遵守管理 Google Books API 系列的品牌推广指南。具体来说,
- 您必须保留出处和指向 Google 图书的链接。
- 链接到 Google 图书上的试阅时,您只能使用已获批准的 Google 预览按钮。
- 所有文字链接、按钮、文档或说明性文字均应符合已获批准的命名惯例。例如,在链接到 Google 图书试阅内容时,请勿使用动词“下载”或“阅读”,因为您只能下载公共领域的作品。
品牌塑造示例
本文档末尾的示例部分提供了另外一些符合当前品牌塑造准则的示例。
客户端 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
- LCCN
&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 图书中一个图书页面(包含该图书的相关信息)的网址。
- 预览网址
- 指向图书试阅内容的网址,可将用户直接转到图书封面。如果请求只能显示摘要视图或没有预览图书,则不会返回预览网址。
- 缩略图网址
- 指向图书封面缩略图的网址。
- 预览版
- 该值表示图书的可浏览状态:
full
(针对全书浏览的图书)、partial
(针对有限试阅图书)或noview
(针对摘录或不提供试阅图书)。 - 可嵌入
- 如果图书支持通过图书搜索嵌入式查看器嵌入第三方网页,该布尔值为
true
。 - jscmd
- 向 Google 图书提出的请求。
- callback
- 我们传递返回所针对的 JavaScript 函数的名称。
- 问:我是否需要 API 密钥或其他权限才能使用动态链接?
- 答:使用动态链接不需要 API 密钥或其他授权。要开始使用,只需复制并粘贴我们的一个示例,然后开始修改即可。
- 问:对于不支持 JavaScript 或已停用 JavaScript 的浏览器,该怎么办?
- 答:如果用户浏览器没有启用 JavaScript,则无法测试 Google 图书是否有图书。对于没有 JavaScript 的浏览器,我们建议您使用 Google 图书的静态链接结构。不过请注意,您不能提前知道 Google 图书中是否包含您要链接到的图书。
- 问:我可以一次搜索多少本图书?
- 答:您可以搜索的图书数量只受 GET 请求的长度限制。在 Microsoft Internet Explorer 中,最大网址长度(2083 个字符)限制了 GET 请求的长度。
- 问:Google 图书刚刚返回一本图书的搜索结果。为什么它现在没有返回结果?
- 答:由于开发者通常会发出非常数量的请求,您可能会无意中提示 Google 图书的安全预防措施。如需检查是否发生了这种情况,请查看该 API 返回的内容。如果请求填写验证码,则说明您发出的查询过多。我们建议您登录 Google 图书,然后重试。
- 问:隐私保护如何?
- 答:在回答针对图书可见度的查询时,Google 会收到非个人身份信息的服务器日志数据。我们非常重视用户隐私,并会按照隐私权政策中所述处理此类数据。如果您要为用户提供包含图书可见度的服务,则可能要告知用户您的服务也通过动态链接向 Google 提交查询。
响应是一个包含两个字段的 JSON 对象,“books”包含图书对象的映射值,并且“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 回调进行处理。
常见问题解答
代码示例
本部分提供的示例说明了动态链接的不同使用方式。点击任一示例即可查看实际效果。如需查看底层代码,请在浏览器中“查看源代码”。