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

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

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

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

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

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

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

目次

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

オーディエンス

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

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

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

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

データモデルの概要

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

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

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

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

Google Data API の XML 構文が拡張可能であるのと同様に、対応するオブジェクト モデルも拡張可能です。たとえば、クライアント ライブラリは、Google Data Namespace で定義された要素に対応するクラスを提供します。

チュートリアルと例

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

これらの例では、Google カレンダーという特定のサービスとのやり取りの方法を示しています。カレンダーが他の Google サービスと異なる点も指摘します。これにより、他のサービスで使用できるように例を調整できます。カレンダーの詳細については、Google Calendar Data API のドキュメントをご覧ください。

クライアントをビルドして実行する

このドキュメントのサンプルをコンパイルするには、次のインポート ステートメントを使用する必要があります。

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 クラスの親クラスでもあります。Entry クラスは <atom:entry> 要素を表します。

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

エントリ タイトルは TextConstruct です。これは、さまざまな形式（書式なしテキスト、HTML、XHTML）のテキストを保持するクラスです。エントリのコンテンツは 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);

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

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

EventEntry.class を getEntry のパラメータとして渡すことで、サービスが単なるエントリではなくイベントを返すことを期待していることを示しています。カレンダー以外のサービスでは、代わりに Entry.class を渡すだけでよい場合があります。

上記のコードは、適切な認証を使用して GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID を Calendar に送信することと同等です。

エントリの検索

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

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 メソッドを使用して、クエリをサービスに送信します。

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

アイテムの更新

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

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

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

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

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

アイテムを削除する

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

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

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

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

リファレンス

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

トップへ戻る