.NET クライアント ライブラリ デベロッパー ガイド

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

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

このドキュメントでは、クライアント ライブラリの C# バージョンの一般的な使用例をいくつか紹介し、その後、GData クライアントの作成に関するその他の情報を提供します。このドキュメントの末尾に、NDoc 形式の C# クライアント ライブラリのリファレンス ドキュメントへのリンクがあります。

このクライアント ライブラリを使用するには、.NET 1.1 ランタイムが必要です。また、すべてのパッチを最新の状態にする必要があります。

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

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

目次

  1. 対象
  2. データモデルの概要
  3. チュートリアルと例
  4. リファレンス

オーディエンス

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

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

データモデルの概要

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

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

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

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

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

チュートリアルと例

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

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

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

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

using Google.GData.Client;

フィードをリクエストする

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

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

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

適切な認証情報も指定する必要があります。ここで使用している認証システム（「インストール済みアプリケーションの Google 認証」）は、ウェブ アプリケーションではなく、デスクトップ クライアントなどのインストール済みクライアント アプリケーションでの使用にのみ適しています。認証の詳細については、Google アカウントの認証に関するドキュメントをご覧ください。

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

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

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

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

service.setUserCredentials メソッドは、標準の .NET ネットワーク認証情報オブジェクトを使用して service.Credentials プロパティを設定します。認証情報は、クライアントがクエリを送信するユーザーの ID とパスワードに設定されます。このドキュメントの例では、「インストール済みアプリケーションの認証」認証システムを使用しています。他の認証システムについて詳しくは、Google アカウント認証のドキュメントをご覧ください。

フィード全体をリクエストするには、service.Query メソッドを呼び出します。このメソッドは FeedQuery オブジェクトを受け取り、その URL にあるフィード全体を返します。より具体的なクエリを送信する方法については、このドキュメントの後半で説明します。

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

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

カレンダー フィードにアイテムを挿入するには、次のコードを使用します。

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

URL を設定したら、AtomEntry オブジェクトを作成します。

エントリ タイトルは AtomTextConstruct です。これは、さまざまな形式（書式なしテキスト、HTML、XHTML）のテキストを保持するクラスです。エントリのコンテンツは AtomContent オブジェクトで表されます。このクラスは、書式なしテキストや、XML やバイナリデータなどの他の形式のコンテンツを保持できます。

各著者は、名前、URI、メールアドレスで表されます。（この例では、URI を省略しています）。エントリに作成者を追加するには、エントリの Authors コレクションに AtomAuthor オブジェクトを追加します。

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

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

上記のコードは、POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full（適切な認証あり）を送信してエントリを提供するのと同等です。

特定のエントリをリクエストする

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

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

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

挿入されたエントリには、SelfUri というプロパティがあります。このプロパティは AtomUri オブジェクトを返します。このオブジェクトは、ToString() メソッドを使用して新しい URI オブジェクトを作成するために使用できます。

次に、サービスの Query メソッドを呼び出して、Entries コレクションに 1 つのエントリのみを含む新しい AtomFeed オブジェクトを取得します。

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

エントリを検索する

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

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

この例では、まず FeedQuery オブジェクトを作成します。このオブジェクトは、主に URL と関連するクエリ パラメータで構成されています。標準の GData クエリ パラメータにはそれぞれプロパティがあります。

FeedQuery を構築したら、サービスの Query メソッドに渡します。このメソッドは、クエリ結果を含むフィードを返します。別の方法として、自分で URL を作成（フィード URL にクエリ パラメータを追加）してから Query メソッドを呼び出すこともできますが、FeedQuery メソッドは便利な抽象化レイヤを提供するため、自分で URL を作成する必要はありません。

フィードの Entries コレクションはフィード内のエントリのリストを返し、Entries.Count はフィード内のエントリの数を返します。

この場合、クエリが結果を返した場合は、最初に一致した結果を AtomEntry オブジェクトに割り当てます。次に、AtomEntry クラスの Title プロパティを使用して、エントリのタイトルを取得します。

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

カテゴリでクエリを実行する

注: Google カレンダーではラベルとイベントが関連付けられていないため、この例はカレンダーでは機能しません。

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

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

もちろん、AtomCategory クラスはカテゴリ フィルタで使用されるカテゴリを表します。QueryCategory クラスには複数のカテゴリを含めることができますが、ここでは 1 つのカテゴリのみを含むフィルタを作成します。

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

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

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

アイテムの更新

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

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

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

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

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

アイテムを削除する

既存のアイテムを削除するには、次のコードを使用します。

updateEntry.Delete();

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

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

Google カレンダー フィードの操作

上記の例では、Google Data C# API を使用して一般的な GData フィードを操作する方法の概要を示しています。ただし、特に Google カレンダー フィードを扱う場合、フィードには、基本 API ライブラリの標準の Atom 志向オブジェクトを使用して簡単にアクセスできないカレンダー固有のデータが多数含まれています。これらのフィードを操作するために、次の拡張機能が用意されています。

using Google.GData.Extensions;
using Google.GData.Calendar;

Extensions 名前空間は拡張機能全般を扱い、Calendar 名前空間はカスタマイズされたカレンダー サービス、フィード、クエリ オブジェクトへのアクセスを提供します。これらの拡張機能の使用方法のより詳細な例については、C# API インストールの /Samples サブディレクトリをご覧ください。次のオブジェクトが追加されます。

EventQuery
FeedQuery のサブクラス。カレンダー サービスに 2 つのカスタム パラメータ（start-min と start-max）を設定できます。
CalendarService
イベント フィードを返すことができるサービスのサブクラス。
EventFeed
AtomFeed のサブクラスで、EventEntry を公開します。
EventEntry
AtomEntry のサブクラス。カレンダー データに関連する追加のプロパティがあります。

これらの特別なクラスの詳細については、API ドキュメントとサンプル プログラムをご覧ください。

リファレンス

C# クライアント ライブラリのリファレンス情報については、リファレンス ドキュメントをご覧ください。

トップへ戻る