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

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

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

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

このドキュメントでは、C# バージョンのクライアントライブラリの一般的な使用例と、GData クライアントの作成に関する追加情報について説明します。このドキュメントの末尾には、C# クライアントライブラリのリファレンスドキュメントへのリンクが NDoc 形式で記載されています。

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

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

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

対象者

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

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

データモデルの概要

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

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

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

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

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

チュートリアルと例

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

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

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

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

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

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

service.setUserCredentials メソッドは、標準の .NET ネットワーク認証情報オブジェクトで service.Credentials プロパティを設定します。認証情報は、クライアントがクエリを送信するユーザーの ID とパスワードに設定されます。このドキュメントの例では、"Installed Applications for Authentication" 認証システムを使用しています。他の認証システムについて詳しくは、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 オブジェクトを作成します。

エントリのタイトルは、さまざまな形式（書式なしテキスト、HTML、XHTML）でテキストを保持するクラスです。AtomTextConstructエントリの内容は 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 メソッドを呼び出して、エントリコレクションに 1 つのエントリのみを持つ新しい AtomFeed オブジェクトを取得するだけです。

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

エントリの検索

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

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

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

アイテムを更新する

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

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

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

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

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

アイテムを削除する

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

updateEntry.Delete();

削除に使用する URL は編集 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;

拡張機能の名前空間では、一般的に拡張機能が扱われ、カレンダーの名前空間を使用すると、カスタマイズされたカレンダーサービス、フィード、クエリオブジェクトにアクセスできます。これらの拡張機能の使用例は、C# API インストールの /Samples サブディレクトリで詳しく説明されています。次のオブジェクトが追加されます。

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

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

Reference

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

トップへ戻る

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

目次

対象者