Dynamic Links

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Google ブックスのダイナミック リンク機能を使用すると、サイトから Google ブックスへのカスタマイズが可能な信頼性の高いリンクを作成できます。たとえば、Google のインデックスに登録された書籍のみが表示されるリンクや、Google ブックスで書籍をプレビューできるかどうかをユーザーに示すリンクを表示する場合に、このツールが使用できます。Dynamic Links 機能を使用すると、Google ブックスへのリンクにサムネイル画像を追加できます。このドキュメントでは、サイトにこの機能をすばやく追加する方法について説明します。

注: この機能は、以前は Book Viewability API と呼ばれていました。

プレビュー ウィザードは、ダイナミック リンクの上に構築されたツールで、コードを数行コピーするだけで、サイトからプレビューへ簡単にリンクできます。このドキュメントは、書籍検索とのリンク方法をカスタマイズしようとしている上級デベロッパーを対象としています。

目次

  1. 視聴者
  2. 書籍検索の用語
  3. はじめに
  4. ブランドの取り扱いガイドライン
  5. クライアントサイド API
    1. リクエスト URL の形式
    2. JSON 結果の形式
  6. 同期モードと非同期モード
  7. よくある質問
  8. コードサンプル

視聴者

ダイナミック リンクに関するドキュメントは、Google ブックス内の書籍にリンクするウェブ アプリケーションを作成するプログラマーを対象としています。このドキュメントは、HTTP プロトコルと基本的な JavaScript に精通していることを前提としています。

書籍検索の用語

Google ブックスではユーザーの地域による著作権の制限が優先されるため、一部の書籍のプレビューや全体表示は、一部の地域ではご利用いただけません。視認性は、次のクラスにクラスタ化されています。

全体表示
書籍全体が表示対象となります。これらの書籍はパブリック ドメインである場合があります。
限定的な使用
書籍の一部を閲覧できる。この書籍は著作権で保護されているため、Google ブックスはこうしたページへのアクセスをユーザーに許可しています。これらの書籍は、ユーザーがページ全体を閲覧できるという点でスニペット表示の書籍とは異なります。
スニペットを表示、プレビューなし
ユーザーには、[書籍について] ページのみが表示されます。書籍から抜粋できるのは、最大でも一部のみです。この書籍はスキャンされていないか、著作権で保護されているため、ユーザーの検索キーワードに関連する複数のスニペットを公開するための許可が Google ブックスに与えられていません。

はじめに

静的リンクのドキュメントでは、Google ブックスの特定の書籍のページへの URL を生成する非常に簡単な方法について説明しています。残念ながら、特定の書籍が Google ブックスのインデックスに登録されていない、または特定の地域のユーザーがプレビューを利用できない場合があります。静的リンクは「ブラインド」であるため、意図した効果が得られないことがあります。

Dynamic Links は、JavaScript を使用して書籍の視認性をクエリする、プログラマティックなクライアント側の代替方法を提供します。これにより、書籍検索への信頼性の高いリンクと予測可能なリンクを含めることができ、ユーザー エクスペリエンスの一貫性が向上します。視認性はエンドユーザーの場所によって異なるため、ダイナミック リンク インターフェースはサーバーサイドまたはオフラインのクエリ用には設計されていません。

Dynamic Links で何ができるかについては、このドキュメントの最後にあるコードサンプルに進んでください。

ブランドの取り扱いガイドライン

Dynamic Links をレンダリングする場合、Google Books API ファミリーのブランディング ガイドラインを遵守する必要があります。特に、

  • 帰属表示と Google ブックスへのリンクを維持する必要があります。
  • Google ブックスでプレビューにリンクする際は、承認済みの Google プレビュー ボタンのみを使用する必要があります。
  • テキストリンク、ボタン、ドキュメント、説明テキストはすべて、承認済みの命名規則を遵守する必要があります。たとえば、Google ブックスでのプレビューにリンクするときは、「ダウンロード」や「読み取り」などの動詞を使用しないでください。ダウンロードできるのは、パブリック ドメインの作品のみです。

ブランディングの例

Freakonomics: An Rogue Economist Explores the Hidden Side of Everything
作者: Steven Levitt and 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 の両方に対応しています)。
OCLC
&bibkeys=OCLC:36792831
LCCN(LCCN)
&bibkeys=LCCN:96072233

JSON 結果の形式

この呼び出しからのレスポンスは、1 つ以上の JSON オブジェクトとして返される、リクエストされた書籍に関する情報になります。JSON オブジェクトの構造は次のとおりです。

JsonSearchResult {
    string bib_key;
    string info_url;
    string preview_url;
    string thumbnail_url;
    string preview;
};

これらのフィールドには、次の情報が表示されます。

bib_key
この書籍に対してクエリを実行するために使用される識別子。
情報 URL
書籍に関する情報(この書籍のページ)がある Google ブックス内のページの URL。
プレビュー URL
書籍のプレビューの URL。ユーザーを書籍の表紙に直接誘導します。リクエスト可能なスニペット ビューまたはプレビュー不可の書籍のみの場合、プレビュー URL は返されません。
サムネイル URL
書籍の表紙のサムネイルへの URL。
プレビュー
書籍の視認性の状態を示す値。full(全文表示の場合)、partial(限定プレビューの書籍)、noview(スニペットまたはプレビューなし)を指します。
埋め込み可能
書籍検索の埋め込みビューアを使用してサードパーティのページに書籍を埋め込むことができる場合、このブール値は true です。

レスポンスは、書籍オブジェクトのマップの値と「リクエスト」に対して有効なオプションのリストを含む「本」の 2 つのフィールドを持つ JSON オブジェクトです。オプションが指定されていない場合、レスポンスの「オプション」フィールドが省略されることがあります。例:

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 ブックスへのリクエスト。
callback
戻り値を渡す JavaScript 関数の名前。

同期モードと非同期モード

非同期モード

非同期モードでは、<script> タグをドキュメントの <head> に配置し、ページのレンダリングに必要なすべての識別子を含む 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 にクエリを送信することをユーザーに知らせることができます。

コードサンプル

このセクションでは、Dynamic Links のさまざまな使用方法を示すサンプルを示します。サンプルをクリックすると、実際の動作を確認できます。基盤となるコードを確認するには、ブラウザから「ソースを表示」します。

  • 書籍ページのプレビュー ボタン
    ダイナミック リンクを使用してサイト上の個々の書籍ページに「プレビュー」ボタンを追加することを想定している場合は、この例が参考になります。この実装では、Google ブックスへの同期呼び出しを使用します。
  • コースのリーディング リスト
    この例では、学習コースの典型的な書籍リストを示しています。同期呼び出しを 1 回行うことで、Google ブックスの書籍のページへのリンク、表紙の画像の追加、プレビュー機能の提供が可能になります。
  • 別の書籍情報
    このサンプルは、上記の例と同様に非同期 API コールバックを使用して書籍検索へのリンクを追加します。
  • インタラクティブな AJAX
    高度にインタラクティブな AJAX アプリケーションで Dynamic Links を使用できます。この例では、ページを更新せずに多数の呼び出しを行う方法を示します。