Dynamic Links
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
有了「Google 圖書動態連結」功能，您就能在個人網站上建立更多可自訂且可靠的 Google 圖書連結。舉例來說，您可以透過這項工具產生「智慧型」連結，只有在書籍加入索引時才會顯示，或是顯示連結，方便使用者瞭解書籍是否可在 Google 圖書上預覽。Dynamic Links 功能也可讓您在自己的 Google 圖書連結中加入縮圖圖片。本文件旨在協助你快速為網站新增這項功能，
注意：這項功能先前稱為 Book Viewability API。
預覽精靈是建構於 Dynamic Links 的工具，可讓您輕鬆複製幾行程式碼，從網站連結至書籍預覽畫面。本文件是針對想要自訂與「Google 圖書搜尋」之連結方式的進階開發人員所設計。
目錄
- 觀眾
- 書籍搜尋字詞
- 說明
- 品牌宣傳指南
- 用戶端 API
- 要求網址格式
- JSON 結果格式
- 同步和非同步模式
- 常見問題
- 程式碼範例
觀眾
動態連結說明文件的適用對象，是想撰寫連結至 Google 圖書書籍的網頁應用程式的程式設計師。本說明文件假設您已熟悉 HTTP 通訊協定和基本 JavaScript。
圖書搜尋字詞
Google 圖書尊重使用者的當地版權限制，因此部分地區可能無法提供試閱或試閱的書籍。可視度分成下列類別：
- 完整檢視畫面
- 整本書開放閱讀。這些書籍可能屬於公版資源。
- 限定試用
- 書籍中有部分內容可供閱讀。這本書受著作權保護，Google 圖書已取得授權，方便使用者瀏覽這些網頁。這些書籍與「摘錄」不同 - 使用者可能會閱讀整個書頁。
- 摘錄檢視且無預覽
- 使用者只會看到「關於本書」頁面，大部分書籍內容只有簡短摘錄內容。這本書尚未掃描或受版權保護，因此 Google 圖書尚未取得權限，無法公開與使用者搜尋字詞相關的幾項「摘要」。
簡介
靜態連結說明文件提供了非常簡單的方式，讓您瞭解如何為 Google 圖書中的特定書籍頁面產生網址。不過有時候，如果某本書沒有納入 Google 圖書索引，或是特定地理位置的使用者無法預覽特定書籍，就可能發生這種情況。由於 Static 連結是「盲人」，因此有時可能會無法達到預期的效果。
Dynamic Links 提供另一種程式輔助用戶端方法，可透過 JavaScript 查詢書籍的可視度。如此一來，您就可以在「圖書搜尋」中加入更可靠且可預測的連結，為使用者打造更一致的使用體驗。由於可視度會因使用者的所在位置而異，因此動態連結介面不適用於伺服器端或離線查詢。
如要瞭解 Dynamic Links 的功能，請跳至本文件結尾處的程式碼範例。
品牌宣傳規範
顯示 Dynamic Links 時，您必須遵守 Google 圖書 API 系列適用的品牌宣傳指南。特別是
- 您必須持續註明出處和 Google 圖書的連結。
- 只有在連結至 Google 圖書的試閱項目時，才能使用核准的 Google 預覽按鈕。
- 所有文字連結、按鈕、說明文件或說明文字都應遵守經核准的命名慣例。舉例來說，由於只有公版著作項目可供下載，因此我不應在連結至 Google 圖書試閱內容時使用「下載」或「閱讀」等動詞。
品牌宣傳範例
《Freakonomics: An Rogue Economists Discovery the Hidden Side of 應有盡有》
作者：Steven Levitt 和 Stephen Dubner
本文件結尾的範例部分提供了符合現行品牌宣傳指南的其他範例。
用戶端 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 物件使用下列結構：
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。
回應為 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 以進行這項作業的程式庫。
參數和其他欄位
- jscmd
- 傳送給 Google 圖書的要求。
- 回呼
- 我們傳遞傳回對象的 JavaScript 函式名稱。
同步與非同步模式
非同步模式
在非同步模式中，開發人員會將 <script> 標記放在文件的 <head> 中，以轉譯網頁所需的所有 ID 建立網址。系統會透過變數中的呼叫接收資料，文件資訊會提供給文件的其餘部分，並可立即在 HTML 和 JavaScript 中存取。
同步模式
在同步模式中，開發人員會使用 HTML <body> 中間的網址，而回應將透過 JavaScript 回呼進行處理。
常見問題
- 問：我是否需要 API 金鑰或其他權限，才能使用動態連結？
- 答：使用動態連結時不需要 API 金鑰或其他授權。首先，請複製及貼上其中一個範例，然後開始規劃。
- 問：如果瀏覽器不支援或停用 JavaScript，該怎麼辦？
- 答：當使用者的瀏覽器未啟用 JavaScript，您無法測試 Google 圖書是否有書籍。建議在沒有 JavaScript 的瀏覽器上使用 Google 圖書的靜態連結結構。不過請注意，您無法事先得知 Google 圖書是否有您要連結的書籍。
- 問：一次可以搜尋幾本書籍？
- 答：您可以搜尋的書籍數量只會受限於 GET 要求的長度。Microsoft Internet Explorer 中的網址長度上限 (2,083 個字元) 會限制 GET 要求的長度。
- 問：Google 圖書剛剛傳回書籍的搜尋結果，為什麼現在沒有傳回結果？
- 答：由於開發人員經常發出數量不尋常的要求，您也許不小心對 Google 圖書採取的安全防護措施。如要確認是否有這個情況，請查看 API 傳回的內容。如果系統要求填寫人機驗證 (Captcha)，這代表您的查詢數量過多。建議您登入 Google 圖書，然後再試一次。
- 問：會如何保護隱私權？
- 答：回應有關書籍可視度的查詢時，Google 會收到非個人識別資訊的伺服器記錄資料。我們十分重視使用者隱私，並會依據《隱私權政策》所述的方式處理這類資料。如果您為使用者提供的服務包含書籍可視度，建議您讓使用者瞭解，您的服務也會透過動態連結向 Google 提交查詢。
程式碼範例
本節提供範例，說明 Dynamic Links 的各種使用方法。點選任一範例即可觀看實際運作情形。如要查看基礎程式碼，請在瀏覽器中「檢視原始碼」。
- 書籍頁面的預覽按鈕
如果您想使用 Dynamic Links 在網站的個別書籍頁面中加入「預覽」按鈕，請參考這個範例。這項實作程序會使用同步呼叫對 Google 圖書進行處理。
- 課程閱讀清單
這個範例顯示學術課程的一般書籍清單。我們會透過單一同步呼叫連結至 Google 圖書上的書籍頁面、新增封面圖片，以及指出是否開放試閱。
- 替代書籍清單
與上一個範例類似，這個範例會使用非同步 API 回呼，新增圖書搜尋的連結。
- 互動式 AJAX
您可以考慮在高度互動的 Vertex 應用程式中使用 Dynamic Links。本例說明如何在不重新整理頁面的情況下，發出多次不同的呼叫。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2024-06-28 (世界標準時間)。
[null,null,["上次更新時間：2024-06-28 (世界標準時間)。"],[[["\u003cp\u003eGoogle Books Dynamic Links offer customizable and reliable links to Google Books, enhancing user experience by displaying links based on book availability and preview options.\u003c/p\u003e\n"],["\u003cp\u003eDynamic Links utilize a client-side JavaScript API allowing developers to verify book viewability and retrieve information like thumbnail URLs and preview states before rendering links.\u003c/p\u003e\n"],["\u003cp\u003eWhen integrating Dynamic Links, developers must adhere to Google Books branding guidelines, including proper attribution, approved button usage, and consistent naming conventions.\u003c/p\u003e\n"],["\u003cp\u003eThe API supports batched queries using various book identifiers (ISBN, OCLC, LCCN) and returns results in JSON format containing details like preview URLs, thumbnail URLs, and viewability status.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers have access to a Preview Wizard tool for simplified integration and code generation, along with detailed documentation and code samples for advanced customization.\u003c/p\u003e\n"]]],[],null,["# Dynamic Links\n\nThe Google Books Dynamic Links feature allows you to create more customizable, reliable links to Google Books from your site. For example, this tool lets you generate \"smart\" links that appear only when a book is in our index, or display links that indicate to your users whether a book can be previewed on Google Books. The Dynamic Links feature also lets you include a thumbnail image in your link to Google Books. This document is intended to let you quickly add this functionality to your site.\n\n*Note: This feature was formerly known as the the Book Viewability API.*\n\nThe [Preview Wizard](/books/docs/preview-wizard) is a tool built atop Dynamic Links that makes it even easier to link to book previews from site by just copying a few lines of code. This document is intended for more advanced developers looking to customize how they link to Book Search.\n\nContents\n--------\n\n1. [Audience](#audience)\n2. [Book Search terminology](#terminology)\n3. [Introduction](#introduction)\n4. [Branding guidelines](#style-guide)\n5. [The Client-side API](#clientSide)\n6.\n 1. [Request URL format](#requestFormat)\n 2. [JSON results format](#JSONformat)\n7. [Synchronous and asynchronous modes](#syncAsync)\n8. [Frequently asked questions](#faq)\n9. [Code samples](#htmlEx)\n\nAudience\n--------\n\nThe dynamic links documentation is intended for programmers who want to write web applications that link to books within Google Books. This documentation assumes that you are familiar with the HTTP protocol and basic JavaScript.\n\nBook Search terminology\n-----------------------\n\nGoogle Books respects the user's local copyright restrictions, and as a result, previews or full views of some books are not available in all locations. Viewability is clustered into the following classes:\n\nFull View\n: The entire book is viewable. These books may be in the public domain.\n\nLimited Preview\n: A portion of the book is viewable. This book is under copyright and Google Books has received permission to make these pages accessible to users. These books differ from Snippet View books in that users may view entire pages.\n\nSnippet View and No Preview\n: Users see only an \"About the book\" page. At most, only short excerpts from the book are available. This book has either not been scanned, or is under copyright and Google Books has not received permission to expose more than a few \"snippets\" related to a user's search term.\n\nIntroduction\n------------\n\nThe [Static Links](/books/docs/static-links) documentation describes a very simple way of generating URLs to a particular book's page on Google Books. Unfortunately, it is sometimes the case that a particular book is not in the Google Books index, or that a preview is not available to a user in a particular geographic location. Because Static Links are \"blind,\" they sometimes fail to have the intended effect.\n\nDynamic Links provides an alternative, programmatic client-side method for querying the viewability of a book using JavaScript. This allows you to include more reliable and predictable links to Book Search, leading to a more consistent experience for your users. Because viewability varies according to the end user's location, the dynamic link interface is not designed for server-side or offline queries.\n\nTo get a sense of what Dynamic Links can do, skip to the [code samples](#htmlEx) at the end of this document.\n\nBranding guidelines\n-------------------\n\nWhen rendering Dynamic Links, you must abide by the [branding guidelines](/books/branding) that govern the Google Books API Family. In particular,\n\n- You must maintain attribution and links to Google Books.\n- You must use only the approved [Google Preview button](/books/branding#previewbutton) when linking to previews on Google Books.\n- Any text links, buttons, documentation, or descriptive text should abide by the approved [naming conventions](/books/branding#naming). For example, you should not use the verbs \"download\" or \"read\" when linking to Google Books previews, as only public domain works can be downloaded in their entirety.\n\n\u003cbr /\u003e\n\n### Example branding\n\n**Freakonomics: An Rogue Economist Explores the Hidden Side of Everything** \nBy Steven Levitt and Stephen Dubner\n\n[](https://books.google.com/books?id=LkQPOSXMUscC&printsec=frontcover) \n\n\nThe [samples section](#htmlEx) at the end of this document provides additional examples that are compliant with the current branding guidelines.\n\nClient-side API\n---------------\n\nAt the core of the client-side dynamic link is a URL format that allows developers to construct URLs requesting information on one or more books and send the requests to Google Books using the `\u003c``script\u003e` tag.\n\nSyntax Example:\n: ` \u003c``script src=\"https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback\"\u003e\u003c``/script\u003e`\n\n### Request format\n\nThe format of the URL is similar to the URL syntax [used to link to books](https://books.google.com/support/bin/answer.py?answer=80658), but the book ID field may contain multiple comma separated book IDs and there are additional 'jscmd' and 'callback' parameters. Optionally, additional arguments can be present to control the viewability filters.\n\nDynamic Links supports several different methods for identifying books: ISBNs, OCLC numbers, and LCCN keys. The API allows batched queries of up to the size of the max size of a GET request.\n\nISBN\n: `&bibkeys=ISBN:0451526538` (The API supports both ISBN 10 and 13.)\n\nOCLC\n: `&bibkeys=OCLC:36792831`\n\nLCCN\n: `&bibkeys=LCCN:96072233`\n:\n\n\u003cbr /\u003e\n\n### JSON results format\n\nThe response from this call will be information about the requested books returned as one or more JSON objects. The JSON objects use the following structure: \n\n```\nJsonSearchResult {\n string bib_key;\n string info_url;\n string preview_url;\n string thumbnail_url;\n string preview;\n};\n```\n\nThese fields provide the following information:\n\nbib_key\n: The identifier used to query this book.\n\ninfo_url\n: A URL to a page within Google Books with information on the book (the about this book page).\n\npreview_url\n: A URL to the preview of the book, which takes the user directly to the cover of the book. If only Snippet View or No Preview books available for a request, no preview URL will be returned.\n\nthumbnail_url\n: A URL to a thumbnail of the cover of the book.\n\npreview\n: A value indicating the [viewability state](#terminology) of the book: `full` (for Full View books), `partial` (for Limited Preview books), or `noview` (for Snippet or No Preview books).\n\nembeddable\n: This boolean is `true` if the book can be embedded onto third party pages using the Book Search [embedded viewer](/books/docs/viewer/developers_guide)."]]
