Dynamic Links
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
Google ブックスの Dynamic Links 機能を使用すると、パートナー様のサイトから Google ブックスへの、カスタマイズ性と信頼性に優れたリンクを作成できます。たとえば、書籍が Google のインデックスに登録された場合のみ表示される「スマート」リンクを生成したり、Google ブックスで書籍をプレビューできるかどうかをユーザーに示すリンクを表示したりできます。Dynamic Links では、Google ブックスへのリンクにサムネイル画像を含めることもできます。このドキュメントでは、この機能をサイトに簡単に追加する方法について説明します。
注: この機能は、以前は Book Viewability API と呼ばれていました。
プレビュー ウィザードは Dynamic Links 上に構築されたツールです。数行のコードをコピーするだけで、サイトから簡単に書籍のプレビューをリンクすることができます。このドキュメントは、ブック検索へのリンク設定をカスタマイズすることを検討している上級開発者を対象としています。
目次
- 対象者
- ブック検索の用語
- はじめに
- ブランドの取り扱いガイドライン
- クライアントサイド API
- リクエスト URL の形式
- JSON の結果の形式
- 同期モードと非同期モード
- よくある質問
- コードサンプル
視聴者
ダイナミック リンクに関するドキュメントは、Google ブックス内の書籍にリンクするウェブ アプリケーションを作成するプログラマーを対象としています。このドキュメントは、HTTP プロトコルと基本的な JavaScript に精通していることを前提としています。
ブック検索の用語
Google ブックスでは、ユーザーの地域における著作権の制限を尊重しているため、地域によっては一部の書籍のプレビューや全表示をご利用いただけない場合があります。視認性は次のクラスに分類されます。
- 全体表示
- 書籍全体を表示できます。該当する書籍はパブリック ドメインである可能性があります。
- 限定的な使用
- 書籍の一部は閲覧できます。この書籍は著作権で保護されているため、Google ブックスはユーザーがこれらのページにアクセスできるようにする許可を得ています。これらの書籍はスニペット表示の書籍と異なり、ユーザーはページ全体を表示できます。
- スニペット表示とプレビューなし
- ユーザーには [書籍について] ページのみが表示されます。多くても、書籍の抜粋のみ利用できます。この書籍はスキャンされていないか、著作権で保護されているため、ユーザーの検索キーワードに関連する少数の「スニペット」を Google ブックスで公開する許可を得ていません。
はじめに
静的リンクのドキュメントでは、Google ブックスの特定の書籍のページへの URL を生成するとても簡単な方法について説明しています。残念ながら、特定の書籍が Google ブックスのインデックスに登録されていない場合や、特定の地域のユーザーにプレビューが利用できない場合があります。静的リンクは「盲目的」であるため、意図した効果が得られないことがあります。
Dynamic Links は、JavaScript を使用して書籍の視認性をクエリするための、プログラマティックなクライアントサイドの代替メソッドです。これにより、ブック検索へのリンクの信頼性と予測可能性が高まるため、ユーザー エクスペリエンスの一貫性が向上します。視認性はエンドユーザーの所在地によって異なるため、ダイナミック リンクのインターフェースはサーバーサイドまたはオフラインのクエリ向けには設計されていません。
Dynamic Links の機能を理解するには、このドキュメントの最後にあるコードサンプルに進んでください。
ブランドの取り扱いガイドライン
Dynamic Links をレンダリングするときは、Google ブックス API ファミリーを規定しているブランドの取り扱いガイドラインに従う必要があります。特に、
- 帰属情報および Google ブックスへのリンクは維持されなければなりません。
- Google ブックスでプレビューにリンクする際は、承認済みの Google プレビュー ボタンのみを使用する必要があります。
- テキストリンク、ボタン、ドキュメント、説明テキストは、承認された命名規則に従う必要があります。たとえば、Google ブックスのプレビューにリンクする際に「ダウンロード」や「読む」という動詞は使用しないでください。これはパブリック ドメインの作品しかダウンロードできないためです。
ブランディングの例
フリーコノミクス: ローグ エコノミストが秘めたあらゆる側面を探る
執筆者: Steven Levitt、Stephen Dubner
このドキュメントの最後にあるサンプル セクションでは、現在のブランディング ガイドラインに準拠している他の例を紹介しています。
クライアントサイド API
クライアントサイドのダイナミック リンクの中核にあるのは、1 冊以上の書籍に関する情報をリクエストする URL を作成し、<script> タグを使用して Google ブックスにリクエストを送信できる URL 形式です。
- 構文の例:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
この URL の形式は、書籍にリンクするために使用される URL 構文に似ていますが、書籍 ID フィールドには複数の書籍 ID をカンマ区切りで指定し、「jscmd」と「callback」パラメータを追加することができます。必要に応じて、追加の引数を指定して、視認性フィルタを制御することもできます。
Dynamic Links は、書籍を特定するさまざまな方法（ISBN、OCLC 番号、LCCN キー）をサポートしています。この API では、GET リクエストの最大サイズまでのバッチ クエリを実行できます。
- ISBN
&bibkeys=ISBN:0451526538（API は ISBN 10 と 13 の両方をサポートしています）- オフライン コンバージョン アクション
&bibkeys=OCLC:36792831- LCCN
&bibkeys=LCCN:96072233-
この呼び出しからのレスポンスは、リクエストされた書籍に関する情報で、1 つ以上の JSON オブジェクトとして返されます。JSON オブジェクトの構造は次のとおりです。
JsonSearchResult {
string bib_key;
string info_url;
string preview_url;
string thumbnail_url;
string preview;
};
これらのフィールドには次の情報が表示されます。
- bib_key
- この書籍のクエリに使用される識別子。
- info_url
- Google ブックス内の書籍に関する情報を含むページ（この書籍の概要ページ）の URL。
- preview_url
- 書籍のプレビューへの URL。ユーザーは書籍の表紙に直接移動できます。リクエストで取得できる書籍が「スニペット表示」または「プレビューなし」のみの場合、プレビュー URL は返されません。
- thumbnail_url
- 書籍の表紙のサムネイルへの URL。
- プレビュー
- 書籍の視認性状態を示す値。
full（完全表示の書籍の場合）、partial（限定プレビューの書籍の場合）、noview（スニペットまたはプレビューなしの書籍の場合）です。
- 埋め込み可能
- ブック検索の埋め込みビューアを使用してサードパーティのページに書籍を埋め込むことができる場合、このブール値は
true です。
レスポンスは、book オブジェクトのマップの値を含む「books」と、そのリクエストで有効になっているオプションのリストを含む「options」の 2 つのフィールドを持つ JSON オブジェクトです。オプションが指定されていない場合、レスポンスで "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 結果に基づいて、ウェブページのコンテンツと外観を変更できます。現時点では、この処理のために DOM を変更するためのライブラリは GBS に用意されていません。
パラメータと追加フィールド
- jscmd
- Google ブックスへのリクエストです。
- callback
- 戻り値を渡す JavaScript 関数の名前。
同期モードと非同期モード
非同期モード
非同期モードでは、デベロッパーはドキュメントの <head> に <script> タグを配置し、ページのレンダリングに必要なすべての識別子を含む URL を構築します。呼び出しから変数にデータが取り込まれます。これにより、ドキュメントの他の部分で書籍の情報を利用できるようになり、HTML や JavaScript ですぐにアクセスできます。
同期モード
同期モードでは、デベロッパーは HTML <body> の途中の URL を使用し、レスポンスは JavaScript コールバックを使用して処理されます。
よくある質問
- Q: ダイナミック リンクを使用するには、API キーやその他の権限が必要ですか？
- A: ダイナミック リンクを使用するために API キーやその他の認証は必要ありません。まずは、サンプルの一つをコピーして貼り付け、手直しをしてみましょう。
- Q: JavaScript をサポートしていないブラウザや JavaScript が無効になっているブラウザはどうなりますか？
- A: ユーザーのブラウザで JavaScript が有効になっていない場合、Google ブックスに書籍があるかどうかをテストする方法はありません。JavaScript に対応していないブラウザでは、Google ブックスの静的リンク構造を使用することをおすすめします。ただし、リンク先の書籍が Google ブックスに登録されているかどうかを事前に知ることはできません。
- Q: 書籍は一度に何冊まで検索できますか？
- A: 検索できる書籍の数は、GET リクエストの長さによってのみ制限されます。Microsoft Internet Explorer では、URL の最大長（2,083 文字）によって GET リクエストの長さが制限されます。
- Q: 少し前の書籍について、Google ブックスの検索結果が返されました。結果が返されないのはなぜですか？
- A: デベロッパーから発行されるリクエストの数は通常とは異なるため、Google ブックスのセキュリティ上の注意事項を誤って伝えてしまうことがあります。これを確認するには、API から何が返されるかを確認します。キャプチャを入力するリクエストの場合は、発行したクエリの数が多すぎます。Google ブックスにログインして、もう一度お試しください。
- Q: プライバシーについてはどうですか？
- A: 書籍の視認性に関するクエリに回答する際、Google は個人を特定できないサーバーのログデータを受け取ります。Google はユーザーのプライバシーを重視しており、このデータは Google のプライバシー ポリシーに記載されているとおりに取り扱われます。書籍の視認性を含むサービスをユーザーに提供している場合、そのサービスがダイナミック リンクを介して Google にもクエリを送信することをユーザーに伝えることをおすすめします。
コードサンプル
このセクションでは、Dynamic Links のさまざまな使用方法を示すサンプルを示します。任意の例をクリックすると、実際の動作を確認できます。基になるコードを確認するには、ブラウザから「ソースを表示」します。
- 書籍ページの [プレビュー] ボタン
Dynamic Links を使用してサイト上の個々の書籍ページに「プレビュー」ボタンを追加する場合、この例が適しています。この実装では、Google ブックスへの同期呼び出しを使用します。 - コースのリーディング リスト
この例は、学術コースの一般的な書籍リストを示しています。1 回の同期呼び出しで、Google ブックスの書籍ページへのリンク、表紙画像の追加、プレビュー提供の可否の通知を行います。
- 代替書籍リスト
前の例と同様に、このサンプルでも非同期 API コールバックを使用してブック検索にリンクを追加します。
- インタラクティブ AJAX
Dynamic Links は、高度にインタラクティブな AJAX アプリケーションでも使用できます。このサンプルは、ページを更新せずにさまざまな呼び出しを発行する方法を示しています。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2024-06-28 UTC。
[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["必要な情報がない","missingTheInformationINeed","thumb-down"],["複雑すぎる / 手順が多すぎる","tooComplicatedTooManySteps","thumb-down"],["最新ではない","outOfDate","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["サンプル / コードに問題がある","samplesCodeIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2024-06-28 UTC。"],[[["\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)."]]
