スタートガイド

このドキュメントでは、Google Books API を使用するために必要な背景知識について詳しく説明します。

はじめに
始める前に
Books API の概要
通話スタイル
1. REST
データ形式
1. JSON

はじめに

このドキュメントは、Google Books API と連携できるアプリケーションを作成するデベロッパーを対象としています。Google ブックスは、世界中の書籍をデジタル化するというビジョンを持っています。Google ブックス API を使用して、コンテンツの検索、認証済みユーザーの個人用ライブラリの整理、変更を行うことができます。

始める前に

Google アカウントを取得する

テスト用に Google アカウントが必要です。テストアカウントをすでにお持ちの場合は、Google ブックスのユーザーインターフェースにアクセスして、テストデータのセットアップ、編集、表示を行うことができます。

ブックスについて理解する

Google ブックスのコンセプトにまだ詳しくない方は、このドキュメントを読み、ユーザーインターフェースの基本操作に慣れてからコード作成に着手してください。なお、このドキュメントはウェブプログラミングの概念やウェブ用のデータ形式について理解していることが前提となっています。

リクエストの承認とアプリケーションの識別について

アプリケーションから限定公開データがリクエストされた場合は、対象データへのアクセス権を持つ認証済みのユーザーがリクエストを承認する必要があります。

特に、Google Books API の [マイライブラリ] のすべてのオペレーションは非公開と見なされ、認証と認可が必要です。また、Google ブックスのデータを変更するオペレーションは、そのデータを所有するユーザーのみが実行できます。

アプリケーションから一般公開データがリクエストされた場合は、リクエストの承認は必要ありませんが、ID（API キーなど）を追加する必要があります。

リクエストを承認して API キーを使用する方法については、API の使用に関するドキュメントのリクエストを承認してアプリケーションを識別するをご覧ください。

Books API の背景

書籍のコンセプト

Google ブックスは、次の 4 つの基本コンセプトに基づいて構築されています。

ボリューム: ボリュームは、Google ブックスがホストする書籍や雑誌に関するデータを表します。これは、Books API の主要なリソースです。この API の他のすべてのリソースは、ボリュームを含むか、ボリュームにアノテーションを付けます。
本棚: 本棚は書籍のコレクションです。Google ブックスでは、各ユーザーに事前定義された本棚が用意されています。その一部はユーザーが完全に管理し、一部はユーザーのアクティビティに基づいて自動的に入力され、一部は両方の混合です。ユーザーは、他の本棚を作成、変更、削除できます。他の本棚には、常に手動で書籍が追加されます。本棚はユーザーが非公開または公開に設定できます。
注: 現在、本棚の作成と削除、本棚のプライバシー設定の変更は、Google ブックスのサイトでのみ行うことができます。
レビュー: ボリュームのレビューは、星評価とテキストの組み合わせです。ユーザーは、1 巻につき 1 件のレビューを送信できます。外部ソースからのレビューも利用可能で、適切に帰属表示されます。
読書位置: 読書位置は、ユーザーが最後に読んだ巻の場所を示します。ユーザーが持つことができる読書位置は、1 つの書籍につき 1 つのみです。ユーザーがその巻を以前に開いていない場合、読書位置は存在しません。最後に読んでいた箇所には、単語の解像度までの詳細な位置情報を保存できます。この情報は常にユーザーに対して非公開です。

Books API データモデル

リソースとは、一意の識別子を持つ個別のデータエンティティです。Books API は、前述のコンセプトに基づいて 2 種類のリソースを使用します。

Volume リソース: ボリュームを表します。
Bookshelf リソース: 特定のユーザーの単一の本棚を表します。

Books API のデータモデルは、コレクションと呼ばれるリソースのグループに基づいています。

ボリュームコレクション: ボリュームコレクションは、Google ブックスで管理されるすべてのボリュームリソースのコレクションです。そのため、すべてのボリュームリソースを一覧表示することはできませんが、一連の検索語句に一致するすべてのボリュームを一覧表示することはできます。
Bookshelf コレクション: 本棚コレクションは、Google ブックスで管理されるすべての本棚リソースで構成されます。本棚は常に特定のユーザーのライブラリのコンテキストで参照する必要があります。本棚には 0 冊以上の書籍を含めることができます。

Books API オペレーション

次の表に示すように、Books API では、コレクションとリソースに対して 5 つの異なるメソッドを呼び出すことができます。

オペレーション	説明	REST HTTP マッピング
list	コレクション内のリソースの指定されたサブセットを一覧表示します。	コレクション URI の `GET`。
insert	新しいリソースをコレクションに挿入します（新しいリソースを作成します）。	コレクション URI の `POST`。新しいリソースのデータを渡します。
get	特定のリソースを取得します。	リソース URI の `GET`。
update	特定のリソースを更新します。	リソース URI の `PUT`。更新されたリソースのデータを渡します。
delete	特定のリソースを削除します。	リソース URI の `DELETE`。削除するリソースのデータを渡します。

さまざまなタイプのリソースでサポートされているオペレーションを次の表にまとめます。ユーザーのプライベートデータに適用されるオペレーションは「マイライブラリ」オペレーションと呼ばれ、すべて認証が必要です。

リソースの種類	サポートされている操作
	list	insert	get	update	削除
ボリューム	○*		はい
本棚	○*	はい、AUTHENTICATED	○*	はい、AUTHENTICATED	はい、AUTHENTICATED
読書の位置		はい、AUTHENTICATED	はい、AUTHENTICATED	はい、AUTHENTICATED	はい、AUTHENTICATED

*これらのオペレーションには、認証済みと未認証の両方のバージョンがあります。認証済みのリクエストはユーザーの非公開の「マイライブラリ」データに対して実行され、未認証のリクエストは公開データに対してのみ実行されます。

呼び出しのスタイル

API を呼び出す方法はいくつかあります。

REST を直接使用する
JavaScript から REST を使用する（サーバーサイドコードは不要）

REST

REST は、データをリクエストして変更するための便利で一貫したアプローチを提供するソフトウェアアーキテクチャのスタイルです。

REST という用語は「Representational State Transfer」の省略形です。Google API のコンテキストでは、HTTP 動詞を使用して、Google が保存しているデータ表現を取得および変更することを表しています。

RESTful システムでは、リソースはデータストアに保存されています。クライアントはサーバーに対して特定のアクション（リソースの作成、取得、更新、削除など）を実行するようリクエストを送信し、サーバーはそのアクションを実行して、レスポンスを送信します。多くの場合、レスポンスは指定されたリソースの表現形式を取ります。

Google の RESTful API では、クライアントは POST、GET、PUT、DELETE などの HTTP 動詞を使用してアクションを指定します。また、次の形式のグローバルに一意な URI でリソースを指定します。

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

すべての API リソースは HTTP でアクセス可能な一意の URI を持っているため、REST はデータキャッシュを有効にし、ウェブの分散インフラストラクチャで動作するように最適化されています。

HTTP 1.1 標準のドキュメントのメソッド定義をご覧ください。GET、POST、PUT、DELETE の仕様が記載されています。

Books API の REST

サポートされている Books オペレーションは、Books API オペレーションで説明されているように、REST HTTP 動詞に直接マッピングされます。

Books API の URI の形式は次のとおりです。

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

ここで、resourceID はボリュームまたは本棚リソースの識別子、parameters はクエリに適用するパラメータです。詳細については、クエリパラメータリファレンスをご覧ください。

resourceID パス拡張子の形式を使用すると、現在操作しているリソースを特定できます。例:

https://www.googleapis.com/books/v1/volumes
https://www.googleapis.com/books/v1/volumes/volumeId
https://www.googleapis.com/books/v1/mylibrary/bookshelves
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
...

URI に mylibrary が含まれるオペレーションは、現在認証されているユーザーのプライベートライブラリデータにのみ適用されます。この API で対応している各オペレーションのすべての URI については、Books API リファレンスに要約されています。

以下に、Books API での動作を示す例をいくつか示します。

キルティングを検索します。

GET https://www.googleapis.com/books/v1/volumes?q=quilting

ボリューム s1gVAAAAYAAJ に関する情報を取得します。

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

JavaScript からの REST

JavaScript（JSON-P とも呼ばれます）から REST を使用して Books API を呼び出すには、callback クエリパラメータとコールバック関数を使用します。これにより、サーバーサイドコードを記述することなく、書籍データを表示するリッチアプリケーションを作成できます。

注: 認証済みメソッドは、access_token パラメータを使用して OAuth 2.0 トークンを渡すことで呼び出すことができます。JavaScript で使用する OAuth 2.0 トークンを取得するには、クライアントサイドウェブアプリケーション用の OAuth 2.0 の説明に沿って操作してください。APIs Console の [API アクセス] タブで、ウェブアプリケーションのクライアント ID を設定し、トークンを取得する際にその OAuth 2.0 認証情報を使用するようにしてください。

次の例では、このアプローチを使用して「ハリー・ポッター」の検索結果を表示します。

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

データ形式

JSON

JSON（JavaScript Object Notation）は言語に依存しない一般的なデータフォーマットであり、任意のデータ構造を単純なテキスト形式で表示します。詳しくは json.org をご覧ください。

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