【转】基于XMLRPC的BloggerAPI学习

　 Luliang的mail2blog脚本，通过基于XML-RPC的BloggerAPI来实现的发布blog的功能。
　　BloggerAPI是一套程序接口，用以支持远程操作blog.这个规范现在的版本是1.0，是个试验版本和α版本。但是，规范的研发人员不再对BloggerAPI进一步地开发，他们正在制定一套新的、更稳定的API，新项目的名称为echo
.

　　虽然如此，了解一下这个bloggerAPI还是非常有意义的。一方面有很多语言提供了实现包，另一方面很blog工具也提供了相应的包，如MT。需要说明的是，BloggerAPI提供的功能太有限了，只定义了6个方法或函数，所以出了一个RFC叫 MetaWeblog API，对其进行了扩展。我看了一下，MT2.6.4就支持MetaWeblogAPI.
　　下面对二者进行简单地介绍，以后有机会，再跟echo比较一下。：）

BloggerAPI based on XML-RPC

1、方法列表

方法	说明
blogger.newPost	向批定的blog增加新的文章（post）,通常会在增加后即发布。
blogger.editPost	编辑一篇文章(post)，通常会在修改后发布。
blogger.getUsersBlogs	返回一个成员的所有文章的信息。
blogger.getUserInfo	鉴证一个用户并反回其信息（如userid,email等）
blogger.getTemplate	返回指定的blog的主要或文档索引模板
blogger.setTemplate	编辑指定的blog的主要或文档索引模板

2、blogger.newPost
参数说明

参数	说明
appkey (string)	发送这个post的程序的唯一标志
blogid (string)	这个post即将发送到的blog的标志
username (string)	有权post文章的用户名
password (string)	用户密码
content (string)	Post的内容
publish (boolean)	是否发布

示例：
请求XML-RPC调用的数据

POST /api/RPC2 HTTP/1.0
User-Agent: Java.Net Wa-Wa 2.0
Host: plant.blogger.com
Content-Type: text/xml
Content-length: 515
<?xml version="1.0"?>
<methodCall>
<methodName>blogger.newPost</methodName>
<params>
<param><value><string>C6CE3FFB3174106584CBB250C0B0519BF4E294</string></value></param>
<param><value><string>744145</string></value></param>
<param><value><string>ewilliams</string></value></param>
<param><value><string>secret</string></value></param>
<param><value><string>Today I had a peanut butter and pickle sandwich
for lunch. Do you like peanut-butter and pickle sandwiches? I do.
They're yummy. Please comment!</string></value></param>
<param><value><boolean>false</boolean></value></param>
</params>
</methodCall>

成功时的应答

HTTP/1.1 200 OK
Connection: close
Content-Length: 125
Content-Type: text/xml
Date: Mon, 6 Aug 20001 19:55:08 GMT
Server: Java.Net Wa-Wa/Linux
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>4515151</string></value>
</param>
</params>
</methodResponse>

失败时的应答

错误信息通过XML-RPC <methodResponse>及<fault> 项返回，包含着的 <struct> 有错误码和描述,这是由xml-rpc规范定义.
HTTP/1.1 200 OK
Connection: close
Content-Length: 225
Content-Type: text/xml
Date: Mon, 6 Aug 20001 19:55:08 GMT
Server: Java.Net Wa-Wa/Linux
<?xml version="1.0"?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>4</int></value>
</member>
<member>
<name>faultString</name>
<value><string>java.lang.Exception: java.lang.Exception: Error: AppKey is
invalid or inactive.</string></value>
</member>
</struct>
</value>
</fault>
</methodResponse>

3、blogger.editPost
参数说明

参数	说明
appkey (string)	发送这个post的程序的唯一标志
postid (string)	某篇post的唯一标志
username (string)	有权修改文章的用户名（作者或管理员）
password (string)	用户密码
content (string)	Post的内容
publish (boolean)	是否发布

4、blogger.getUserBlogs
参数说明

参数	说明
appkey (string)	发送这个post的程序的唯一标志
username (string)	用户名
password (string)	用户密码

成功应答示例

HTTP/1.1 200 OK
Connection: close
Content-Length: 125
Content-Type: text/xml
Date: Mon, 6 Aug 20001 19:55:08 GMT
Server: Java.Net Wa-Wa/Linux
<?xml version="1.0" encoding="ISO-8859-1"?>
<methodResponse>
<params>
<param>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>url</name>
<value>http://stuff.foo.com/biz</value>
</member>
<member>
<name>blogid</name>
<value>2997323</value>
</member>
<member>
<name>blogName</name>
<value>Blogger Biz Dev</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>url</name>
<value>http://www.blogger.com/</value>
</member>
<member>
<name>blogid</name>
<value>2723</value>
</member>
<member>
<name>blogName</name>
<value>Blogger News</value>
</member>
</struct>
<value>
<struct>
<member>
<name>url</name>
<value>http://www.geocities.com/rafting/</value>
</member>
<member>
<name>blogid</name>
<value>223723</value>
</member>
<member>
<name>blogName</name>
<value>RaftingBlog</value>
</member>
</struct>
</value>
</value>
</data>
</array>
</value>
</param>
</params>
</methodResponse>

5、blogger.getUserInfo
参数说明

参数	说明
appkey (string)	发送这个post的程序的唯一标志
username (string)	用户名
password (string)	用户密码

成功应答示例

HTTP/1.1 200 OK
Connection: close
Content-Length: 125
Content-Type: text/xml
Date: Mon, 6 Aug 20001 19:55:08 GMT
Server: Java.Net Wa-Wa/Linux
<?xml version="1.0" encoding="ISO-8859-1"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>nickname</name>
<value>Ev.</value>
</member>
<member>
<name>userid</name>
<value>1</value>
</member>
<member>
<name>url</name>
<value>http://www.evhead.com</value>
</member>
<member>
<name>email</name>
<value>ev@pyra.com</value>
</member>
<member>
<name>lastname</name>
<value>Williams</value>
</member>
<member>
<name>firstname</name>
<value>Evan</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>

6、blogger.getTemplate
参数说明

参数	说明
appkey (string)	发送这个post的程序的唯一标志
blogid (string)	这个post即将发送到的blog的标志
username (string)	有权post文章的用户名
password (string)	用户密码
templateType (string)	指定返回哪个模板，目前只能是 "main" 或 "archiveIndex".

成功时的应答，....表示此处内容被我省略。

<?xml version="1.0" encoding="ISO-8859-1"?<<methodResponse<<params<<param<<value<&lt;HTML<
&lt;HEAD<
&lt;TITLE<<$BlogTitle$<: <$BlogDescription$<</TITLE<

&lt;/BODY<
&lt;/HTML<

</value<</param<</params<</methodResponse<

7、blogger.setTemplate
参数说明

参数	说明
appkey (string)	发送这个post的程序的唯一标志
blogid (string)	这个post即将发送到的blog的标志
username (string)	有权post文章的用户名
password (string)	用户密码
template (string)	模板文本（通常是HTML）.必须包含 和标签，因它们需要发布。 （？我的mainindex里没有啊）
templateType (string)	指定返回哪个模板，目前只能是 "main" 或 "archiveIndex".

请求格式示例

POST /api/RPC2 HTTP/1.0
User-Agent: Java.Net Wa-Wa 2.0
Host: plant.blogger.com
Content-Type: text/xml
Content-length: 515
<?xml version="1.0"?>
<methodCall>
<methodName>blogger.setTemplate</methodName>
<params>
<param><value><string>C6CE3FFB3174106584CBB250C0B0519BF4E294</string></value></param>
<param><value><string>744154</string></value></param>
<param><value><string>ewilliams</string></value></param>
<param><value><string>secret</string></value></param>
<param><value><string>&lt;html&gt;&lt;head&gt;&lt;title&gt;&lt;$BlogTitle$&gt;&lt;/title&gt;&lt;/head&gt;&lt;body&gt;&lt;Blogger&gt;&lt;BlogDateHeader&gt;&lt;h1&gt;&lt;$BlogDateHeaderDate$&gt;&lt;/h1&gt;&lt;/BlogDateHeader&gt;&lt;$BlogItemBody$&gt;&lt;br&gt;&lt;/Blogger&gt;&lt;/body&gt;&lt;/html&gt;</string></value></param>
<param><value><string>main</string></value></param>
</params>
</methodCall>

MetaWeblog API

这个rfc的最新发布是在08/26/2003.
1、什么是MetaWeblog API
　　MetaWeblog API (MWA)是一套编程接口，允许外面的程序能取得和设置blog文章的文本或属性。它基于流行的XML-RPC通信协议,后者在很多的流行的开发环境中都有了实现的包。

2、MetaWeblog API与Blogger API 的关系
　　MetaWeblog API是对Blogger API增强, Blogger API只能取得或设置blog文章的文本内容(hedong问，能取得吗？).在2002年春天MWA面世,在此以前许多blog工具能存储许多扩展数据，但不能访问或编辑这些数据，因为没有一个通过的API。

　　到2003年夏天，在本文的写作期间，大部分流行的blog工具和编辑器，能同时支持Blogger API 和MetaWeblog API.
3、MetaWeblog API和 RSS 2.0 的关系

MetaWeblog API利用XML-RPC来描述一篇blog文章. 我们使用了RSS2.0中对一个项的术语来描述一篇blog文章的元数据，而不是重新发明一套。请参照RSS2.0中对文章的title, link 、description，author, comments, enclosure, guid等的定义或命名。 更进一步，由于RSS2.0是可扩展的，因而MetaWeblog API也是可扩展的. 我们在MWA中设计了一些用以表述属性和命名空间的约定。

4、基本函数(entry-points)
1)metaWeblog.newPost (blogid, username, password, struct, publish) returns string
2)metaWeblog.editPost (postid, username, password, struct, publish) returns true
3)metaWeblog.getPost (postid, username, password) returns struct
blogid, username, password 和publish参数的含义同 Blogger API. newPost返回的字符串表示post_id,同Blogger API定义的一样. 而那个struct就是MWA的精华所在。

5、数据结构
　　在newPost和editPost中，内容信息不再跟BloggerAPI中那是一个字符串，而是一个数据结构。这个数据结构的成员，就是rss2.0中定义的ITEM的元素。参见后面附表。

　　当一个元素有属性时，用一个数据结构（属性做成员）传递属性及其相应的值。如enclosure元素，用一个包含url, length 和type的结构传递属性。

对source元素，数据结构的成员为url 和name，前者为source的属性后者为source值。

对categories元素，传递一个字符串数组。在服务器端，如果传来的category不存在，则忽略不报错，且只保存有效的那些category.(hedong，好象没说domain属性的事啊）

　　服务器必须忽略所有不能理解的元素。

在调用 metaWeblog.newPost 或 metaWeblog.editPost时，如果数据结构中含有一个名叫flNotOnHomePage的 boolean 值，则主页不显示此文章而只在分类中显示。

6、其它函数
1）metaWeblog.newMediaObject (blogid, username, password, struct) returns struct
　　参数的struct，至少包含name, type and bits三个元素。
name是个字符串，可以用来作存储对象的文件名或用于对象列表的显示。它决定weblog如何引用这个对象。如果name和weblog已有一个对象重名，则替换掉已有的对象。
type是个字符串，表示对象的类型，必须是个标准的MIME类型，如 audio/mpeg or image/jpeg or video/quicktime.
bits是个base64-编码的二进制值，包含着对象的内容。
这个结构可以含有其它的元素，这些元素可以或不能被内容管理系统保存.
当调用失败时，抛出error.当成功时，返回的strcut中，至少要有一个元素url，用以指明这个对象如何被访问。其值只能是一个HTTP url或FTP url.
2）metaWeblog.getCategories (blogid, username, password) returns struct
返回的struct中，为每个分类提供一个子结构，子结构中至少包含三个元素：description, httpurl 和 rssurl.

3）metaWeblog.getRecentPosts (blogid, username, password, numberOfPosts) returns array of structs
　　返回是一个结构数组，盛放着最新发布的文章信息。每个结构的内容同metaWeblog.getPost返回内容相同.
　　numberOfPosts指明要取回的按发布时间倒序计数的文章数量，当值超过总文章数时，返回全部文章信息。

7、传送带属性的元素
　　除了enclosure和source元素有专门规定外，其它元素按下列规则处理：
1)如果一个元素有属性，则用一个struct来表示，各属性为struct的子元素。
2)如果一个元素同时有属性和值，则用一个一个struct来表示，各属性为struct的子元素，再增加一个叫_value的子元素，表示元素的值。这也就要求，元素的属性名不能为_value.

8、传送某命名空间的元素
　　RSS 2.0允许使用命名空间. 如果你要传送的元素是一个命名空间的一部分，那就在传递给 newPost 或 editPost 的struct中增加一个子struct,以指明命名空间的URL为名，以要传送的元素值为子元素。

9、说明
　　在MWA中不要明确要求传送appkey值，如果应用程序要传送appkey,则在struct中增加一个名为appkey的元素，并赋之以相关的值。

附表：RSS2.0中ITEM的元素列表　　

元素(Element)	描述(Description)	例子(Example)	重要性	属性
title	项(item)的标题	Venice Film Festival Tries to Quit Sinking	必备
link	项的URL	http://www.nytimes.com/2002/09/07/movies/07FEST.html	必备
description	项的大纲	Some of the most heated chatter at the Venice Film Festival this week was about the way that the arrival of the stars at the Palazzo del Cinema was being staged.	必备
author	该项作者的email	oprah@oxygen.net	可选
category	包含该项的一个或几个分类(catogory)	Simpsons Characters	可选	domain可选，指分类法的URL
comments	该项的评论(comments)页的URL	http://www.myblog.org/cgi-local/mt/mt-comments.cgi?entry_id=290	可选
enclosure	描述该附带的媒体对象		可选	url/length/type皆必备,type须是标准MIME类型
guid	项的唯一标志符串	http://inessential.com/2002/09/01.php#a2	可选	isPermaLink可选，默认为真，指明guid是否为一永久URL。
pubDate	项的发布时间	Sun, 19 May 2002 15:21:36 GMT	可选
source	该项来自的RSS道	Quotes of the Day	可选	Url必备

附：MWAAPI清单

1. metaWeblog.newPost (blogid, username, password, struct, publish) returns string
   
2. metaWeblog.editPost (postid, username, password, struct, publish) returns true
   
3. metaWeblog.getPost (postid, username, password) returns struct
   
4. metaWeblog.newMediaObject (blogid, username, password, struct) returns struct
   
5. metaWeblog.getCategories (blogid, username, password) returns struct
   
6. metaWeblog.getRecentPosts (blogid, username, password, numberOfPosts) returns array of structs