このページは Cloud Translation API によって翻訳されました。

スタートガイド

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

はじめに
準備
Books API の背景
通話スタイル
1. REST
データ形式
1. JSON

はじめに

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

始める前に

Google アカウントを取得する

テストを行うには、Google アカウントが必要です。テストアカウントをすでにお持ちの場合は、準備は完了です。Google ブックスのユーザーインターフェースにアクセスして、テストデータの設定、編集、表示を行えます。

ブックスに慣れる

Google ブックスのコンセプトに精通していない場合は、コーディングを始める前にこのドキュメントを読んで、ユーザーインターフェースを試してみることをおすすめします。このドキュメントは、ウェブプログラミングのコンセプトとウェブデータ形式の知識があることを前提としています。

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

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

特に、Google ブックス API の [マイライブラリ] の下のすべての操作は非公開とみなされ、認証と承認が必要になります。また、Google ブックスのデータを変更する操作は、そのデータを所有するユーザーのみが行うことができます。

アプリケーションが一般公開データをリクエストする場合、リクエストを承認する必要はありませんが、API キーなどの識別子を付加する必要があります。

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

ブックス API のバックグラウンド

ブックスのコンセプト

Google ブックスは、次の 4 つの基本概念に基づいて構築されています。

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

ブックス API データモデル

リソースとは、固有識別子を持つ個別のデータエンティティです。ブックス API は、前述のコンセプトに基づいて、次の 2 種類のリソースで動作します。

ボリュームリソース: ボリュームを表します。
Bookshell リソース: 特定のユーザーの 1 つの本棚を表します。

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

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

ブックス API オペレーション

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

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

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

リソースの種類	サポートされている操作
	リスト	挿入	取得	更新	削除
ボリューム	○*		あり
本棚	○*	はい、AUTHENTICATED です	○*	はい、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 の仕様が記載されています。

ブックス API の REST

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

ブックス 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 での使用例を示します。

quilting を検索します。

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 を使用して、callback クエリパラメータとコールバック関数を使用して、Books API を呼び出すことができます。これにより、サーバー側のコードを記述せずに書籍データを表示する高機能なアプリケーションを作成できます。

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

次の例では、このアプローチを使用して「harry potter」の検索結果を表示します。

<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 をご覧ください。