開發人員指南:通訊協定

重要事項:這是舊版的舊版頁面。如需最新版本,請使用左側導覽列中的連結。

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

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

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

目錄

觀眾

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

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

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

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

開始

建立 Blogger 帳戶

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

驗證 Blogger 服務

使用 Blogger Data API 就能存取公開和私人的動態消息。 公開動態饋給不需要驗證,但處於唯讀狀態。如要修改網誌,則用戶端必須先進行驗證,才能要求私人動態饋給。身分驗證方式有兩種:AuthSub Proxy 驗證或 ClientLogin 使用者名稱/密碼驗證。

如要進一步瞭解如何使用 Google Data API 進行驗證,請參閱驗證說明文件

在本文件的後續章節中,大部分範例假設您已提供適當的驗證機制。

AuthSub Proxy 驗證

需要驗證使用者提供給 Google 帳戶的網頁應用程式會使用 AuthSub Proxy 驗證。網站運算子和用戶端代碼無法存取 Blogger 使用者的使用者名稱和密碼;用戶端則會取得特殊的 AuthSub 權杖,允許用戶端代表特定使用者採取行動。詳情請參閱 AuthSub 說明文件

使用者第一次造訪您的應用程式時,尚未通過驗證。在這種情況下,您必須顯示某些資訊,以及透過連結將使用者帶往 Google 頁面的連結,以便我們驗證您的網誌存取要求。

AuthSubRequest 網址中包含以下查詢參數:

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

AuthSubRequest 網址看起來可能像這樣:

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%2Fwelcome.html

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

使用者驗證完成後,AuthSub 系統會將使用者重新導向至 AuthSubRequest 網址的 next 查詢參數中指定的網址。AuthSub 系統會將驗證權杖附加至該網址,做為 token 查詢參數的值。例如:

http://www.example.com/welcome.html?token=yourAuthToken

這個權杖值代表一次性的 AuthSub 權杖。在這個範例中,因為指定 session=1,所以您可以透過在 Authorization 標頭中使用單一一次性權杖呼叫 AuthSubSessionToken 服務,將這個權杖交換到 AuthSub 工作階段符記,如下所示:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

AuthSubSessionToken 服務回應包含包含工作階段符記的 Token 標頭和指出權杖有效時間的 Expiration 標頭。

然後,應用程式就可以在後續與 Blogger 的 Authorization 標頭中使用工作階段符記值。

以下示範如何在 HTTP 要求 (含有不安全的權杖) 中傳送 HTTP 要求:

GET /feeds/blogID/blogs/posts/defaults HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourSessionToken"
User-Agent: Java/1.5.0_06
Host: www.blogger.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

ClientLogin 使用者名稱/密碼驗證

如果您的用戶端是獨立的單一使用者「已安裝」用戶端 (例如電腦版應用程式),請使用 ClientLogin 驗證。如要使用 ClientLogin 機制要求驗證權杖,請將 POST 要求傳送至下列網址:

https://www.google.com/accounts/ClientLogin

POST 主體應包含一組查詢參數,看起來像是 HTML 表單傳遞,並使用 application/x-www-form-urlencoded 內容類型。這些參數如下:

電子郵件
使用者的電子郵件地址。
Passwd
使用者的密碼。
服務
Blogger 服務名稱為 blogger。如果是其他服務名稱,請參閱服務名稱清單。)
accountType
使用 Blogger API 時,請一律設為 GOOGLE。如未設定這個參數,就無法同時存取 G Suite 帳戶的使用者。
source
用於識別你的用戶端應用程式。格式應為 companyName-applicationName-versionID。範例使用 exampleCo-exampleApp-1 名稱。

如要進一步瞭解參數,請參閱安裝版應用程式驗證文件。

如果驗證要求失敗,伺服器會傳回 HTTP 403 Forbidden 狀態碼。

如果成功,伺服器會傳回 HTTP 200 OK 狀態碼,以及回應內文中的三個長英數字元代碼:SID、LSID,以及 Auth。「驗證值」是與您後續所有要求一起傳送給 Blogger 的授權權杖,因此請使用這個值。您可以忽略 SID 和 LSID 值。

所有傳送給私人動態饋給的要求都需要進行驗證,因此您必須按照下列格式在日後與 Blogger 的互動設定「Authorization 」標頭:

Authorization: GoogleLogin auth=yourAuthToken

其中 yourAuthToken 是 ClientLogin 要求傳回的驗證字串。

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

注意:在特定工作階段中的所有要求都使用相同的權杖;請勿為各個 Blogger 要求取得新權杖。

注意:如「ClientLogin」說明文件中所述,驗證要求可能會失敗,並要求進行人機驗證 (Captcha) 驗證。如果您想讓 Google 發出及處理人機驗證 (Captcha) 驗證問題,請將使用者傳送至 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (而非 ClientLogin 說明文件中的人機驗證 (Captcha) 處理網址)。

擷取網誌清單

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

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

http://www.blogger.com/feeds/userID/blogs

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

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

<entry>
  <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
  <published>2006-08-02T18:44:43.089-07:00</published>
  <updated>2006-11-08T18:10:23.020-08:00</updated>
  <title type='text'>Lizzy's Diary</title>
  <summary type='html'>Being the journal of Elizabeth Bennet</summary>
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/'>
  </link>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default'>
  </link>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default'>
  </link>
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/userID/blogs/blogID'>
  </link>
  <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/userID/blogs/blogID'>
  </link>
  <author>
    <name>Elizabeth Bennet</name>
    <email>noreply@blogger.com</email>
    <uri>http://www.blogger.com/profile/profileID</uri>
  </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 屬性,格式如下:

http://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://purl.org/atom/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 http://www.blogger.com/feeds/blogID/posts/default

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

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

<feed xmlns='http://www.w3.org/2005/Atom'>
  <id>tag:blogger.com,1999:blog-blogID</id>
  <updated>2006-11-08T18:10:23.020-08:00</updated>
  <title type='text'>Lizzy's Diary</title>
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/index.html'>
  </link>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default'>
  </link>
  <link rel='self' type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default'>
  </link>
  <author>
    <name>Elizabeth Bennet</name>
    <email>noreply@blogger.com</email>
    <uri>http://www.blogger.com/profile/profileID</uri>
  </author>
  <generator version='7.00' uri='http://www2.blogger.com'>Blogger</generator>
  <entry>
    <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>
    <author>
      <name>Elizabeth Bennet</name>
      <email>noreply@blogger.com</email>
      <uri>http://www.blogger.com/profile/profileID</uri>
    </author>
  </entry>
</feed>

使用查詢參數擷取貼文

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

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

GET http://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-minupdated-max 參數也可用來更新指定範圍內的所有網誌項目。不過請注意,除非 orderby 參數也設為 updated,否則系統會忽略這些參數。

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

alt
要傳回的動態饋給類型,例如 atom (預設) 或 rss
/category
指定類別 (也就是標籤) 可篩選動態饋給結果。例如,http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 會傳回同時包含 FritzLaurie 標籤的項目。
最大結果
要傳回的項目數量上限。
排序依據
傳回項目的順序,例如 lastmodified (預設值)、starttimeupdated
發布-分鐘,發布上限
項目發布日期的邊界。
起始索引
要擷取的第一個結果以 1 為基礎的索引 (用於分頁)。
updated-min, updated-max
項目更新日期的邊界。除非 orderby 參數設為 updated,否則系統會忽略這些查詢參數。

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

正在更新貼文

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

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

<entry>
  <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 http://www.blogger.com/feeds/blogID/postID/comments/default

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

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

擷取註解

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

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

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

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

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

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
         xmlns:thr="http://purl.org/syndication/thread/1.0">
  <id>tag:blogger.com,1999:blog-blogID.post-postID.comment-commentID</id>
  <updated>2007-04-04T21:56:29.803-07:00</updated>
  <title type="text">My Blog : Time to relax</title>
  <link rel="alternate" type="text/html" href="http://blogName.blogspot.com/2007/04/first-post.html"/>
  <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://blogName.blogspot.com/feeds/postID/comments/default"/>
  <author>
    <name>Blog Author name</name>
  </author>
  <generator version="7.00" uri="http://www2.blogger.com">Blogger</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <entry>
    <id>tag:blogger.com,1999:blog-blogID.post-commentID</id>
    <published>2007-04-04T21:56:00.000-07:00</published>
    <updated>2007-04-04T21:56:29.803-07:00</updated>
    <title type="text">This is my first comment</title>
    <content type="html">This is my first comment</content>
    <link rel="alternate" type="text/html" href="http://blogName.blogspot.com/2007/04/first-post.html#commentID"/>
    <link rel="self" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default/commentID"/>
    <link rel="edit" type="application/atom+xml" href="http://www.blogger.com/feeds/blogID/postID/comments/default/commentID"/>
    <thr:in-reply-to href="http://blogName.blogspot.com/2007/04/first-post.html" 
                     ref="tag:blogger.com,1999:blog-blogID.post-postID" 
                     source="http://www.blogger.com/feeds/posts/default/blogID"
                     type="text/html"/>
    <author>
      <name>Blog Author name</name>
      <email>blog_author@gmail.com</email>
      <uri>http://www.blogger.com/profile/userID</uri>
    </author>
    <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0' 
         href='http://blogName.blogspot.com/2007/04/first-post.html' 
         ref='tag:blogger.com,1999:blog-blogID.post-postID' 
         source='http://blogName.blogspot.com/feeds/posts/default/postID'
         type='text/html' />
  </entry>
</feed>

刪除留言

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

匯出格式

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

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

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

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

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

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

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

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

返回頁首