開發人員指南：.NET

重要事項：自 2024 年 9 月 30 日起，我們將停止支援 2.0 Google Data API。為確保能持續運作，請將採用 2.0 版 Google Data API 的應用程式更新至最新版 API。如需最新版本，請使用左側導覽列中的連結。注意：雖然系統會繼續支援部分 GET 要求 (例如：列出貼文)，但其行為仍有些微差異。詳情請參閱 Blogger 說明說明文件。

Blogger Data API 可讓用戶端應用程式查看及更新 Google Data API 動態饋給形式的 Blogger 內容。

您的用戶端應用程式可以使用 Blogger Data API 來建立新的網誌文章、編輯或刪除現有的網誌文章，還能查詢符合特定條件的網誌文章。

除了提供 Blogger Data API 的一些功能背景外，本文件還提供了使用 .NET 用戶端程式庫的基本 Data API 互動範例。如要進一步瞭解程式庫使用的基礎通訊協定，請參閱本開發人員指南的「通訊協定」一節。

目錄

  1. 觀眾
  2. 開始使用
    1. 建立 Blogger 帳戶
    2. 執行程式碼範例
  3. 通過 Blogger 服務驗證
    1. AuthSub Proxy 驗證
    2. ClientLogin 使用者名稱/密碼驗證
  4. 擷取網誌清單
  5. 建立貼文
    1. 發布網誌文章
    2. 建立網誌文章草稿
  6. 擷取貼文
    1. 擷取所有網誌文章
    2. 使用查詢參數擷取貼文
  7. 更新貼文
  8. 刪除貼文
  9. 留言
    1. 建立留言
    2. 擷取註解
    3. 刪除留言

觀眾

本文件的適用對象為想編寫可與 Blogger 互動的 .NET 用戶端應用程式的程式設計人員。

本文假設您瞭解 Google Data API 通訊協定的一般概念。

如需用戶端程式庫提供的類別和方法相關參考資訊，請參閱 .NET 用戶端程式庫 API 參考資料。如需一般 Blogger Data API 參考資訊，請參閱通訊協定參考指南。

開始使用

如需設定用戶端程式庫的說明，請參閱入門指南。

如要使用 .NET 用戶端程式庫，您將會需要 .NET 1.1 執行階段，且所有修補程式也應具備最新版本。下載用戶端程式庫後，您就會在發行的 lib/Release 子目錄中找到開始使用所需的 DLL。

建立 Blogger 帳戶

建議您註冊 Blogger 帳戶以進行測試。Blogger 使用 Google 帳戶，因此如果您已經擁有 Google 帳戶，那就大功告成了。

執行程式碼範例

您可以在 .NET 用戶端程式庫專案中找到完整運作的範例用戶端 (包含本文件顯示的所有程式碼範例)。範例位於 SVN 存放區「Source」分頁的 /trunk/clients/cs/samples/blogger/ConsoleSample.cs 中。

在編譯及執行這個範例之前，請將 username、password、blogName 和 postId 的值更新為適當的值。username 和 password 值代表用來登入 Blogger 的憑證。blogName 值是網誌的 blogspot 網址開頭。

範例用戶端會在提供的網誌上執行多項作業，以示範 Blogger Data API 的使用。

如要將本文件中的範例編譯成您自己的程式碼，您需要下列 using 陳述式：

using Google.GData.Client;
using System.Net;
using System.Xml;
using System.Text.RegularExpressions;

驗證 Blogger 服務

您可以透過 Blogger Data API 存取公開和私人的動態饋給。 公開動態饋給不需要任何驗證，但屬於唯讀性質。如要修改網誌，則用戶端必須先通過驗證，才能要求私人動態饋給。進行驗證時，方法有兩種：AuthSub Proxy 驗證或 ClientLogin 使用者名稱/密碼驗證。

如要進一步瞭解 Google Data API 驗證的一般資訊，請參閱驗證說明文件。

AuthSub Proxy 驗證

需要向 Google 帳戶驗證使用者身分的網頁應用程式，會使用 AuthSub Proxy 驗證。網站運算子及用戶端程式碼無法存取 Blogger 使用者的使用者名稱和密碼，而是會改為取得特殊的 AuthSub 憑證，讓用戶端能夠代表特定使用者執行動作。詳情請參閱 AuthSub 說明文件。

使用者首次造訪您的應用程式時，他們尚未通過驗證。在這種情況下，您必須顯示一些資訊以及將使用者導向 Google 頁面的連結，才能驗證您網誌的存取權要求。

假設您的網頁定義了以下 ASP 超連結：

<asp:HyperLink ID="GotoAuthSubLink" runat="server"/>

接著，如要建構應用程式的 AuthSubRequest 網址，請依下列方式發出 .NET 用戶端程式庫呼叫：

GotoAuthSubLink.Text = "Login to your Google Account";
GotoAuthSubLink.NavigateUrl =
  AuthSubUtil.getRequestUrl("http://www.example.com/RetrieveToken",
  "http://www.blogger.com/feeds/",
  false,
  true);

getRequestUrl 方法會使用下列參數 (對應 AuthSubRequest 處理常式使用的查詢參數)：

繼續
Google 在驗證完成後應將使用者重新導向至的網頁網址。
範圍
指出應用程式要求存取 Blogger 動態消息的權杖。要使用的範圍字串為 http://www.blogger.com/feeds/ (當然是經過網址編碼)。
安全
指出用戶端是否要求安全權杖。
工作階段
指出傳回的權杖是否可交換為多用途 (工作階段) 權杖。

以上範例顯示不會要求安全權杖 (secure 值為 false) 的呼叫，產生的要求網址可能會像這樣：

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2FRetrieveToken

使用者點選連結前往 Google 網站，並驗證自己的 Google 帳戶。

使用者完成驗證後，AuthSub 系統會將他們重新導向至您在 AuthSubRequest 網址的 next 查詢參數中指定的網址。AuthSub 系統會將驗證權杖附加至該網址，做為 token 查詢參數的值。因此，權杖可做為 ASP 頁面 Request.QueryString 物件中的變數存取。使用者被重新導向至類似以下的網址：

http://www.example.com/RetrieveToken?token=yourAuthToken

這個權杖值代表單次使用的 AuthSub 權杖。在這個範例中，由於已指定 session = true，因此這組權杖可用於 AuthSub 工作階段符記，如下所示：

SessionsessionToken = AuthSubUtil.exchangeForSessionToken(Request.QueryStringtoken, null);

也就是說，您要將一次性權杖與 null (針對未註冊模式) 或私密金鑰 (用於已註冊模式) 傳送至 exchangeForSessionToken 方法，而 AuthSub 介面會傳回工作階段符記。如要進一步瞭解已註冊的應用程式與私密金鑰，請參閱 AuthSub 說明文件的「簽署要求」一節。

如此一來，您的應用程式就可以在與 Blogger 的後續互動中使用工作階段符記值。如要指示 .NET 用戶端程式庫在每次要求時自動傳送授權標頭 (包含工作階段符記)，請執行下列操作：

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("blogger", "BloggerSampleApp");
authFactory.Token = SessionsessionToken.ToString();
Service service = new Service(authFactory.ApplicationName);
service.RequestFactory = authFactory;

ClientLogin 使用者名稱/密碼驗證

如果您的用戶端是獨立的單一使用者「安裝」用戶端 (例如桌面應用程式)，請使用 ClientLogin 驗證。請按照下列方式設定服務物件的憑證：

Service service = new Service("blogger", "exampleCo-exampleApp-1");
service.Credentials = new GDataCredentials("user@example.com", "secretPassword");
GDataGAuthRequestFactory factory = (GDataGAuthRequestFactory) service.RequestFactory;
factory.AccountType = "GOOGLE";

在上方的程式碼片段中，我們會將兩個參數傳遞至 Service 建構函式。第一個參數是我們想互動的服務名稱。第二個參數則是應用程式的名稱，格式為 companyName-applicationName-versionID。此外，我們也將 Service.RequestFactory 設定為僅使用 GOOGLE 帳戶類型，以便為 G Suite 使用者提供適當驗證。

如要進一步瞭解 ClientLogin 驗證，包括要求與回應範例，請參閱已安裝應用程式的驗證說明文件。

注意：在指定工作階段中，所有要求使用相同權杖，請不要取得每個 Blogger 要求的新權杖。

注意：如 ClientLogin 說明文件所述，驗證要求可能會失敗，並要求進行 CAPTCHA 驗證。如要讓 Google 發出及處理人機驗證 (CAPTCHA) 驗證問題，請將使用者傳送至 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger，而非用戶端登入說明文件中提供的人機驗證 (CAPTCHA) 處理網址。

擷取網誌清單

Blogger Data API 提供的動態饋給可列出特定使用者的網誌；該動態饋給稱為「中繼動態饋給」。

以下程式碼範例使用經過驗證的 Service 物件擷取中繼動態饋給，然後列印每個網誌的標題。

query.Uri = new Uri("http://www.blogger.com/feeds/default/blogs");
AtomFeed feed = null;
try
{
  feed = service.Query(query);
  foreach (AtomEntry entry in feed.Entries)
  {
    Console.WriteLine("Blog Title: " + entry.Title.Text);
  }
}

記下 getFeed 方法使用的網址。這是預設的中繼動態饋給網址，並且會傳回目前已驗證使用者的網誌清單。如要存取其他使用者的動態消息，您可以將使用者 ID 取代為中繼動態饋給網址中的 default。使用者 ID 是指使用者個人資料網址末端的數字字串。

建立貼文

Blogger Data API 可讓您建立並發布新的網誌項目，以及建立項目的草稿。

以下所有範例都假設您擁有經過驗證的 Service 物件。

注意：目前不支援為貼文設定自訂作者。所有新貼文都會顯示為目前經過驗證的使用者所建立。

發布網誌文章

您可以使用 .NET 用戶端程式庫發布新的網誌項目。

首先，請建立 AtomEntry 物件來代表網誌文章。然後設定網誌文章的標題、內容和其他屬性。 最後，使用 Service 物件插入貼文。以下是如何發布新網誌文章的範例：

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
  "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
  "<p>He is the last man on earth I would ever desire to marry.</p>" +
  "<p>Whatever shall I do?</p>" +
  "</div>";
newPost.Content.Type = "xhtml";

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

Insert 方法會將服務的貼文網址做為參數。接著方法會傳回 Blogger 儲存的項目。傳回的項目與您傳送的項目相同，但也包含 Blogger 新增的各種元素，例如文章 ID。

如果因為某些原因導致要求失敗，Blogger 可能會傳回不同的狀態碼。如要進一步瞭解狀態碼，請參閱 Google Data API 通訊協定參考文件。

建立網誌文章草稿

草稿貼文的建立方式與公開貼文相同，但必須設定 AtomEntry 物件的 draft 屬性。上述的網誌文章可以加上醒目顯示的程式碼行，建立為草稿：

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
    "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
    "<p>He is the last man on earth I would ever desire to marry.</p>" +
    "<p>Whatever shall I do?</p>" +
    "</div>";
newPost.Content.Type = "xhtml";
newPost.IsDraft = true;

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

如要將現有的網誌文章草稿轉換為已發布的文章，請擷取草稿文章，將草稿屬性設為 false，然後更新貼文。我們將在接下來的兩個章節中介紹如何擷取及更新貼文。

擷取貼文

以下各節說明如何擷取含及不含查詢參數的網誌文章清單。

你不需要驗證，可以查詢 Blogger 公開動態消息。因此，從公開網誌擷取文章前，您不需要設定憑證或進行 AuthSub 驗證。

擷取所有網誌文章

如要擷取使用者的貼文，請呼叫用來擷取網誌中繼動態饋給的相同 getFeed 方法，但這次要傳送網誌文章動態饋給網址：

query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
feed = service.Query(query);
Console.WriteLine(feed.Title.Text);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("Entry Title: " + entry.Title.Text);
}

使用查詢參數擷取貼文

Blogger Data API 可讓您要求一組符合指定條件的項目，例如要求在指定日期範圍內發布或更新的網誌文章。方法是建立 FeedQuery 物件，並傳遞至 Service.Query() 方法。

舉例來說，如要傳送日期範圍查詢，請設定 FeedQuery 物件的 MinPublication 和 MaxPublication 成員。下列程式碼片段會列印指定開始時間與結束時間之間的每篇網誌文章標題：

FeedQuery query = new FeedQuery();
query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
query.MinPublication = new DateTime(2006, 1, 1);
query.MaxPublication = new DateTime(2007, 4, 12);
AtomFeed feed = service.Query(query);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("  Entry Title: " + entry.Title.Text);
}

請注意，FeedQuery 物件是根據用來擷取貼文的貼文動態消息網址建立而成。

Blogger Data API 支援下列查詢參數：

alt
要傳回的動態饋給類型，例如 atom (預設值) 或 rss。
/category
指定類別 (也稱為「標籤」) 來篩選動態饋給結果。舉例來說，http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 會傳回同時具有 Fritz 和 Laurie 標籤的項目。
max-results
傳回的項目數量上限。
訂購
項目傳回順序，例如 lastmodified (預設值)、starttime 或 updated。
Publishing-min、publish-max
項目發布日期的邊界。
start-index
要擷取的第一個結果的 1 式索引 (用於分頁)。
update-min、update-max
項目更新日期的邊界。除非 orderby 參數設為 updated，否則系統會忽略這些查詢參數。

如要進一步瞭解查詢參數，請參閱《Blogger Data API 參考指南》和《Google Data API 參考指南》。

更新貼文

如要更新現有的網誌文章，請先擷取您要更新的項目，然後進行修改，再使用項目的 Update() 方法將文章傳送至 Blogger。下列程式碼片段會假設您已從伺服器擷取項目標題，並修改網誌項目的標題。

static AtomEntry EditEntry(AtomEntry toEdit)
{
  // Edit the entry by changing the Title and calling Update().
  if (toEdit != null)
  {
    toEdit.Title.Text = "Marriage Woes!";
    toEdit = toEdit.Update();
  }
  return toEdit;
}

上述程式碼會傳回 AtomEntry，其中包含最近更新的完整貼文。如要更新任何其他屬性，只要在呼叫 Update() 之前在 AtomEntry 物件中設定屬性即可。

注意：目前不支援修改與貼文相關聯的作者資料。

刪除貼文

如要刪除貼文，請在現有的 AtomEntry 物件上呼叫 Delete 方法，如下所示：

static void DeleteEntry(AtomEntry toDelete)
{
  // Delete the edited entry
  if (toDelete != null)
  {
    toDelete.Delete();
  }
}

註解

Blogger Data API 可讓您建立、擷取及刪除留言。 不支援更新註解 (且在網頁介面上也無法使用)。

正在建立留言

如要發布留言，請建立 AtomEntry 物件並插入，如下所示：

AtomEntry comment;
comment = new AtomEntry();
comment.Title.Text = "This is my first comment";
comment.Content.Content = "This is my first comment";
Uri commentPostUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/" + entryId + "/comments/default");
postedComment = service.Insert(commentPostUri, comment);

注意：目前您只能將留言張貼至已驗證使用者擁有的網誌。

注意：目前不支援為留言設定自訂作者。所有新註解都會顯示為目前經過驗證的使用者所建立。

擷取註解

您可以從該則貼文的留言動態消息網址中擷取特定訊息的留言：

static void ListEntryComments(Service service, Uri commentUri)
{
  if (commentUri != null)
  {
    // Retrieve all comments on a blog entry
    FeedQuery query = new FeedQuery();
    query.Uri = commentUri;
    AtomFeed feed = service.Query(query);
    foreach (AtomEntry entry in feed.Entries)
    {
      Console.WriteLine("  Comment Title: " + entry.Title.Text);
    }
  }
}

您也可以使用網誌的留言動態消息網址，取得所有文章的留言：

http://www.blogger.com/feeds/blogID/comments/default

正在刪除留言

如要刪除註解，請對現有的註解 AtomEntry 物件呼叫 Delete() 方法，如下所示：

static void DeleteComment(AtomEntry commentEntry)
{
  if (commentEntry != null)
  {
    // Delete the comment.
    commentEntry.Delete();
  }
}

返回頁首