.NET 客户端库开发者指南

本文档介绍了如何使用 .NET 客户端库发送 Google Data API ("GData") 查询并解读返回的响应。

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

本文档提供了一组有关如何使用 C# 版客户端库的常见示例，随后还介绍了有关编写 GData 客户端的其他信息。本文档末尾提供了一个链接，指向采用 NDoc 格式的 C# 客户端库参考文档。

如需使用此客户端库，您需要 .NET 1.1 运行时，并且还应及时安装所有补丁。

下载 .NET 客户端库。

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

目录

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

受众群体

本文档面向希望编写可与 GData 服务互动的客户端应用的 C# 程序员。

本文档假定您了解 Google Data API 协议背后的总体思路。本文还假定您了解如何使用 C# 进行编程。

数据模型概览

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

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

如需向服务发送 Feed 或条目，您可以创建一个 Feed 或 Entry 对象，然后调用库方法（例如 insert 方法）自动将该对象转换为 XML 并发送。

如果您愿意，可以自行解析和/或生成 XML；最简单的方法是使用合适的第三方库。

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

教程和示例

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

为了使这些示例更具体，我们展示了如何与特定服务（即 Google 日历）互动。我们会指出日历与其他 Google 服务之间的不同之处，以便您根据需要调整这些示例，以用于其他服务。如需详细了解日历，请参阅 Google Calendar Data API 文档。

构建并运行客户端

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

using Google.GData.Client;

请求 Feed

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

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

当然，您必须将 userID 替换为用户的电子邮件地址；有关详情，请参阅日历文档。您也可以使用用于与日历互动的特殊默认网址（如日历文档中所述），但本文档将使用包含用户 ID 的不公开完整 Feed 网址。

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

如需使用 C# 客户端库为电子邮件地址为“jo@gmail.com”且密码为“mypassword”的用户请求日历 Feed，请使用以下代码：

// 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 对象，该对象的 Entries 集合中只有一个条目。

上述代码相当于向日历发送 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 方法将查询发送到服务。

如果日历允许类别搜索，则上述代码相当于向日历发送 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 子目录中找到有关如何使用这些扩展程序的更详细示例。添加了以下对象：

EventQuery
FeedQuery 的一个子类，可用于为 Calendar 服务设置两个自定义参数（start-min 和 start-max）。
CalendarService
一种可以返回活动 Feed 的服务子类。
EventFeed
AtomFeed 的子类，用于公开 EventEntry。
EventEntry
AtomEntry 的子类，具有与日历数据相关的其他属性。

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

参考

如需查看 C# 客户端库的相关参考信息，请参阅参考文档。

返回页首