開發人員指南：通訊協定

重要事項：我們將在 2024 年 9 月 30 日停止支援 Google Data API 2.0 版。為確保相關功能持續運作，請將使用 Google Data API 2.0 版的應用程式更新為最新的 API 版本。如要使用最新版本，請使用左側的水平列連結。注意：雖然部分 GET 要求 (例如商家資訊貼文) 仍會支援動態饋給網址，但兩者的行為略有不同。詳情請參閱 Blogger 說明說明文件。

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 參考資訊，請參閱Protocol 參考指南。

開始使用

建立 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 要求的主體中。接著，在 metafeed 中找出網誌的文章網址，方法是找出 <link> 元素，其中 rel 屬性結尾為 #post。網誌的文章網址會以此元素的 href 屬性提供，格式如下：

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

注意：這個網址與網誌人類可讀版本的 <head> 部分中顯示的 <link rel="service.post"> 標記中的網址相同。

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 公開動態饋給，無須驗證。因此，從公開網誌擷取網誌文章時，您不需要設定授權參數。

擷取所有網誌文章

如要擷取使用者的貼文，請向網誌的動態饋給網址傳送 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 屬性中找到該 ETag。

例如：

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

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

如果 ETag 不相符，表示自您上次要求以來，項目已遭修改，而 Blogger 會傳回該項目。

如要進一步瞭解 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 的項目。
max-results
要傳回的項目數量上限。
orderby
傳回項目的順序，例如 lastmodified (預設)、starttime 或 updated。
published-min、published-max
項目發布日期的邊界。
start-index
要擷取的第一個結果的索引 (以 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 格式，請參閱Protocol 參考指南。

返回頁首