Google 圖書動態連結功能可讓您為網站建立更多可自訂又可靠的 Google 圖書連結。舉例來說,你可以利用這項工具產生「智慧型」連結,只有在書籍已編入索引時才會顯示連結,或是顯示可向使用者顯示書籍是否提供試閱的 Google 圖書連結。你也可以透過動態連結功能在 Google 圖書連結中加入縮圖圖片。這份文件可讓你快速為網站新增這項功能。
注意:這項功能先前稱為 Book 可視度 API。
預覽精靈是一項以 Dynamic Links 為基礎的工具,只要複製幾行程式碼就能更輕鬆地連結至網站上的書籍預覽。本文件的適用對象為想自訂連結「圖書搜尋」方式的進階開發人員。
目錄
觀眾
動態連結說明文件適用於想編寫網頁應用程式,以連結到 Google 圖書中的書籍程式。這份說明文件假設您熟悉 HTTP 通訊協定和基本 JavaScript。
書籍搜尋術語
Google 圖書尊重使用者當地的版權限制,因此並非所有書籍皆提供試閱或完整試閱功能。可視度將分為以下類別:
- 完整檢視畫面
- 整本書可供查看。這些書籍可能屬於公共領域資源。
- 限定試用
- 部分書籍開放閱讀。這本書受版權保護,Google 圖書已取得授權,允許使用者存取這些網頁。這些書籍不同於摘錄檢視書籍,使用者可能會看到整頁內容。
- 摘錄檢視和無預覽
- 使用者只會看到「關於本書」頁面。最多可以顯示書籍的短摘錄摘錄。這本書未經掃描或受到版權保護,且 Google 圖書並未取得授權,因此無法公開與使用者搜尋字詞相關的數個「摘要」。
簡介
靜態連結說明文件可協助您輕鬆產生 Google 圖書特定書籍頁面的網址。不過,有時書籍有時會顯示在 Google 圖書索引中,或者使用者無法對特定地理位置的使用者提供試閱。由於「靜態連結」是「視障」,因此有時會無法正常運作。
Dynamic Links 提供替代的程式輔助用戶端方法,可使用 JavaScript 查詢書籍的可視度。如此可讓您加入「書籍搜尋」的更可靠、可預測的連結,讓使用者享有一致的體驗。由於動態可視度會因使用者的位置而異,因此動態連結介面並非專為伺服器端或離線查詢所設計。
如要瞭解 Dynamic Links 的用途,請跳到本文結尾的程式碼範例。
品牌宣傳規範
顯示 Dynamic Links 時,您必須遵守 Google 圖書 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' 和 ##9;callback' 參數。或者,您也可以指定其他引數,以控制可視度篩選器。
Dynamic Links 支援幾種辨識書籍的方法,包括 ISBN、OCLC 編號和 LCCN 金鑰。這個 API 可讓您批次查詢最多 GET 要求的大小上限。
- ISBN
&bibkeys=ISBN:0451526538
(API 支援 ISBN 10 和 13)。- 離線轉換追蹤
&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; };
這些欄位提供下列資訊:
- bi__key
- 用來查詢這本書的 ID。
- info_url
- Google 圖書中的頁面網址,內含書籍相關資訊 (關於「關於書籍」頁面)。
- Preview_url
- 書籍試閱的網址,會直接將使用者導向書籍封面。如果某項要求只有「摘要檢視」或「無試閱」書籍,則不會傳回預覽網址。
- thumbnail_url
- 書籍封面的縮圖網址。
- 預先發布版
- 表示書籍可視狀態的值:
full
(適用於全檢視書籍)、partial
(適用於部分試閱書籍) 或noview
(適用於摘錄書籍或不提供試閱書籍)。 - 可嵌入
- 如果書籍可以使用「書籍搜尋」的「嵌入式檢視器」嵌入第三方網頁,這個布林值會是
true
。 - jscmd
- 傳送至 Google 圖書的要求
- 回呼
- 我們要傳回傳回的 JavaScript 函式名稱。
- 問:我需要 API 金鑰或其他權限,才能使用動態連結嗎?
- 答:不需要動態 API 金鑰或其他授權,即可使用動態連結。開始前,請直接複製其中一個範例,然後開始調整。
- 問:瀏覽器不支援 JavaScript 或是已停用 JavaScript 嗎?
- 答:如果使用者的瀏覽器未啟用 JavaScript,就無法測試 Google 圖書是否有書籍。我們建議使用不含 Google JavaScript 的瀏覽器的 Google 圖書靜態連結結構,但請注意,你無法事先得知 Google 圖書含有你要連結的書籍。
- 問:我一次可以搜尋幾本書籍?
- 答:你可以搜尋的書籍數量,受限於 GET 要求的長度。在 Microsoft Internet Explorer 中,最大網址長度上限 (2,083 個字元) 會限制 GET 要求的長度。
- 問:Google 圖書很快就傳回書籍的搜尋結果。為什麼現在不傳回結果?
- 答:由於開發人員經常會發布一般要求,因此你可能會在意料中附上 Google 圖書的安全預防措施。如要確認系統是否發生這種情況,請查看 API 傳回的指令。如果這是填寫人機驗證 (Captcha) 的要求,您已發出過多查詢。建議你登入 Google 圖書,然後再試一次。
- 問:在隱私權方面呢?
- 答:Google 會在回答書籍可視度的查詢時,收到非個人識別資訊的伺服器記錄資料。我們十分重視使用者的隱私權,並根據《隱私權政策》所述的方式處理這類資料。如果您為使用者提供的服務包含書籍可視度,建議您告知使用者,您的服務也會透過動態連結向 Google 提交查詢。
回應是 JSON 物件,其中含有「books」(圖) 欄位和「books」(對應) 物件的值,以及「 options」選項,包含針對該要求啟用的選項清單。如果未指定任何選項,回應中可能會省略「option」選項。例如:
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 的不同方式。只要點選任一範例,即可查看實際使用狀況。若要查看基礎程式碼,請從瀏覽器「檢視原始碼」。