開發人員指南：通訊協定

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

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

除了提供 Blogger Data API 功能的背景之外，本文件也提供了使用原始 XML 與 HTTPS 的基本 Data API 互動範例。閱讀本文件後，您可能需要閱讀這份開發人員指南的程式設計語言專屬章節，進一步瞭解如何利用用戶端程式庫與 API 互動。

目錄

  1. 觀眾
  2. 開始使用
    1. 建立 Blogger 帳戶
  3. 授權要求
  4. 指定版本
  5. 擷取網誌清單
  6. 建立貼文
    1. 發布網誌文章
    2. 建立網誌文章草稿
  7. 擷取貼文
    1. 擷取所有網誌文章
    2. 重新擷取網誌文章
    3. 使用查詢參數擷取貼文
  8. 更新貼文
  9. 刪除貼文
  10. 註解
    1. 建立留言
    2. 擷取留言
    3. 刪除留言
  11. 匯出格式

觀眾

本文件的適用對象為想透過 XML 和 HTTPS 與 Blogger 互動的用戶端應用程式。

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

如果您使用 UNIX 系統，並且想嘗試本文件中的範例，而不必編寫任何程式碼，那麼 UNIX 指令列公用程式 curl 或 wget 可能對您有所幫助；詳情請參閱這些公用程式的手動頁面。

如需 Blogger Data API 參考資料資訊，請參閱通訊協定參考指南。

開始

建立 Blogger 帳戶

如要進行測試，建議您註冊 Blogger 帳戶。Blogger 會使用 Google 帳戶，因此如果您已經有 Google 帳戶，就表示大功告成。

授權要求

應用程式要求公開非公開的使用者資料時，必須包含授權權杖。這個憑證也可讓 Google 識別您的應用程式。

關於授權通訊協定

建議您使用 OAuth 2.0 來授權要求。

Blogger GData API 也支援舊版授權選項，例如 OAuth 1.0、AuthSub 或 ClientLogin；不過在大多數情況下，我們不建議使用其他選項。如果您的應用程式已使用這些選項，建議您盡可能遷移至 OAuth 2.0。

如果您的應用程式有特定的特殊授權需求 (例如同時登入以要求資料存取權 (混合型) 或全網域授權授權 (2LO)，目前就無法使用 OAuth 2.0 權杖。在這種情況下，請改用 OAuth 1.0 權杖。

使用 OAuth 2.0 授權要求

向 Blogger GData API 要求非公開的使用者資料時，都必須由已通過驗證的使用者授權。

授權程序的詳細資料 (也就是「流程」) 的細節會因 OAuth 2.0 的情況而有所差異。以下一般流程適用於所有應用程式類型：

  1. 建立應用程式時，您必須向 Google 註冊應用程式。接著，Google 會提供您稍後所需的資訊，例如用戶端 ID 和用戶端密鑰。
  2. 當應用程式需要存取使用者資料時，會要求 Google 授予特定範圍的存取權。
  3. Google 會向使用者顯示 OAuth 對話方塊，要求他們授權您的應用程式要求部分資料。
  4. 如果使用者核准要求，Google 就會為您的應用程式提供短期的存取權杖。
  5. 您的應用程式會要求使用者資料，並將存取權杖附加至要求。
  6. 如果 Google 判定您的要求和權杖有效，就會傳回要求的資料。

部分流程包含額外步驟，例如使用重新整理權杖取得新的存取權杖。如要進一步瞭解各種應用程式適用的流程，請參閱 Google 的 OAuth 2.0 說明文件。

以下是 Blogger GData API 的 OAuth 2.0 範圍資訊：

https://www.blogger.com/feeds/

如要透過 OAuth 2.0 要求存取權，應用程式需要範圍資訊，以及 Google 在應用程式註冊期間提供的資訊 (例如用戶端 ID 和/或用戶端密鑰)。

提示：Google API 用戶端程式庫可以為您處理部分授權程序，這些程式設計語言支援多種程式設計語言；詳情請參閱程式庫和範例頁面。

指定版本

凡是使用 Blogger Data API 傳送的要求，都必須指定 API 版本 2。

如要指定版本號碼，請使用 GData-Version HTTP 標頭：

GData-Version: 2

或者，如果可以設定 HTTP 標頭，則可將 v=2 指定為網址的查詢參數。但我們會優先使用 HTTP 標頭。

注意：用戶端程式庫會自動提供適當的版本標頭，因此在您使用用戶端程式庫時，請勿使用 v=2 查詢參數。

擷取網誌清單

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

將 HTTP GET 傳送至下列網址以擷取網誌清單：

https://www.blogger.com/feeds/profileID/blogs

其中 ID 是指使用者個人資料頁面網址中的數字。

注意：您也可以將 default 替換成使用者 ID，讓 Blogger 針對憑證的要求使用者傳回網誌清單。

中繼動態饋給中的項目可能會如下所示：

<entry gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'>
  <id>tag:blogger.com,1999:user-userNumber.blog-blogID</id>
  <published>2006-08-02T18:44:43.089-07:00</published>
  <updated>2008-04-17T00:03:33.152-07:00</updated>
  <title>Lizzy's Diary</title>
  <summary type='html'>Being the journal of Elizabeth Bennet</summary>
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/profileID/blogs/blogID' />
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/' />
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default' />
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default' />
  ...
  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://www.blogger.com/profile/profileID</uri>
    <email>noreply@blogger.com</email>
  </author>
</entry>

如要瞭解這些元素代表的意義，請參閱 Google Data API 通訊協定參考資料或 Atom 1.0 規格。

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

建立貼文

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

發布網誌文章

通過驗證後，你就可以發布新的網誌項目。

首先，請針對要發布的文章建立 XML 表示法。這個 XML 必須以 Atom <entry> 元素的形式，如下所示：

<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Marriage!</title>
  <content type='xhtml'>
    <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>
  </content>
  <category scheme="http://www.blogger.com/atom/ns#" term="marriage" />
  <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" />
</entry>

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

若要發布此項目，請按照下列文章傳送至網誌的貼文網址。首先，請使用 application/atom+xml 內容類型，將 Atom <entry> 元素放在新的 POST 要求主體中。接著在中繼資料中尋找<link> 元素以 rel 結尾，#post 的網誌即可找到網誌的貼文網址。網誌的貼文網址會做為這個元素的 href 屬性，格式如下：

https://www.blogger.com/feeds/blogID/posts/default

注意：這個網址與 <link rel="service.post"> 標記中顯示的網址相同，也就是可供使用者理解的網誌 <head> 部分。

Blogger 會使用您傳送的項目建立網誌文章，然後傳回 HTTP 201 CREATED 狀態碼，以及 <entry> 元素形式的新貼文副本。傳回的項目與您先前傳送的項目相同，但其中包含 Blogger 新增的各種元素，例如 <id> 元素。

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

建立網誌文章草稿

草稿訊息的建立方式與公開貼文相同，但系統會在項目中加入 <app:control> 元素，指出貼文不應 (但尚未發布)。

這個 <app:control> 元素應包含單一的 <app:draft> 元素做為子項：

<app:control xmlns:app='http://www.w3.org/2007/app'>
  <app:draft>yes</app:draft>
</app:control>

<app:draft> 元素中包含的資料必須是 yes 字串，才能將貼文視為草稿。

您可以將現有的草稿網誌文章轉換為已發布的貼文，只要擷取草稿文章，將 <app:draft> 元素資料設為 no 字串，然後更新貼文即可。後續兩節將會涵蓋擷取和更新貼文。

注意：如要進一步瞭解 Atom 發布通訊協定，包括 <app:control> 和 <app:draft> 命名空間，請參閱 RFC 5023。

擷取貼文

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

您不必驗證就能查詢 Blogger 公開動態饋給。因此，當您從公開網誌擷取網誌文章時，就不必設定 Authorization 參數。

擷取所有網誌文章

如要擷取使用者的貼文，請將 HTTP GET 要求傳送至網誌的動態饋給網址。接著 Blogger 會傳回含有適當網誌項目的動態消息。舉例來說，如要取得 liz@gmail.com 的網誌文章清單，請將下列 HTTP 要求傳送給 Blogger (使用適當的值來取代 blogID )：

GET https://www.blogger.com/feeds/blogID/posts/default

接著，Blogger 會傳回 HTTP 200 OK 狀態碼和一篇包含網誌文章的標準 Atom 1.0 動態消息。

以下範例是只含有一篇文章的網誌動態饋給。請注意，我們已稍早編輯此範例，使其更容易理解。具體來說，實際的 Blogger 動態饋給會包含實際 ID 和網址。

<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet href="http://www.blogger.com/styles/atom.css"
  type="text/css"?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'>
  <id>tag:blogger.com,1999:blog-blogID</id>
  <updated>2008-04-17T00:03:33.152-07:00</updated>
  <title>Lizzy's Diary</title>
  <subtitle type='html'></subtitle>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default' />
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default' />
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/' />
  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://www.blogger.com/profile/profileID</uri>
    <email>noreply@blogger.com</email>
  </author>
  <generator version='7.00'
    uri='http://www2.blogger.com'>Blogger</generator>
  <entry gd:etag='W/"D0YHRn84eip7ImA9WxZUFk8."'>
    <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
    <published>2008-04-07T20:25:00.005-07:00</published>
    <updated>2008-04-07T20:25:37.132-07:00</updated>
    <title>Quite disagreeable</title>
    <content type='html'>&lt;p&gt;I met Mr. Bingley's friend Mr. Darcy
      this evening. I found him quite disagreeable.&lt;/p&gt;</content>
    <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/posts/default/postID' />
    <link rel='self' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/posts/default/postID' />
    <link rel='alternate' type='text/html'
      href='http://blogName.blogspot.com/2008/04/quite-disagreeable.html' />
    <author>
      <name>Elizabeth Bennet</name>
      <uri>http://www.blogger.com/profile/profileID</uri>
      <email>noreply@blogger.com</email>
    </author>
  </entry>
</feed>

再次擷取網誌文章

如果您想擷取先前擷取過的文章，可以建議 Blogger 只有在您上次擷取文章後有所變動，才能提高張貼效率。

如要執行此類條件擷取作業，請傳送包含 HTTP If-None-Match 標頭的 HTTP GET 要求。在標頭中指定項目的 ETag，可在 <entry> 元素和 gd:etag 屬性中找到。

例如：

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Blogger 收到這項要求後，會檢查您要求的項目是否與您指定的 ETag 相同 ETag。如果 ETag 相符，則項目保持不變，Blogger 會傳回 HTTP 304 Not Modified 狀態碼。

如果 ETag 不相符，則自

如要進一步瞭解 ETag，請參閱 Google Data API 參考指南。

使用查詢參數擷取貼文

Blogger Data API 可讓您要求一組與指定條件相符的項目，例如要求在指定日期範圍內發布或更新的網誌文章。

舉例來說，如要傳送日期範圍查詢，請在要求網址中加入 published-min 和 published-max 參數。如要取得 2008 年 3 月 16 日至 2008 年 3 月 24 日之間建立的所有網誌項目，請傳送 HTTP 要求至網誌的動態消息網址：

GET https://www.blogger.com/feeds/blogID/posts/default?published-min=2008-03-16T00:00:00&published-max=2008-03-24T23:59:59

當您傳送 GET 要求時，Blogger 會傳回 HTTP 200 OK 狀態碼，以及您在指定日期範圍內建立的網誌文章。

updated-min 和 updated-max 參數也可用來更新指定範圍內的所有網誌項目。不過請注意，除非 orderby 參數也設為 updated，否則系統會忽略這些參數。

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

alt
要傳回的動態饋給類型，例如 atom (預設) 或 rss。
/category
指定類別 (也就是標籤) 可篩選動態饋給結果。例如，https://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 會傳回同時包含 Fritz 和 Laurie 標籤的項目。
最大結果
要傳回的項目數量上限。
排序依據
傳回項目的順序，例如 lastmodified (預設值)、starttime 或 updated。
發布-分鐘，發布上限
項目發布日期的邊界。
起始索引
要擷取的第一個結果以 1 為基礎的索引 (用於分頁)。
updated-min, updated-max
項目更新日期的邊界。除非 orderby 參數設為 updated，否則系統會忽略這些查詢參數。
路徑
貼文的永久連結路徑。舉例來說，如果文章的網址為 http://buzz.blogger.com/2011/08/bloggers-fresh-new-look.html，永久連結路徑就是 /2011/08/bloggers-fresh-new-look.html。
q
全文查詢字串。這可讓你在網誌中搜尋與查詢相符的文章。

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

正在更新貼文

如要更新現有網誌文章，請先擷取您要更新的項目，然後加以修改，然後再將 PUT 要求和訊息內文中的更新項目傳送至貼文的編輯網址。確認 PUT 項目中的 <id> 值與現有項目的 <id> 完全相符。

編輯項目會醒目顯示在下列項目中：

<entry gd:etag='W/"CUYDSXo8fSp7ImA9WB9UFkU."'>
  <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
  <published>2006-11-08T18:10:00.000-08:00</published>
  <updated>2006-11-08T18:10:14.954-08:00</updated>
  <title type='text'>Quite disagreeable</title>
  <content type='html'>&lt;p&gt;I met Mr. Bingley's friend Mr. Darcy
    this evening. I found him quite disagreeable.&lt;/p&gt;</content>
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/2006/11/quite-disagreeable.html'>
  </link>
  <link rel='self' type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default/postID'>
  </link>
  <link rel='edit' type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default/postID'>
  </link>
  <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Bingley" />
  <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" />
  <author>
    <name>Elizabeth Bennet</name>
    <email>noreply@blogger.com</email>
    <uri>http://www.blogger.com/profile/profileID</uri>
  </author>
</entry>

重要事項：為了確保回溯相容性，請務必在您PUT更新項目時所有 從 Blogger 擷取項目時出現的 XML。否則，當我們在實作新項目並在動態饋給中加入 <new-awesome-feature> 元素時，用戶端就不會傳回這些元素，而使用者可能會錯過。Google Data API 用戶端程式庫皆可正確處理這個問題，因此，如果您使用的其中一個程式庫已設定完成，

注意：目前無法修改與貼文相關的作者資料。

疑難排解提示：部分防火牆會封鎖 HTTP PUT 訊息。如要解決這個問題，請在 POST 要求中加入 X-HTTP-Method-Override: PUT 標頭。詳情請參閱 Google Data API 通訊協定基本概念文件。

刪除貼文

如要刪除貼文，請傳送 DELETE 要求至貼文的編輯網址。以及更新貼文的網址。

疑難排解提示：部分防火牆會封鎖 HTTP DELETE 訊息。如要解決這個問題，只要在 POST 要求中加入 X-HTTP-Method-Override: DELETE 標頭即可。詳情請參閱 Google Data API 通訊協定基本概念文件。

留言

Blogger Data API 可讓您建立、擷取及刪除留言。不支援更新註解 (或透過網頁介面提供註解)。

建立註解

如要發布註解，請建立如下的 Atom <entry> 元素：

  <entry xmlns='http://www.w3.org/2005/Atom'>
    <title type="text">This is my first comment</title>
    <content type="html">This is my first comment</content>
  </entry>

如要發布這則註解，請使用 application/atom+xml 內容類型將 Atom <entry> 元素放在新的 POST 要求主體中。接著將 POST 要求傳送至適當的 Blogger 網址：

POST https://www.blogger.com/feeds/blogID/postID/comments/default

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

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

擷取註解

只要將 GET 傳送至這個貼文的留言動態消息網址，即可擷取特定貼文的留言：

GET https://www.blogger.com/feeds/blogID/postID/comments/default

或者，你可以使用網誌和留言動態饋給的網址，接收所有貼文的留言： 

GET https://www.blogger.com/feeds/blogID/comments/default

這些要求會傳回留言動態饋給，如下所示：

<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet href="http://www.blogger.com/styles/atom.css"
  type="text/css"?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"CUYMQ348fyp7ImA9WB9UFkU."'>
  <id>tag:blogger.com,1999:blog-blogID.postpostID..comments</id>
  <updated>2007-12-14T17:46:22.077-08:00</updated>
  <title>Comments on Lizzy's Diary: Quite disagreeable</title>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/postID/comments/default' />
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/postID/comments/default' />
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html' />
  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://www.blogger.com/profile/profileID</uri>
    <email>noreply@blogger.com</email>
  </author>
  <generator version='7.00'
    uri='http://www.blogger.com'>Blogger</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <entry gd:etag='W/"CUYCQX47eSp7ImA9WB9UFkU."'>
    <id>tag:blogger.com,1999:blog-blogID.post-commentID</id>
    <published>2007-12-14T17:46:00.001-08:00</published>
    <updated>2007-12-14T17:46:00.001-08:00</updated>
    <title>Darcy FTW!</title>
    <content type='html'>Darcy FTW!</content>
    <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' />
    <link rel='self' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' />
    <link rel='alternate' type='text/html'
      href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html?showComment=1197683160001#ccommentID'
      title='' />
    <author>
      <name>Elizabeth Bennet</name>
      <uri>http://www.blogger.com/profile/profileID</uri>
      <email>liz@gmail.com</email>
    </author>
    <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0'
      href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html'
      ref='tag:blogger.com,1999:blog-blogID.post-postID'
      source='http://www.blogger.com/feeds/blogID/posts/default/postID'
      type='text/html' />
  </entry>
</feed>

刪除留言

如要刪除註解，請將 DELETE 要求傳送至註解的編輯網址。這個網址會醒目顯示在上方的留言動態消息中。

匯出格式

Blogger 可讓使用者使用 Blogger 匯出檔案匯出及匯入網誌。這個匯出檔案包含單一網誌的所有文章和留言。匯出檔案的格式與「擷取文章和註解」章節所述的 Atom 格式完全相同。這個匯出檔案會將貼文動態饋給的內容和留言動態饋給內容合併為一份文件。

如要使用匯出格式匯出或匯入網誌資料，請造訪網誌的「設定」頁面。如要使用 Data API 擷取網誌的匯出檔案，請使用下列網址：

GET https://www.blogger.com/feeds/blogID/archive

如要匯入匯出檔案，請在下列網址中建立 POST 要求，並將匯出檔案的內容做為要求資料，並將 application/atom+xml 做為內容類型：

POST https://www.blogger.com/feeds/blogID/archive/full

上述兩個網址都不支援查詢參數。兩項要求都必須包含驗證資訊，只有網誌管理員才能使用這些動態饋給網址匯入/匯出網誌。

注意：如果您自行建立 Blogger 匯出檔案，目前對於張貼留言和留言項目的順序設有限制。Blogger 匯出檔案會先列出所有文章，再列出所有註解。允許發布留言和留言項目，前提是留言內容必須與留言所屬的貼文相同。

如要進一步瞭解 Blogger 如何在匯出檔案中使用 Atom 格式，請參閱通訊協定參考指南。

返回頁首