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

スタートガイド

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

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

はじめに

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

始める前に

Google アカウントを取得する

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

ブックスの詳細

Google ブックスのコンセプトに習熟されていない場合は、コーディングの前にこのドキュメントを読み、ユーザーインターフェースでテストしてください。このドキュメントは、ウェブプログラミングの概念とウェブデータ形式に精通していることを前提としています。

リクエストの承認とアプリケーションの識別の詳細

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

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

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

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

Books API の背景

ブックスのコンセプト

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

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

Books API のデータモデル

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

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

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

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

Books API のオペレーション

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

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

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

リソースの種類	サポートされている操作
	リスト	挿入	取得	更新	削除
ボリューム	あり*		あり
本棚	あり*	はい、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 API のオペレーションで説明されているように、サポートされている Books オペレーションは 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

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

注: access_token パラメータを使用して OAuth 2.0 トークンを渡すことで、認証済みのメソッドを呼び出すことができます。JavaScript で使用する OAuth 2.0 トークンを取得するには、クライアントサイドウェブアプリケーション用の OAuth 2.0 の手順を行ってください。API 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 をご覧ください。