Java クライアント ライブラリの使用

このドキュメントでは、Java クライアント ライブラリを使用して Google Data API（GData）のクエリを送信し、返されたレスポンスを解釈する方法について説明します。

Google は、データ API を持つサービスを操作するための、さまざまなプログラミング言語によるクライアント ライブラリのセットを提供しています。これらのライブラリを使用すると、GData リクエストを作成してサービスに送信し、レスポンスを受け取ることができます。

このドキュメントでは、Java クライアント ライブラリの使用方法に関する一般的な情報とともに、一般的な使用例を紹介します。

このクライアント ライブラリを使用するには、Java 1.5 を実行する必要があります。

Java クライアント ライブラリをダウンロードします。

このガイドの例では、Google カレンダー API を使用していますが、Calendar API の使用に関する正確かつ最新のガイドではありません。特定のサービスの Data API で Java クライアント ライブラリを使用する方法については、サービス固有のドキュメントをご覧ください。たとえば、Google カレンダーの場合は、Calendar Data API デベロッパー ガイドをご覧ください。

目次

  1. 視聴者
  2. データモデルの概要
  3. チュートリアルと例
    1. クライアントの構築と実行
    2. フィードをリクエストする
    3. 新しいアイテムを挿入する
    4. 特定のエントリをリクエストする
    5. エントリの検索
    6. カテゴリ別のクエリ
    7. アイテムを更新する
    8. アイテムの削除
  4. Reference

対象者

このドキュメントは、GData サービスとやり取りできるクライアント アプリケーションを作成する Java プログラマーを対象としています。

このドキュメントは、Google Data API プロトコルの背後にある一般的な概念を理解していることを前提としています。また、Java でのプログラミング方法についての知識があることも前提となります。

クライアント ライブラリで提供されるクラスとメソッドに関するリファレンス情報については、Java クライアント ライブラリ API リファレンス（Javadoc 形式）をご覧ください。

このドキュメントは順番に読むことを目的としています。各例は前の例に基づいています。

データモデルの概要

Java クライアント ライブラリは一連のクラスを使用して、Google Data API で使用される要素を表します。たとえば、<atom:feed> クラスに対応するフィード クラスがあり、エントリの作成、各種サブ要素の値の取得や設定などを行うメソッドがあります。また、<atom:entry> 要素に対応する Entry クラスもあります。Google Data API で定義されたすべての要素に独自のクラスがあるわけではありません。詳しくは、リファレンス ドキュメントをご確認ください。

このライブラリにより、Atom コンテンツが自動的に解析され、Atom 要素の値が適切なオブジェクトに格納されます。たとえば、getFeed メソッドはフィードを取得し、解析して、結果の値を含むフィード オブジェクトを返します。

フィードまたはエントリをサービスに送信するには、フィードまたはエントリ オブジェクトを作成し、ライブラリ メソッド（insert メソッドなど）を呼び出してオブジェクトを XML に自動的に変換し、送信します。

必要に応じて XML を解析したり、生成したりすることもできます。最も簡単な方法は、Rome などの適切なサードパーティ ライブラリを使用することです。

Google Data API の XML 構文は拡張可能であるのと同様、対応するオブジェクト モデルも拡張可能です。たとえば、クライアント ライブラリには、Google Data 名前空間で定義された要素に対応するクラスが用意されています。

チュートリアルと例

次の例は、Java クライアント ライブラリを使用してさまざまなデータ API リクエストを送信する方法を示しています。

具体例として、特定のサービス（Google カレンダー）を利用する方法を説明します。Google カレンダーは、他の Google サービスと異なる点を示し、他のサービスで使用できるようにサンプルを調整します。カレンダーについて詳しくは、Google Calendar Data API のドキュメントをご覧ください。

クライアントの構築と実行

このドキュメントの例では、次の import ステートメントを使用する必要があります。

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

フィードのリクエスト

Google Calendar Data API のドキュメントに記載されているように、次の HTTP リクエストをカレンダーに送信することで、カレンダー フィードをリクエストできます。

GET http://www.google.com/calendar/feeds/userID/private/full

その場合は、userID をユーザーのメールアドレスに置き換える必要があります。詳しくは、カレンダーのドキュメントをご覧ください。代わりに、カレンダーの操作用に特別なデフォルト URL（カレンダーのドキュメントに記載）を使用できますが、このドキュメントでは、ユーザー ID を含む非公開の完全フィード URL を使用します。

また、適切な認証を行う必要があります。このサンプルとカレンダー ドキュメントの最初の例との主な違いは、（1）この例には認証が含まれ、（2）この例では、カレンダー固有の CalendarService クラスではなく、より一般的な GoogleService クラスを使用していることです。

ここで使用している認証システム（「Google 認証用インストール済みアプリケーション」と呼ばれます）は、デスクトップ クライアントなどのインストール済みのクライアント アプリケーションでの使用のみに適しており、ウェブ アプリケーションには使用できません。認証について詳しくは、Google アカウント認証のドキュメントをご覧ください。

Java クライアント ライブラリを使用してカレンダー フィードをリクエストするには、メールアドレスが「liz@gmail.com」でパスワードが「mypassword」のユーザーに対して次のコードを使用します。

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

GoogleService クラスは、GData サービスへのクライアント接続（認証を使用）を表します。クライアント ライブラリを使用してサービスにクエリを送信する一般的な手順は、次の手順で構成されます。

  1. 適切な URL を取得または作成します。
  2. サービスにデータを送信する場合（新しいエントリを挿入する場合など）は、クライアント ライブラリのクラスを使用して元データをオブジェクトに変換します。（この例ではフィードだけをリクエストする場合は、このステップは適用されません）。
  3. 新しい GoogleService インスタンスを作成し、サービス名（カレンダーの場合は "cl" など）とアプリケーションの名前（companyName-applicationName-versionID の形式）を設定します。
  4. 適切な認証情報を設定します。
  5. フィードで使用される拡張機能をクライアント ライブラリに示し、ライブラリが返されたフィードを正しく解析できるようにします。
  6. リクエストを送信して結果を受け取るメソッドを呼び出します。

setUserCredentials メソッドは、クライアントがクエリを送信しているユーザーの ID とパスワードを指定します。このドキュメントの例では、「認証済みアプリケーションの認証」認証システムを使用しています。認証システムについて詳しくは、Google アカウント認証のドキュメントをご覧ください。

認証情報を設定したら、declareExtensions メソッドを呼び出して、フィードで使用する拡張機能を指定します。この場合、フィードはイベント フィードであるため、イベントの種類で定義された拡張機能が使用されます。

フィード全体をリクエストするには、getFeed メソッドを呼び出します。このメソッドは、URL を受け取って、その URL で検出されたフィード全体を返します。具体的なクエリを送信する方法については、このドキュメントで後ほど説明します。

GoogleService クラスの他のメソッドと同様に、getFeed は必要に応じて認証とリダイレクトを処理します。

新しいアイテムを挿入する

新しいカレンダーの予定を作成するには、次のコードを使用します。

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

URL を設定した後、EventEntry オブジェクトを作成します。EventEntry は抽象基本クラス BaseEntry から派生します。このクラスは、Entry クラスの親クラスでもあり、<atom:entry> 要素を表します。

EventEntry クラスは、イベントの種類を表します。詳細については、Kinds ドキュメントをご覧ください。カレンダー以外のサービスでは、返されたエントリを EventEntry オブジェクトではなく Entry オブジェクトに割り当てることができます。

エントリのタイトルは、さまざまな形式（書式なしテキスト、HTML、XHTML）でテキストを保持するクラスです。TextConstructエントリの内容は Content オブジェクトで表されます。このクラスは、書式なしテキストやその他の形式のコンテンツ（XML データやバイナリデータを含む）を保持できるクラスです。（ただし、setContent メソッドは TextConstruct を受け入れることもできます）。

各著者は、名前、URI、メールアドレスで表されます。（この例では URI を省略しています）。エントリに作成者を追加するには、エントリの getAuthors().add メソッドを呼び出します。

前の例で作成したのと同じ GoogleService オブジェクトを使用しています。この場合、insert メソッドを呼び出し、指定された挿入 URL にアイテムを送信します。

サービスは新しく作成されたエントリを返します。このエントリには、エントリの編集 URL など、サーバー生成の追加要素を含めることができます。

例外として HTTP ステータス コードが返されます。

上記のコードは、適切な認証とともに POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full を送信し、Event という形式でエントリを提供するのと同じです。

特定のエントリのリクエスト

次のコードでは、前の例で挿入した特定のエントリをリクエストできます。

この一連の例では、挿入されたエントリをカレンダーがすでに返すため、そのエントリを取得する必要はありませんが、エントリの URI がわかっていれば同じ手法を適用できます。

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

挿入されたエントリのメソッド getSelfLink は、エントリの URL を含む Link オブジェクトを返します。Link クラスには、URL を String として返す getHref メソッドがあり、そこから URL オブジェクトを作成できます。

エントリを取得するには、サービスの getEntry メソッドを呼び出すだけです。

ここでは EventEntry.class を getEntry のパラメータとして提供しています。これは、サービスが単なるエントリではなく単にイベントを返すことを想定しています。カレンダー以外のサービスについては、代わりに Entry.class を渡すだけで済みます。

上記のコードは、適切な認証とともに GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID をカレンダーに送信することと同じです。

エントリの検索

全文検索から最初の一致を取得するには、次のコードを使用します。

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

この例では、まず Query オブジェクトを作成します。このオブジェクトは主に URL と関連するクエリ パラメータで構成されます。標準の GData クエリ パラメータには、それぞれセッター メソッドがあります。addCustomParameter メソッドを使用して、特定のサービスにカスタムクエリ パラメータを設定することもできます。

Query を作成した後、サービスの query メソッドに渡します。このメソッドは、クエリ結果を含むフィードを返します。別の方法として、（フィードの URL にクエリ パラメータを追加して）ご自身で URL を作成し、getFeed メソッドを呼び出すという方法もありますが、query メソッドは、URL をご自身で作成する必要がないように、便利な抽象化レイヤを提供します。

フィードの getEntries メソッドはフィード内のエントリのリストを返します。getEntries().size はフィード内のエントリ数を返します。

この場合、クエリの結果が返された場合は、最初に一致した結果が Entry オブジェクトに割り当てます。次に、Entry クラスの getTitle().getPlainText メソッドを使用してエントリのタイトルを取得し、テキストに変換します。

上記のコードは、GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis をカレンダーに送信することと同じです。

カテゴリ別のクエリ

注: Google カレンダーには予定とラベルが関連付けられていないため、この例はカレンダーには適用されません。

以前の全文検索に一致し、特定のカテゴリまたはラベルを持つすべてのエントリで構成されるフィードを取得するには、次のコードを使用します。

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

Category クラスは、もちろん、カテゴリ フィルタで使用するカテゴリを表します。Query.CategoryFilter クラスには複数のカテゴリを含めることができますが、ここでは 1 つのカテゴリのみのフィルタを作成しています。

次に、そのフィルタを既存のクエリに追加します。このクエリには前の例の全文クエリ文字列が引き続き含まれています。

ここでも query メソッドを使用して、クエリをサービスに送信します。

Google カレンダーでカテゴリ検索が許可されている場合、上記のコードは Google カレンダーに GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis を送信するのと同じです。

アイテムを更新する

既存のアイテムを更新するには、次のコードを使用します。この例では、以前に取得したエントリのタイトルを古いテキスト（"Tennis with Darcy"）から「重要な会議」に変更します。

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

まず、先ほど取得したエントリに新しいタイトルを設定します。次に、getEditLink メソッドを使用してエントリの編集 URL を取得します。次に、サービスの update メソッドを呼び出して、更新されたエントリを送信します。

サービスは、このエントリの新しいバージョンの新しい URL を含め、更新されたエントリを返します。（エントリ バージョンの詳細については、プロトコル リファレンス ドキュメントのオプティミスティック同時実行のセクションをご覧ください）。

上記のコードは、PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID をサービスに送信し、元のエントリを置き換える新しいエントリ（Atom 形式）とほぼ同等です。

アイテムを削除する

更新されたエントリを削除するには、次のコードを使用します。

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

削除に使用する URL は編集 URL と同じであるため、この例は前の URL と非常によく似ていますが、update ではなく delete メソッドを呼び出しています。

上記のコードは、DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID をサービスに送信するのとほぼ同じです。

Reference

クライアント ライブラリで提供されるクラスとメソッドに関するリファレンス情報については、Java クライアント ライブラリ API リファレンス（Javadoc 形式）をご覧ください。

トップへ戻る