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

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

Google 提供一系列的用戶端程式庫,能夠支援各種程式設計語言的 GData 服務。透過這些程式庫,您可以建構 GData 要求、將要求傳送至服務以及接收回應。

本文件提供一系列 C# 版本的常見應用實例,以及其他有關撰寫 GData 用戶端的資訊。本文件結尾處有 NDoc 格式的 C# 用戶端程式庫參考文件連結。

如要使用這個用戶端程式庫,您需要 .NET 1.1 執行階段,且在所有修補程式中也應處於最新狀態。

下載 .NET 用戶端程式庫。

本指南以 Google Calendar API 為例,但本指南並非正確或最新的使用 Calendar API 指南。如要瞭解如何將 .NET 用戶端程式庫與特定服務的 Data API 搭配使用,請參閱服務專屬說明文件。舉例來說,如果您使用 Google 日曆,請參閱 Calendar Data API 開發人員指南

目錄

目標對象

本文旨在協助 C# 程式設計師撰寫用戶端應用程式,以便與 GData 服務互動。

本文假設您已瞭解 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 日曆,請參閱 Google Calendar Data API 說明文件。

建立並執行用戶端

如要編譯這份文件的範例,您必須使用以下陳述式使用以下內容:

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 服務的用戶端連線 (須通過驗證)。使用用戶端程式庫將查詢傳送至一般程序的程序包括:

  1. 取得或建立適當的網址。
  2. 如果您要將資料傳送至服務 (例如,插入新項目),請使用用戶端程式庫類別將原始資料轉換為物件。(如果您只要求提供動態饋給,就不適用這個步驟)。
  3. 建立新的 Service 例項,設定服務名稱 (例如 Google 日曆的 "cl") 以及您的應用程式名稱 (格式為 companyName-applicationName-versionID)。
  4. 設定適當的憑證。
  5. 呼叫方法來傳送要求並接收任何結果。

service.setUserCredentials 方法使用標準 .NET Network 憑證物件來設定 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 (具備適當驗證機制) 並提供項目。

要求特定項目

以下程式碼可讓您要求您在上一個範例中插入的特定項目。

在這個系列的示例中,您不一定要擷取該項目,因為 Google 日曆已經傳回插入的項目,不過只要知道項目的網址,就可以套用相同的技巧。

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 日曆不會為標籤與活動建立關聯,因此這個範例不支援 Google 日曆。

如要擷取包含所有較舊全文搜尋、與特定類別或有特定標籤相符的項目,請使用以下程式碼:

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

當然,AtomCategory 類別代表要在類別篩選器中使用的類別。QueryCategory 類別可包含多個類別,但在這種情況下,我們只建立一個只包含一個類別的篩選器。

然後將該篩選器新增至現有查詢,但該查詢仍會包含上一個範例中的全文查詢字串。

我們再次使用 Query 方法將查詢傳送至服務。

如果 Google 日曆允許執行類別搜尋,上述程式碼就等於傳送 GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis 到 Google 日曆。

更新項目

如要更新現有項目,請使用下列程式碼。在以下範例中,我們會把先前擷取的項目標題從舊的文字 (「家中有伯丁」) 變更為「重要會議」。

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 子目錄中找到更詳細的擴充功能使用方式範例。已新增下列物件:

事件查詢
FeedQuery 的子類別,可讓您為日曆服務設定兩個自訂參數 (start-min 和 start-max)。
日曆服務
服務子類別,可傳回事件資訊提供。
事件資訊提供
AtomFeed 的子類別,顯示 EventEntries。
事件項目
AtomEntry 的子類別,其中包含日曆資料的額外屬性。

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

參考資料

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

返回頁首