关于Bugzilla WebService接口

参考：http://www.bugzilla.org/docs/3.2/en/html/api/Bugzilla/WebService.html

http://www.bugzilla.org/docs/4.4/en/html/api/Bugzilla/WebService.html

刚翻译完就发现找到是老的api。。。

新版中支持json格式返回、并多了很多接口：

Server Types

Bugzilla::WebService::Server::XMLRPC

Bugzilla::WebService::Server::JSONRPC

WebService Modules

Bugzilla::WebService::Bug

Bugzilla::WebService::Bugzilla

Bugzilla::WebService::Classification

Bugzilla::WebService::Group

Bugzilla::WebService::Product

Bugzilla::WebService::User

API名称

Bugzilla::WebService - Bugzilla的Web Service接口

描述

这是外部程序想与Bugzilla发生交互的标准API，它提供了各模块的各种方式。当前访问该API的唯一方式是通过XML-RPC，相关标准可参看： http://www.xmlrpc.com/spec

Bugzilla WebServices的访问入口是Bugzilla安装目录中 xmlrpc.cgi 脚本文件。比如，如果你的 Bugzilla 位于 bugzilla.yourdomain.com，那么你的 XML-RPC 客户端就要访问 API : http://bugzilla.yourdomain.com/xmlrpc.cgi

方法调用

Bugzilla当前没有实现标准XML-RPC方法调用的扩展特性。方法以常规XML-RPC方式调用。方法以“packages”的形式进行分组，如Bug对应 Bugzilla::WebService::Bug。所以如果是 "get" in Bugzilla::WebService::Bug，在XML-RPC中应该是用Bug.get调用。

参数

除了标准的参数类型如int, string等外，XML-RPC还有两种数据结构 <struct> 及 <array>。

Structs

XML-RPC:

 <struct>
   <member>
     <name>fruit</name>
     <value><string>oranges</string></value>
   </member>
   <member>
     <name>vegetable</name>
     <value><string>lettuce</string></value>
   </member>
 </struct>

API文档里：

 { fruit => 'oranges', vegetable => 'lettuce' }

Arrays

以下示例代码中，[ 和 ] 用来代表数组的起止界定。

比如，XML-RPC中的数组

 <array>
   <data>
     <value><i4>1</i4></value>
     <value><i4>2</i4></value>
     <value><i4>3</i4></value>
   </data>
 </array>

在API文档里，会写成：

 [1, 2, 3]

Bugzilla WebService方法如何接收参数

所有的Bugzilla WebServices 函数以<struct>的形式接收参数。换句话说，所有函数都只接收单个参数，所有的参数都包含在这个参数中。API文档中列出的对应名称的参数意味着放在struct数据结构中。

帐号登陆

你可以使用 "login" in Bugzilla::WebService::User 接口来登陆 Bugzilla 账户。这会产生标准的HTTP cookies，在将来的调用中必须用到这个数据，所以你的XML-RPC客户端必须要能接收与发送cookies的处理能力。

Bugzilla_login and Bugzilla_password

Added in Bugzilla 3.6

You can specify Bugzilla_login and Bugzilla_password as arguments to any WebService method, and you will be logged in as that user if your credentials are correct. Here are the arguments you can specify to any WebService method to perform a login:

Bugzilla_login (string) - A user's login name.

Bugzilla_password (string) - That user's password.

Bugzilla_restrictlogin (boolean) - Optional. If true, then your login will only be valid for your IP address.

The Bugzilla_restrictlogin option is only used when you have also specified Bugzilla_login and Bugzilla_password.

Bugzilla_token

Added in Bugzilla 5.0 and backported to 4.4.3

You can specify Bugzilla_token as argument to any WebService method, and you will be logged in as that user if the token is correct. This is the token returned when calling User.login mentioned above.

Support for using login cookies for authentication has been dropped for security reasons.

方法稳定的、实验性的及不稳定的状态

Methods are marked STABLE if you can expect their parameters and return values not to change between versions of Bugzilla. You are best off always using methods markedSTABLE. We may add parameters and additional items to the return values, but your old code will always continue to work with any new changes we make. If we ever break aSTABLE interface, we'll post a big notice in the Release Notes, and it will only happen during a major new release.

Methods (or parts of methods) are marked EXPERIMENTAL if we believe they will be stable, but there's a slight chance that small parts will change in the future.

Certain parts of a method's description may be marked as UNSTABLE, in which case those parts are not guaranteed to stay the same between Bugzilla versions.

错误

如果某个webservice调用失败，它会抛出一个标准的XML-RPC错误。包括一个数字格式的错误代码，以及相应的描述文字。这些错误代码是固定的，不会因Bugzilla的版本变化而改变。

各种抛出的错误由那些函数的相应文档进行声明。如果你的代码中需要知道会抛出什么错误，用数字代码而不要去分析那些描述文字，因为各版本可能会有变化。

临时错误与重大错误

如果错误代码是大于0的数字，该错误就可以叫做临时错误，意味着是由于用户的输入引起的错误，而不是系统本身。

如果错误代码小于0，则该错误是致命性的，意味着是系统错误，可能需要联系管理员解决。

负数与正数错误不是对称的，比如有一个代号是302的错误，但不一定就对应有-302的错误。

未知错误

有时函数可能抛出具体含义的错误代码，这种情况下-32000代表系统重大错误，32000则代表是临时性错误。