.NET 客户端库开发者指南

本文档介绍了如何使用 .NET 客户端库发送 Google Data API（“GData”）查询以及解读返回的响应。

Google 提供了一组客户端库，用于与使用各种编程语言的启用了 GData 的服务进行交互。使用这些库，您可以构建 GData 请求，将其发送到服务并接收响应。

本文档提供了一组有关 C# 版客户端库的常见用途，以及有关编写 GData 客户端的其他信息。本文档末尾提供了 C# 客户端库参考文档的链接，采用 NDoc 格式。

如需使用此客户端库，您需要 .NET 1.1 运行时，并且所有补丁程序都应是最新版本。

下载 .NET 客户端库。

本指南中的示例引用的是 Google Calendar API，但本指南的内容并不是有关使用 Calendar API 的准确或最新的指南。如需了解如何将 .NET 客户端库与特定服务的数据 API 配合使用，请参阅服务特定文档。例如，如果您使用的是 Google 日历，请参阅 Calendar Data API 开发者指南。

目录

  1. 观众群
  2. 数据模型概览
  3. 教程和示例
  4. 参考文档

观众

本文档适用于想要编写可与 GData 服务进行交互的客户端应用的 C# 程序员。

本文假定您了解 Google Data API 协议的一般概念。本文档还假定您知道如何使用 C# 进行编程。

数据模型概览

C# 客户端库提供了一组与 Google Data API 使用的元素和数据类型相对应的类。例如，有一个 Feed 类，它对应于 <atom:feed> 元素；它有用于创建条目、获取和设置各种子元素值等的方法。此外，还有一个与 <atom:entry> 元素对应的 Entry 类。并非 Google Data API 中定义的每个元素都有自己的类；如需了解详情，请参阅参考文档。

该库可自动解析 Atom 内容，并将 Atom 元素的值放入相应的对象中。例如，getFeed 方法会获取 Feed，对其进行解析，并返回包含所生成值的 Feed 对象。

要向服务发送 Feed 或条目，请创建 Feed 或条目对象，然后调用库方法（例如 insert 方法），自动将对象转换为 XML 并发送。

您可以根据需要自行解析和/或生成 XML；最简单的方法是使用相应的第三方库。

就像 Google Data API 的 XML 语法一样可扩展，对应的对象模型也是可扩展的。例如，客户端库提供与 Google 数据命名空间中定义的元素相对应的类。

教程和示例

以下示例展示了如何使用 C# 客户端库发送各种 GData 请求。

为了让用户更有针对性，这些示例展示了如何与 Google 日历的特定服务交互。我们会指出 Google 日历与其他 Google 服务的不同之处，以帮助您调整这些示例，以便在其他服务中使用。要详细了解 Google 日历，请参阅 Google Calendar Data API 文档。

构建并运行客户端

如需编译本文档中的示例，您需要使用以下 using 语句：

using Google.GData.Client;

请求 Feed

如 Google Calendar Data API 文档中所述，您可以通过将以下 HTTP 请求发送到日历来请求日历 Feed：

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

当然，您必须将 userID 替换为用户的电子邮件地址；如需了解详情，请参阅 Google 日历文档。您可以改用特殊的默认网址与日历互动（如日历文档中所述），但在此文档中，我们将使用包含用户 ID 的完整私人 Feed 网址。

您还必须提供适当的身份验证。请注意，我们在此处使用的身份验证系统（称为“安装式 Google 身份验证”）仅适用于安装式客户端应用（如桌面客户端），不适用于 Web 应用。如需详细了解身份验证，请参阅 Google 帐号身份验证文档。

要使用 C# 客户端库请求日历 Feed，对于电子邮件地址为“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. 获取或构造适当的网址。
  2. 如果要向服务发送数据（例如，如果您要插入新的条目），则使用客户端库类将原始数据转换为对象。（如果您在此示例中请求了 Feed，则此步骤不适用。）
  3. 创建一个新的 Service 实例，设置服务名称（例如日历的 "cl"）和应用的名称（格式为 companyName-applicationName-versionID）。
  4. 设置适当的凭据。
  5. 调用方法以发送请求并接收任何结果。

service.setUserCredentials 方法使用标准的 .NET 网络凭据对象设置 service.Credentials 属性。凭据会设置为您的客户端代表其发送查询的用户的 ID 和密码。本文档中的示例使用“已安装应用的身份验证”身份验证系统；有关其他身份验证系统的详细信息，请参阅 Google 帐号身份验证文档。

如需请求整个 Feed，您可以调用 service.Query 方法，该方法会接受 FeedQuery 对象并返回在该网址上找到的整个 Feed。我们将在本文档的后面部分介绍如何发送更具体的查询。

与 Service 类的其他方法一样，Query 会根据需要处理身份验证和重定向。

插入新项

要在日历 Feed 中插入项，您可以使用以下代码：

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

设置网址后，我们会构建一个 AtomEntry 对象。

条目标题是一个 AtomTextConstruct，这是一个包含各种格式（纯文本、HTML 或 XHTML）的文本的类。条目内容由 AtomContent 对象表示，该类可容纳纯文本或其他形式的内容，包括 XML 和二进制数据。

每个作者都以姓名、URI 和电子邮件地址表示。（在此示例中，我们省略了 URI）。您可以向条目的 Authors 集合添加 AtomAuthor 对象，从而为条目添加作者。

我们使用的是之前示例中创建的 Service 对象。在本例中，调用的方法是 Insert，这会将一个项发送到指定的插入网址。

该服务会返回新创建的条目，其中可能包含服务器生成的其他元素，如该条目的修改网址。

上面的代码等同于发送 POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full（使用正确的身份验证）并提供条目。

请求特定条目

通过以下代码，您可以请求在上一个示例中插入的特定条目。

在本系列示例中，由于条目已返回所插入的条目，因此不必检索该条目；但只要您知道该条目的网址，就可以使用相同的方法。

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 方法来获取一个新的 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 对象，该对象主要由网址以及关联的查询参数组成。每个标准 GData 查询参数都有一个属性。

构建 FeedQuery 后，我们会将其传递给服务的 Query 方法，该方法会返回包含查询结果的 Feed。另一种方法是自行构造网址（通过将查询参数附加到 Feed 网址），然后调用 Query 方法，但 FeedQuery 方法可提供实用的抽象层，因此您无需自行构建网址。

Feed 的 Entries 集合会返回 Feed 中的条目列表；Entries.Count 会返回 Feed 中的条目数。

在本例中，如果查询返回任何结果，我们会将第一个匹配结果分配给 AtomEntry 对象。然后，我们使用 AtomEntry 类的 Title 属性来检索条目的标题。

上面的代码相当于将 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis 发送到日历。

按类别查询

注意：Google 日历不会将标签与活动关联，因此此示例不适用于 Google 日历。

要检索的 Feed 包括与之前的全文搜索相匹配的所有条目、属于特定类别或具有特定标签的条目，请使用以下代码：

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

当然，AtomCategory 类表示要在类别过滤器中使用的类别。QueryCategory 类可以包含多个类别，但在本例中，我们构造的过滤器只有一个类别。

然后，我们将该过滤器添加到现有查询，该查询仍然包含上一个示例中的全文查询字符串。

我们再次使用 Query 方法将查询发送到服务。

如果 Google 日历允许类别搜索，上述代码等同于向 Google 日历发送 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis。

更新商品

如需更新现有项，请使用以下代码。在以下示例中，我们将之前检索到的条目的标题从旧文本（“带白晶石的网球”）更改为“重要会议”。

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

首先，我们为之前提取的条目设置新标题。然后，我们只需调用 Upate 方法，即可向服务发送更新后的条目。

该服务会返回更新后的条目，包括该条目新版本的新网址。（如需详细了解条目版本，请参阅 v1 协议参考文档的乐观并发部分。）

上面的代码大致等同于向服务发送 PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID，以及新条目（Atom 格式）来替换原始条目。

删除商品

如需删除现有项，请使用以下代码：

updateEntry.Delete();

要删除的网址与修改网址相同，因此此示例与上一个示例非常相似，只不过我们调用的是 Delete 方法，而不是 Update。

上面的代码大致相当于将 DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID 发送到服务。

使用 Google 日历 Feed

以上示例概述了如何使用 Google Data C# API 处理通用 GData Feed。特别是在使用 Google 日历 Feed 时，该 Feed 包含大量日历特定数据，而使用基本 API 库中面向 Atom 的标准对象难以访问这些数据。为了帮助您与这些 Feed 互动，我们提供了以下扩展程序：

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

扩展程序命名空间通常处理扩展程序；通过日历命名空间，您可以访问自定义日历服务、Feed 和查询对象。您可以在 C# API 安装的 /Samples 子目录中找到更详细的示例，了解如何使用这些扩展程序。添加了以下对象：

事件查询
FeedQuery 的一个子类，可让您为日历服务设置两个自定义参数（start-min 和 start-max）。
日历服务
服务的子类，可以返回事件 Feed。
事件 Feed
公开 EventEntry 的 AtomFeed 的子类。
EventEntry
AtomEntry 的子类，具有与日历数据相关的其他属性。

如需详细了解这些特殊类，请参阅 API 文档和示例程序。

参考

如需了解 C# 客户端库的参考信息，请参阅参考文档。

返回页首