有了「Google 圖書動態連結」功能,您就能在個人網站上建立更多可自訂且可靠的 Google 圖書連結。舉例來說,您可以透過這項工具產生「智慧型」連結,只有在書籍加入索引時才會顯示,或是顯示連結,方便使用者瞭解書籍是否可在 Google 圖書上預覽。Dynamic Links 功能也可讓您在自己的 Google 圖書連結中加入縮圖圖片。本文件旨在協助你快速為網站新增這項功能,
注意:這項功能先前稱為 Book Viewability API。
預覽精靈是建構於 Dynamic Links 的工具,可讓您輕鬆複製幾行程式碼,從網站連結至書籍預覽畫面。本文件是針對想要自訂與「Google 圖書搜尋」之連結方式的進階開發人員所設計。
目錄
觀眾
動態連結說明文件的適用對象,是想撰寫連結至 Google 圖書書籍的網頁應用程式的程式設計師。本說明文件假設您已熟悉 HTTP 通訊協定和基本 JavaScript。
圖書搜尋字詞
Google 圖書尊重使用者的當地版權限制,因此部分地區可能無法提供試閱或試閱的書籍。可視度分成下列類別:
- 完整檢視畫面
- 整本書開放閱讀。這些書籍可能屬於公版資源。
- 限定試用
- 書籍中有部分內容可供閱讀。這本書受著作權保護,Google 圖書已取得授權,方便使用者瀏覽這些網頁。這些書籍與「摘錄」不同 - 使用者可能會閱讀整個書頁。
- 摘錄檢視且無預覽
- 使用者只會看到「關於本書」頁面,大部分書籍內容只有簡短摘錄內容。這本書尚未掃描或受版權保護,因此 Google 圖書尚未取得權限,無法公開與使用者搜尋字詞相關的幾項「摘要」。
簡介
靜態連結說明文件提供了非常簡單的方式,讓您瞭解如何為 Google 圖書中的特定書籍頁面產生網址。不過有時候,如果某本書沒有納入 Google 圖書索引,或是特定地理位置的使用者無法預覽特定書籍,就可能發生這種情況。由於 Static 連結是「盲人」,因此有時可能會無法達到預期的效果。
Dynamic Links 提供另一種程式輔助用戶端方法,可透過 JavaScript 查詢書籍的可視度。如此一來,您就可以在「圖書搜尋」中加入更可靠且可預測的連結,為使用者打造更一致的使用體驗。由於可視度會因使用者的所在位置而異,因此動態連結介面不適用於伺服器端或離線查詢。
如要瞭解 Dynamic Links 的功能,請跳至本文件結尾處的程式碼範例。
品牌宣傳規範
顯示 Dynamic Links 時,您必須遵守 Google 圖書 API 系列適用的品牌宣傳指南。特別是
- 您必須持續註明出處和 Google 圖書的連結。
- 只有在連結至 Google 圖書的試閱項目時,才能使用核准的 Google 預覽按鈕。
- 所有文字連結、按鈕、說明文件或說明文字都應遵守經核准的命名慣例。舉例來說,由於只有公版著作項目可供下載,因此我不應在連結至 Google 圖書試閱內容時使用「下載」或「閱讀」等動詞。
品牌宣傳範例
![](https://developers.google.cn/static/books/images/gbs_preview_button1.gif?authuser=8&hl=zh-tw)
本文件結尾的範例部分提供了符合現行品牌宣傳指南的其他範例。
用戶端 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
- 用於查詢這本書的 ID。
- info_url
- 指向 Google 圖書中書籍資訊 (關於此書頁面) 的網頁網址。
- preview_url
- 書籍預覽網址,可將使用者帶往書籍封面。如果要求只提供「摘錄檢視」或「沒有預覽書籍」,系統就不會傳回預覽網址。
- thumbnail_url
- 書籍封面縮圖的網址。
- 預先發布版
- 這個值表示書籍的可視度狀態:
full
(適用於完整試閱書籍)、partial
(適用於限定預覽書籍) 或noview
(適用於摘要書籍或不提供試閱書籍)。 - 可嵌入
- 如果書籍可以使用圖書搜尋內嵌檢視器嵌入第三方頁面,則此佈林值為
true
。 - jscmd
- 傳送給 Google 圖書的要求。
- 回呼
- 我們傳遞傳回對象的 JavaScript 函式名稱。
- 問:我是否需要 API 金鑰或其他權限,才能使用動態連結?
- 答:使用動態連結時不需要 API 金鑰或其他授權。首先,請複製及貼上其中一個範例,然後開始規劃。
- 問:如果瀏覽器不支援或停用 JavaScript,該怎麼辦?
- 答:當使用者的瀏覽器未啟用 JavaScript,您無法測試 Google 圖書是否有書籍。建議在沒有 JavaScript 的瀏覽器上使用 Google 圖書的靜態連結結構。不過請注意,您無法事先得知 Google 圖書是否有您要連結的書籍。
- 問:一次可以搜尋幾本書籍?
- 答:您可以搜尋的書籍數量只會受限於 GET 要求的長度。Microsoft Internet Explorer 中的網址長度上限 (2,083 個字元) 會限制 GET 要求的長度。
- 問:Google 圖書剛剛傳回書籍的搜尋結果,為什麼現在沒有傳回結果?
- 答:由於開發人員經常發出數量不尋常的要求,您也許不小心對 Google 圖書採取的安全防護措施。如要確認是否有這個情況,請查看 API 傳回的內容。如果系統要求填寫人機驗證 (Captcha),這代表您的查詢數量過多。建議您登入 Google 圖書,然後再試一次。
- 問:會如何保護隱私權?
- 答:回應有關書籍可視度的查詢時,Google 會收到非個人識別資訊的伺服器記錄資料。我們十分重視使用者隱私,並會依據《隱私權政策》所述的方式處理這類資料。如果您為使用者提供的服務包含書籍可視度,建議您讓使用者瞭解,您的服務也會透過動態連結向 Google 提交查詢。
回應為 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>
中,以轉譯網頁所需的所有 ID 建立網址。系統會透過變數中的呼叫接收資料,文件資訊會提供給文件的其餘部分,並可立即在 HTML 和 JavaScript 中存取。
同步模式
在同步模式中,開發人員會使用 HTML <body>
中間的網址,而回應將透過 JavaScript 回呼進行處理。
常見問題
程式碼範例
本節提供範例,說明 Dynamic Links 的各種使用方法。點選任一範例即可觀看實際運作情形。如要查看基礎程式碼,請在瀏覽器中「檢視原始碼」。