重要事項:這是本頁面的舊版。如要使用最新版本,請使用左側的 navbar 中的連結。
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 指令列公用程式 curl
或 wget
很實用;如需更多資訊,請參閱這些公用程式的手冊頁面。
如需 Blogger Data API 參考資訊,請參閱Protocol 參考指南。
開始使用
建立 Blogger 帳戶
建議您註冊 Blogger 帳戶進行測試。Blogger 使用 Google 帳戶,因此只要您已有 Google 帳戶,即可開始使用。
向 Blogger 服務進行驗證
您可以使用 Blogger Data API 存取公開和私人動態消息。公開動態饋給不需要任何驗證,但為唯讀。如果您想修改網誌,則您的用戶端必須先驗證,才能要求私人動態饋給。可使用以下任一方法進行驗證:AuthSub 代理驗證或 ClientLogin 使用者名稱/密碼驗證。
如要進一步瞭解一般使用 Google Data API 的驗證方式,請參閱驗證說明文件。
本文件後續部分的大部分範例都假設您會提供適當的驗證資訊。
AuthSub Proxy 驗證
需要對使用者進行 Google 帳戶驗證的網頁應用程式,會使用 AuthSub 代理驗證。網站操作員和用戶端程式碼無法存取 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
,因此您可以使用單次使用權杖,透過呼叫 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 要求範例,其中包含您可能會傳送給 Blogger 的不安全權杖:
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
主體應包含一組查詢參數,這些參數看起來就像使用 application/x-www-form-urlencoded
內容類型的 HTML 表單傳遞的參數。這些參數如下:
- 電子郵件
- 使用者的電子郵件地址。
- Passwd
- 使用者的密碼。
- 服務
- Blogger 服務名稱為
blogger
。(如需其他服務名稱,請參閱服務名稱清單)。 - accountType
- 使用 Blogger API 時,應一律將這個屬性設為
GOOGLE
。如果未設定這個參數,則使用者將無法透過 G Suite 帳戶存取應用程式。 - 來源
- 識別用戶端應用程式。應採用 companyName-applicationName-versionID 的格式。範例使用
exampleCo-exampleApp-1
這個名稱。
如要進一步瞭解參數,請參閱「已安裝應用程式的驗證」說明文件。
如果驗證要求失敗,伺服器會傳回 HTTP 403 Forbidden
狀態碼。
如果成功,伺服器會傳回 HTTP 200 OK
狀態碼,並在回應主體中加上三個長的英數字元碼:SID、LSID 和 Auth。Auth 值是您會隨後透過各項要求傳送至 Blogger 的授權權杖,因此請保留該值的副本。您可以忽略 SID 和 LSID 值。
由於所有私人動態消息要求都需要驗證,因此您必須在與 Blogger 的所有後續互動中,使用下列格式設定授權標頭:
Authorization: GoogleLogin auth=yourAuthToken
其中 yourAuthToken
是 ClientLogin 要求傳回的驗證字串。
如要進一步瞭解 ClientLogin 驗證,包括要求和回應範例,請參閱「已安裝應用程式的驗證」說明文件。
注意:請在特定工作階段中,針對所有要求使用相同的符記;不要為每項 Blogger 要求取得新的符記。
注意:如 ClientLogin 說明文件所述,驗證要求可能會失敗,並要求人機驗證 (CAPTCHA) 挑戰。如果您希望 Google 發出並處理人機驗證挑戰,請將使用者導向 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger
(而非 ClientLogin 說明文件中提供的人機驗證處理網址)。
擷取網誌清單
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
要求的主體中。接著,在 metafeed 中找出網誌的文章網址,方法是找出 <link>
元素,其中 rel
屬性結尾為 #post
。網誌的文章網址會以此元素的 href
屬性提供,格式如下:
http://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://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 公開動態饋給,無須驗證。因此,從公開網誌擷取網誌文章時,您不需要設定授權參數。
擷取所有網誌文章
如要擷取使用者的貼文,請向網誌的動態饋給網址傳送 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'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></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-min
和 published-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-min
和 updated-max
參數,取得指定範圍內所有更新的網誌文章。不過請注意,除非 orderby
參數也設為 updated
,否則系統會忽略這些參數。
Blogger Data API 支援下列查詢參數:
- alt
- 要傳回的動態饋給類型,例如
atom
(預設) 或rss
。 - /category
- 指定用於篩選動態饋給結果的類別 (也稱為標籤)。舉例來說,
http://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
,否則系統會忽略這些查詢參數。
如要進一步瞭解查詢參數,請參閱 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'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></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 格式,請參閱Protocol 參考指南。