参考資料‎ > ‎

.NET Client Library Developer's Guide(日本語訳 原文入り)

たまたま仕事でGoogleカレンダーに登録する仕事が入ったので、以下英語のマニュアルを、エキサイトの翻訳とChromeの翻訳を使って、頑張って翻訳してみた。
コピペプログラマは、もちろん英語もコピペ!ということで、正しい翻訳を期待している方は残念 申し訳ない。
なんとなくわかればいいさって人むけ。


.NETクライアントライブラリ開発者ガイド

This document describes how to use the .NET client library to send Google Data API ("GData") queries and interpret returned responses.

このドキュメントはGoogle Data API("GData")質問を送って、返された応答を解釈するのに.NETクライアントライブラリを使用する方法を説明します。

Google provides a set of client libraries for interacting with GData-enabled services, in a variety of programming languages. Using these libraries, you can construct GData requests, send them to a service, and receive responses.

Googleはさまざまなプログラミング言語でGDataによって可能にされたサービスと対話するための1セットのクライアントライブラリを提供します。 これらのライブラリを使用して、あなたは、GData要求を構成して、それらをサービスに送って、応答を受けることができます。

This document provides a set of examples of common uses of the C# version of the client library, followed by other information about writing GData clients. At the end of this document is a link to the reference documentation for the C# client library, in NDoc format.

このドキュメントはGDataクライアントに書くことの他の情報があとに続いた、クライアントライブラリのC#バージョンの一般的な用途の例のセットを提供します。 このドキュメントの端に、C#クライアントライブラリへの参照ドキュメンテーションへのリンクがあります、NDoc形式で。

To use this client library, you need the .NET 1.1 runtime, and you should also be current on all patches.

このクライアントライブラリを使用するために、.NET 1.1ランタイム を必要とします、また、すべてのパッチのときに、現在になってください。

Download the .NET client library.

This guide's examples refer to the Google Calendar API, but this guide is not an accurate or up-to-date guide to using the Calendar API. For information about using the .NET client library with a specific service's Data API, see the service-specific documentation. For example, if you're working with Calendar, read theCalendar Data API Developer's Guide.

このガイドの例はGoogle Calendar APIについて言及しますが、このガイドはCalendar APIを使用することへの正確であるか最新のガイドではありません。特定のサービスのData APIがある.NETクライアントライブラリを使用することの情報に関しては、サービス特有のドキュメンテーションを見てください。例えば、Calendarと共に働いているなら、Calendar Data API Developer's Guide.を読んでください。

Contents コンテンツ

  1. Audience 対象者
  2. Data model overview データモデル概要
  3. Tutorial and examples チュートリアルと例
  4. Reference 参照

Audience 対象者

This document is intended for C# programmers who want to write client applications that can interact with GData services.

このドキュメントはGDataと対話できるクライアントアプリケーションにサービスを書きたがっているC#プログラマのために意図します。

This document assumes that you understand the general ideas behind the Google Data APIs protocolIt also assumes that you know how to program in C#.

このドキュメントは、あなたがGoogle Data APIs protocolの後ろで概念を理解していると仮定します。また、それは、あなたがC#でプログラムを作る方法を知っていると仮定します。

Data model overview データモデル概要

The C# client library provides a set of classes that correspond to the elements and data types used by the Google Data APIs. For example, there's a Feed class, which corresponds to the <atom:feed> element; it has methods for creating an entry, getting and setting the values of various sub-elements, and so on. There's also an Entry class, which corresponds to the <atom:entry> element. Not every element defined in the Google Data APIs has its own class; for details, see the reference documentation.

C#クライアントライブラリは1セットの要素に対応するクラスとGoogle Data APIによって使用されるデータ型を提供します。例えば、Feedのクラスがあります。(それは、 <atom:feed> 要素に対応します)。 それには、様々な下位要素などの値を得て、設定して、エントリーを作成するためのメソッドがあります。また、Entryのクラスがあります。(それは、 <atom:entry> 要素に対応します)。Google Data APIで定義されたあらゆる要素が、それ自身のクラスを持っているというわけではありません。 詳細に関しては、reference documentationを見てください。

The library can automatically parse Atom content and put the values of the Atom elements into appropriate objects. For example, the getFeed method gets a feed, parses it, and returns a Feed object with the resulting values.

ライブラリは、自動的にAtom内容を分析して、Atom要素の値を適切なオブジェクトに入れることができます。例えば、 getFeed メソッドは、結果として起こる値と共に給送を得て、それを分析して、Feedオブジェクトを返します。

To send a feed or entry to a service, you create a Feed or Entry object, then call a library method (such as the insert method) to automatically translate the object into XML and send it.

あなたは、給送かエントリーをサービスに送るために、FeedかEntryオブジェクトを作成して、次に、自動的にオブジェクトをXMLに翻訳して、それを送るためのライブラリメソッド( insert メソッドなどの)を呼びます。

You can parse and/or generate XML yourself if you prefer; the easiest way to do that is with an appropriate third-party library.

あなたは、よければXML自身を分析する、そして/または、生成することができます。 それをする最も簡単な方法が適切な第三者ライブラリと共にあります。

Just as the Google Data API's XML syntax is extensible, the corresponding object model is extensible. For example, the client library provides classes corresponding to the elements defined in the Google Data namespace.

ちょうどGoogle Data APIのXML構文が広げることができるように、対応するオブジェクトモデルは広げることができます。例えば、クライアントライブラリはGoogle Data namespaceで定義された要素に対応するクラスを供給します。

Tutorial and examples チュートリアルと例

The following examples show how to send various GData requests using the C# client library.

以下の例は、C#クライアントライブラリを使用することでどのように様々なGData要求を送るかを示しています。

To make them more concrete, these examples show how to interact with a specific service: Google Calendar. We'll point out places where Calendar differs from other Google services, to help you adapt these examples for use with other services. For more information about Calendar, see the Google Calendar Data API document.

それらをより具体的にするように、これらの例は、どのように特定のサービス:Googleカレンダー と対話するかを示しています。 私たちはCalendarがあなたが他のサービスで使用のためのこれらの例を適合させるのを助けるために他のGoogleサービスと異なっている場所を指摘するつもりです。Calendarに関する詳しい情報に関しては、Google Calendar Data APIドキュメントを見てください。

Building and running your client あなたのクライアントを構築して、走らせます。

To compile the examples in this document, you'll need to use the following using statement:

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

using Google.GData.Client;

Requesting a feed フィードを要求

As described in the Google Calendar Data API document, you can request a Calendar feed by sending the following HTTP request to Calendar:

Google Calendar Data APIドキュメントで説明されるように、あなたは以下のHTTP要求をCalendarに送ることによって、Calendarフィードを要求できます:

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

Of course, you have to replace userID with the user's email address; see the Calendar document for details. You can, instead, use the special default URL for interacting with Calendar (as described in the Calendar document), but in this document we'll use the private full feed URL, which contains the user ID.

もちろん、あなたは userID をユーザのEメールアドレスに取り替えなければなりません。 詳細のためのCalendarドキュメントを見てください。あなたは、Calendarと対話するのに代わりに特別なデフォルトURLを使用できますが(Calendarドキュメントで説明されるように)、本書では私たちは private full feed URL を使用するつもりです。(それは、ユーザIDを含みます)。

 

You also have to provide appropriate authentication. Note that the authentication system we're using here (known as "Google Authentication for Installed Applications") is appropriate only for use in installed client applications such as desktop clients, not for use in web applications. For more information about authentication, see the Google Account Authentication documentation.

また、あなたは適切な認証を提供しなければなりません。ウェブアプリケーションにおける、使用ではなく、デスクトップクライアントなどのインストールされたクライアントアプリケーションにおける使用だけに、私たちがここ(「インストールされたアプリケーションのためのGoogle認証」として、知られている)で使用している認証システムが適切であることに注意してください。認証に関する詳しい情報に関しては、 Google Account Authentication ドキュメンテーションを見てください。

To request a Calendar feed using the C# client library, for a user with email address "jo@gmail.com" and password "mypassword", use the following code:

ユーザにEメールアドレス" jo@gmail.com "とパスワード"mypassword"でC#クライアントライブラリを使用することでCalendarフィードを要求するには、以下のコードを使用してください:

 

// 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);

The Service class represents a client connection (with authentication) to a GData service. The general procedure for sending a query to a service using the client library consists of the following steps:

  1. Obtain or construct the appropriate URL.
  2. If you're sending data to a service (for example, if you're inserting a new entry), then transform the raw data into objects using the client library classes. (This step doesn't apply if you're just requesting a feed, as we're doing in this example.)
  3. Create a new Service instance, setting the service name (such as "cl" for Calendar) and your application's name (in the formcompanyName-applicationName-versionID).
  4. Set the appropriate credentials.
  5. Call a method to send the request and receive any results.

 

 Service のクラスはクライアント接続(認証がある)のGDataサービスに代理をします。クライアントライブラリを使用することで質問をサービスに送るための基本手順は以下のステップから成ります:

  1. 適切なURLを得るか、または構成してください。
  2. データをサービスに送るなら(あなたが例えば新しいエントリーを挿入しているなら)、クライアントライブラリのクラスを使用することで生データをオブジェクトに変えてください。(あなたがただフィードを要求しているなら、私たちがこの例でしているように、このステップは適用されません。)
  3. サービス名(Calendarのための「Cl」などの)とあなたのアプリケーションの名前を設定して、新しいServiceインスタンスを作成してください。(このフォームで。companyName-applicationName-versionID).
  4. 適切な証明書を設定してください。
  5. リクエストを送信し、任意の結果を受け取るメソッドを呼び出します。

The service.setUserCredentials method sets the service.Credentials property with a standard .NET Network credentials object. The credentials are set to the ID and password of the user on whose behalf your client is sending the query. The examples in this document use the "Authentication for Installed Applications"authentication system; for more information about other authentication systems, see the Google Account Authentication documentation.

 service.setUserCredentials メソッドは標準の.NET Network資格証明書オブジェクトで service.Credentials の特性の用意をします。 資格証明書はあなたのクライアントがだれの代理にクエリーを送るかときのユーザのIDとパスワードへのセットです。 例は本書では「Authentication for Installed Applications」認証システムを使用します。 他の認証システムに関する詳しい情報に関しては、Google Account Authentication ドキュメンテーションを見てください。

To request an entire feed, you call the service.Query method, which takes a FeedQuery object and returns the entire feed found at that URL. We'll show how to send more specific queries later in this document.

全体のフィードを要求するために、あなたは service.Query メソッドを呼びます。(それは、 FeedQuery オブジェクトを取って、そのURLで見つけられた全体の給送を返します)。私たちは、後でどのように本書ではより特定のクエリーを送るかを示すつもりです。

Like other methods of the Service class, Query handles authentication and redirects as necessary.

 Service のクラスの他のメソッドのように、 Query は認証を扱って、必要に応じて向け直します。

Inserting a new item 新しい項目を挿入する

To insert an item into a Calendar feed, you might use the following code:

カレンダーフィードにアイテムを挿入するには、次のコードを使用する場合があります:

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);

After setting the URL, we construct an AtomEntry object.

URLを設定した後に、私たちは、 AtomEntry オブジェクトを組み立てます。

The entry title is a AtomTextConstructa class that holds text in various forms (plain text, HTML, or XHTML). The entry content is represented by an AtomContentobject, a class that can hold either plain text or other forms of content, including XML and binary data.

エントリータイトルは、 AtomTextConstruct、様々なフォーム(プレーンテキスト、HTML、またはXHTML)でテキストをつかむクラスです。エントリー内容は AtomContentオブジェクトによって表されます、プレーンテキストかフォームのどちらかの、他の中身を保持できるクラス、XMLとバイナリ・データを含んでいます。

Each author is represented as a name, a URI, and an email address. (In this example, we're leaving out the URI.) You add an author to an entry by adding anAtomAuthor object to the entry's Authors collection.

各作者は名前、URI、およびEメールアドレスとして代理をされます。 (この例では、私たちはURIを省いています。)  あなたは、エントリーの Authors 収集に AtomAuthor オブジェクトを追加することによって、エントリーに作者を加えます。

We're using the same Service object that we created in the previous example. In this case, the method to call is Insert, which sends an item to the specified insertion URL.

私たちは私たちが前の例で作成したのと同じ Service オブジェクトを使用しています。この場合、呼ぶためのメソッドは Insertです。(そのInsertは指定された挿入URLにアイテム を送ります)。

The service returns the newly created entry, which may contain additional server-generated elements, such as an edit URL for the entry.

サービスは新たに作成されたエントリーを返します、エントリーへの編集URLのように。(エントリーは追加サーバで発生している要素を含むかもしれません)。

The above code is equivalent to sending POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (with proper authentication) and providing an entry.

上のコードは POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (適切な認証がある)を送って、エントリーを提供するのに同等です。

Requesting a specific entry 特定のエントリーを要求します。

The following code lets you request the specific entry that you inserted in the previous example.

以下のコードで、あなたは前の例に挿入した特定のエントリーを要求できます。

In the context of this series of examples, retrieving that entry isn't really necessary, because Calendar already returned the inserted entry; but the same technique can be applied whenever you know the URL for an entry.

このシリーズの例の文脈では、そのエントリーを検索するのは本当に必要ではありません、Calendarが既に挿入されたエントリーを返したので。 しかし、あなたがURLをエントリーに知っているときはいつも、同じテクニックを適用できます。

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

The inserted entry has a property, SelfUri, that returns an AtomUri object that, using its ToString() method, can be used to create a new URI object.

挿入されたエントリーには、特性、 ToString() メソッドを使用して、新しいURIオブジェクトを作成するのに使用できる AtomUri オブジェクトを返す SelfUri があります。

Then we just have to call the service's Query method to get a new AtomFeed object, with just one entry in its Entries collection.

次に、私たちはただ新しいAtomFeedオブジェクトを手に入れるためのサービスの Query メソッドを呼ばなければなりません、Entries収集におけるちょうど1つのエントリーで。

The above code is equivalent to sending GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID to Calendar, with proper authentication.

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

Searching for an entry エントリの検索

To retrieve the first match in a full-text search, use the following code:

フルテキスト検索で最初に一致したものを取得するには、次のコードを使用します:

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; 
}

This example starts by constructing a FeedQuery object, which consists mostly of a URL plus associated query parameters. Each of the standard GData query parameters has a property.

この例は、 FeedQuery オブジェクトを組み立てることによって、始まります。(オブジェクトはほとんどURLと関連質問パラメータから成ります)。それぞれの標準のGData クエリーパラメータに、特性があります。

After constructing the FeedQuery, we pass it to the service's Query method, which returns a feed containing the query results. An alternative approach would be to construct a URL yourself (by appending query parameters to the feed URL) and then call the Query method, but the FeedQuery method provides a useful layer of abstraction so that you don't have to construct the URL yourself.

 FeedQuery を組み立てた後に、私たちは、サービスの Query 方法にそれを通過します。(それは、クエリー結果を含むフィードを返します)。 代替的アプローチが自分でURLを構成して(フィードURLにクエリーパラメータを追加することによって)、次に、 Query 方法を呼ぶだろうことですが、 FeedQuery 方法が役に立つ層の抽象化を提供するので、あなたは自分でURLを構成する必要はありません。

The feed's Entries collection returns a list of the entries in the feed; Entries.Count returns the number of entries in the feed.

フィードの Entries 収集は給送におけるエントリーのリストを返します。 Entries.Count はフィードにおける、エントリーの数を返します。

In this case, if the query returned any results, we assign the first matching result to an AtomEntry object. Then we use the AtomEntry class's Title property to retrieve the entry's title.

この場合、クエリーが何か結果を返したなら、私たちは、最初の合う結果を AtomEntry オブジェクトに割り当てます。そして、私たちは、エントリーのタイトルを検索するのに AtomEntry のクラスの Title プロパティを使用します。

The above code is equivalent to sending GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis to Calendar.

上のコードは GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis をCalendarに送るのに同等です。

Querying by category カテゴリ別の照会

Note: Google Calendar doesn't associate labels with events, so this example doesn't work with Calendar.

Note: Google Calendarがラベルをイベントに関連づけないので、この例はCalendarで動作しません。

To retrieve a feed consisting of all the entries that match the earlier full-text search and that are in a particular category or have a particular label, use the following code:

以前の全文検索に合って、特定のカテゴリにあるすべてのエントリーから成るフィードを検索するか、または特定のラベルを持つには、以下のコードを使用してください:

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

The AtomCategory class, of course, represents a category to be used in a category filter. The QueryCategory class can contain multiple categories, but in this case we're constructing a filter with only one category.

 AtomCategory のクラスは、カテゴリフィルタで使用されるためにもちろんカテゴリを表します。 QueryCategory のクラスは複数のカテゴリを含むことができますが、この場合、私たちは、1つのカテゴリだけがあるフィルタを組み立てています。

Then we add that filter to the existing query, which still contains the full-text query string from the previous example.

そして、私たちは既存のクエリーにそのフィルタを加えます。(まだ、それは、前の例からの全文クエリーストリングを含んでいます)。

We again use the Query method to send the query to the service.

私たちは再び質問をサービスに送るためのQueryメソッドを使用します。

If Calendar allowed a category search, the above code would be equivalent to sending GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis to Calendar.

Calendarがカテゴリ検索を許すなら、上のコードは GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis をCalendarに送るのに同等でしょう。



 

Updating an item アイテムを更新

To update an existing item, use the following code. In the following example, we're changing the previously retrieved entry's title from its old text ("Tennis with Beth") to "Important meeting."

既存の項目をアップデートするには、以下のコードを使用してください。 以下の例では、私たちは以前に検索されたエントリーのタイトルを古いテキスト(「ベスがいるテニス」)から「重要なミーティング」に変えています。

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

First we set a new title for the entry we fetched earlier. Then we just call the Upate method to send the updated entry to the service.

まず最初に、私たちは、私たちが、より早くとって来たエントリーのための新しいタイトルを設定します。 そして、私たちは、 Upate をただアップデートされたエントリーをサービスに送るためのメソッドと呼びます。

The service returns the updated entry, including a new URL for this entry's new version. (For more information on entry versions, see the Optimistic concurrencysection of the protocol reference document.)

サービスはアップデートされたエントリーを返します、このエントリーの新しいバージョンのための新しいURLを含んでいます。(エントリーバージョンの詳しい情報に関して、protocol reference document の Optimistic concurrency 部を見てください)

The above code is roughly equivalent to sending PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID to the service, along with the new entry (in Atom format) to replace the original entry.

上のコードはおよそ元のエントリーを取り替えるために新しいエントリー(Atomフォーマットにおける)と共に  PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID  をサービスに送るのに同等です。

Deleting an item アイテムを削除する

To delete an existing item, use the following code:

既存の項目を削除するには、以下のコードを使用してください:

updateEntry.Delete();

The URL to use for deletion is the same as the edit URL, so this example is very similar to the previous one, except of course that we're calling the Delete method instead of Update.

削除に使用するURLは編集URLと同じです、したがって、この例が前のものと非常に同様です、もちろんそれを除いて、私たちが Update の代わりに Delete メソッドを呼んでいます。

The above code is roughly equivalent to sending DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID to the service.

上のコードはおよそ DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID をサービスに送るのに同等です。

Working with Google Calendar feeds Googleカレンダーを操作するフィード

The above examples outline how to use the Google Data C# API to work with generic GData feeds. When you're working with a Google Calendar feed in particular, though, the feed contains a lot of calendar-specific data that is not easily accessible using the standard Atom-oriented objects in the base API library. To help you interact with those feeds, we provide the following extensions:

上記の例はジェネリックGDataフィードで働くのにどうGoogle Data C#APIを使用するかを概説します。 もっとも、あなたが特にGoogle Calendarフィードで働いているとき、フィードは、ベースAPI図書館で標準のAtom指向のオブジェクトを使用するのにおいて容易にアクセス可能でない多くのカレンダー特有のデータを含んでいます。 あなたがそれらのフィードと対話するのを助けるために、私たちは以下の拡大を提供します:

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

The Extensions namespace deals with extensions in general; the Calendar namespace gives you access to a customized calendar service, feed and query object. You can find a more elaborate example of how those extensions are used in the /Samples subdirectory of the C# API installation. The following objects are added:

Extensions名前空間は一般に、拡大に対処します。 Calendar名前空間は特製カレンダーサービス、フィード、およびクエリーオブジェクトへのアクセスをあなたに与えます。あなたはそれらの拡張子がC#APIインストールに関する/サンプルサブディレクトリでどう使用されるかの、より入念な例を見つけることができます。 以下のオブジェクトは加えられます:

EventQuery
A subclass of FeedQuery, which allows you to set two custom parameters for the Calendar service (start-min and start-max).
あなたは、Calendarサービスの2つのカスタムパラメータを(開始分およびstart - max)に設定することができますFeedQueryのサブクラスです。
CalendarService
A subclass of service, which can return an event feed.
イベントフィードを返すことができるサービスのサブクラス。
EventFeed
A subclass of AtomFeed, exposing EventEntries.
AtomFeedのサブクラスは、eventEntriesにを露出させる。
EventEntry
A subclass of AtomEntry, which has additional properties related to calendar data.
追加のプロパティをカレンダーデータに関連したAtomEntryのサブクラスです。

For more details about those special classes, see the API documentation and the samples program.

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

Comments