本頁面由 Cloud Translation API 翻譯而成。

.NET 用戶端程式庫開發人員指南

本文說明如何使用 .NET 用戶端程式庫傳送 Google Data API (簡稱「GData」) 查詢，以及解讀傳回的回應。

Google 提供一系列用戶端程式庫，可讓您以各種程式設計語言與啟用 GData 的服務互動。您可以使用這些程式庫建構 GData 要求、傳送至服務，並接收回應。

本文提供一系列範例，說明如何使用 C# 版用戶端程式庫，並提供撰寫 GData 用戶端的其他資訊。本文結尾提供 C# 用戶端程式庫的參考文件連結 (NDoc 格式)。

如要使用這個用戶端程式庫，您需要 .NET 1.1 執行階段，且所有修補程式都應為最新版本。

本指南的範例是指 Google Calendar API，但本指南並非使用 Calendar API 的正確或最新指南。如要瞭解如何搭配特定服務的 Data API 使用 .NET 用戶端程式庫，請參閱該服務的說明文件。舉例來說，如果您使用 Google 日曆，請參閱「Google 日曆資料 API 開發人員指南」。

觀眾

本文適用於想要編寫用戶端應用程式，與 GData 服務互動的 C# 程式設計師。

本文假設您瞭解 Google Data APIs 通訊協定背後的一般概念。此外，本課程也假設您瞭解如何使用 C# 程式設計。

資料模型總覽

C# 用戶端程式庫提供一組類別，對應 Google Data API 使用的元素和資料型別。舉例來說，Feed 類別對應於 <atom:feed> 元素，其中包含建立項目、取得及設定各種子元素值等方法。此外，還有對應 <atom:entry> 元素的 Entry 類別。Google Data API 中定義的每個元素不一定都有自己的類別，詳情請參閱參考說明文件。

這個程式庫可以自動剖析 Atom 內容，並將 Atom 元素的值放入適當的物件。舉例來說，getFeed 方法會取得動態饋給、剖析動態饋給，並傳回含有結果值的 Feed 物件。

如要將動態消息或項目傳送至服務，請建立 Feed 或 Entry 物件，然後呼叫程式庫方法 (例如 insert 方法)，自動將物件轉換為 XML 並傳送。

您也可以自行剖析及/或產生 XML，最簡單的方法是使用適當的第三方程式庫。

如同 Google Data API 的 XML 語法可擴充，對應的物件模型也可擴充。舉例來說，用戶端程式庫會提供與 Google Data 命名空間中定義的元素對應的類別。

教學課程和範例

以下範例說明如何使用 C# 用戶端程式庫傳送各種 GData 要求。

為使這些範例更具體，我們將說明如何與特定服務 (Google 日曆) 互動。我們會指出 Google 日曆與其他 Google 服務的不同之處，協助您調整這些範例，以便用於其他服務。如要進一步瞭解 Google 日曆，請參閱 Google Calendar Data API 說明文件。

建構及執行用戶端

如要編譯本文中的範例，請使用下列 using 陳述式：

using Google.GData.Client;

要求動態消息

如 Google Calendar Data API 說明文件所述，您可以將下列 HTTP 要求傳送至 Google 日曆，要求日曆動態消息：

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

當然，您必須將 userID 替換成使用者的電子郵件地址；詳情請參閱 Google 日曆文件。您可以改用與 Google 日曆互動的特殊預設網址 (如 Google 日曆文件所述)，但本文將使用包含使用者 ID 的私人完整動態饋給網址。

您也必須提供適當的驗證資訊。請注意，我們在此使用的驗證系統 (稱為「已安裝應用程式的 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 服務的連線 (含驗證)。使用用戶端程式庫將查詢傳送至服務的一般程序包含下列步驟：

取得或建構適當的網址。
如果您要將資料傳送至服務 (例如插入新項目)，請使用用戶端程式庫類別將原始資料轉換為物件。(如果您只是要求動態饋給，則不適用這個步驟，如本例所示)。
建立新的 Service 執行個體，設定服務名稱 (例如日曆的 "cl") 和應用程式名稱 (格式為 companyName-applicationName-versionID)。
設定適當的憑證。
呼叫方法來傳送要求並接收任何結果。

service.setUserCredentials 方法會使用標準 .NET 網路憑證物件設定 service.Credentials 屬性。憑證會設為使用者 ID 和密碼，您的用戶端會代表該使用者傳送查詢。本文範例使用「已安裝應用程式的驗證」驗證系統；如要進一步瞭解其他驗證系統，請參閱「Google 帳戶驗證」說明文件。

如要要求整個動態消息，請呼叫 service.Query 方法，該方法會採用 FeedQuery 物件，並傳回該網址中找到的整個動態消息。本文稍後會說明如何傳送更具體的查詢。

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

設定網址後，我們會建構 AtomEntry 物件。

項目標題是 AtomTextConstruct，這個類別會以各種形式 (純文字、HTML 或 XHTML) 保存文字。項目內容以 AtomContent 物件表示，這個類別可保留純文字或其他形式的內容，包括 XML 和二進位資料。

每位作者都會以名稱、URI 和電子郵件地址表示。(在本範例中，我們省略了 URI)。如要為項目新增作者，請將 AtomAuthor 物件新增至項目的 Authors 集合。

我們使用在上一個範例中建立的相同 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 傳送至 Google 日曆，並完成適當的驗證。

搜尋項目

如要擷取全文搜尋中的第一個相符項目，請使用下列程式碼：

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 方法，該方法會傳回含有查詢結果的動態消息。另一種做法是自行建構網址 (將查詢參數附加至動態饋給網址)，然後呼叫 Query 方法，但 FeedQuery 方法提供實用的抽象層，因此您不必自行建構網址。

動態饋給的 Entries 集合會傳回動態饋給中的項目清單；Entries.Count 則會傳回動態饋給中的項目數量。

在本例中，如果查詢傳回任何結果，我們會將第一個相符結果指派給 AtomEntry 物件。接著，我們使用 AtomEntry 類別的 Title 屬性擷取項目的標題。

上述程式碼等同於將 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis 傳送至 Google 日曆。

依類別查詢

注意：Google 日曆不會將標籤與活動建立關聯，因此這個範例不適用於日曆。

如要擷取動態消息，其中包含與先前全文搜尋相符的所有項目，且這些項目屬於特定類別或具有特定標籤，請使用下列程式碼：

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 傳送至日曆。

更新項目

如要更新現有項目，請使用下列程式碼。在下列範例中，我們將先前擷取的項目標題從舊文字「Tennis with Beth」變更為「Important meeting」。

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 日曆動態消息

上述範例說明如何使用 Google Data C# API 處理一般 GData 動態消息。不過，如果您要處理 Google 日曆動態消息，動態消息會包含許多日曆專屬資料，這些資料無法透過基本 API 程式庫中的標準 Atom 導向物件輕鬆存取。為協助您與這些動態消息互動，我們提供下列擴充功能：

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

擴充功能命名空間處理一般擴充功能；日曆命名空間則可讓您存取自訂日曆服務、動態饋給和查詢物件。如要查看這些擴充功能的詳細使用範例，請前往 C# API 安裝目錄的 /Samples 子目錄。系統會新增下列物件：

EventQuery: FeedQuery 的子類別，可讓您為 Calendar 服務設定兩個自訂參數 (start-min 和 start-max)。
CalendarService: 服務的子類別，可傳回事件動態消息。
EventFeed: AtomFeed 的子類別，會公開 EventEntry。
EventEntry: AtomEntry 的子類別，具有與日曆資料相關的其他屬性。

如要進一步瞭解這些特殊類別，請參閱 API 說明文件和範例程式。

參考資料

如需 C# 用戶端程式庫的參考資訊，請參閱參考說明文件。

返回頁首

.NET 用戶端程式庫開發人員指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目錄

觀眾