XML-RPC规范(中文)（一）

 

概述

XML-RPC是基于Internet的远程过程调用协议。

一个XML-RPC消息就是一个HTTP-POST请求。请求的主体是XML格式。在服务器端过程执行后的返回结果同样也是XML格式。

过程调用的参数可以是scalars（标量）, numbers（数字）, strings（字符串）, dates（时间）等；也可以是复杂的结果集和列表结构体。

Request例子

下面是一个XML-RPC请求的例子：

 

POST /RPC2 HTTP/1.0

User-Agent: Frontier/5.1.2 (WinNT)

Host: betty.userland.com

Content-Type: text/xml

Content-length: 181

 

<?xml version="1.0"?>

<methodCall>

   <methodName>examples.getStateName</methodName>

   <params>

      <param>

         <value><i4>41</i4></value>

      </param>

   </params>

</methodCall>

 

Header必要条件

首行中的URI没有指定格式。例如，它可以为空，一个斜线，如果服务器只处理XML-RPC请求。但是，如果服务器处理混合HTTP请求（即除了XML-RPC外还提供其他的HTTP请求），要允许URI来帮助请求路由到处理XML-RPC请求的代码。（在上面的例子中，URI为/ RPC2，告诉服务器将请求路由到“RPC2”的响应者。）

User-Agent和Host是必须指定的。

Content-Type的值必须是text/xml。

Content-Length必须指定，并且必须是正确的。

Payload格式（Payload format）

有效负载是XML格式，一个<methodCall>结构。

<methodCall>必须包含一个字符串型的<methodName>子元素，用来表明被调用的方法名称。该字符串仅可能包含标示字符，大小写字母A到Z、数字0到9、下划线、点、冒号和斜线。至于怎么解释该字符串中的字符将完全由服务器端来决定。

例如，methodName可能是一个请求执行的脚本文件的名称，也可能是数据库表中列的名字，还可能是表示目录和文件层级结构的路径。

如果过程调用有参数，<methodCall>就必须包含一个<params>子元素。<params>可以包含任意个<param>元素，每个<param>有一个<value>子元素。

Scalar <value>s

<value>可能为标量，通过嵌套在类型标签中来指定值的类型，支持的类型如下表:

Tag	Type	Example
<i4> or <int>	four-byte signed integer	-12
<boolean>	0 (false) or 1 (true)	1
<string>	string	hello world
<double>	double-precision signed floating point number	-12.214
<dateTime.iso8601>	date/time	19980717T14:08:55
<base64>	base64-encoded binary	eW91IGNhbid0IHJlYWQgdGhpcyE=

如果没有指定类型，默认为字符串类型。

<struct>s

<value>也可以是<struct>类型。

一个<struct>包含若干个<member>，每个<member>包含一个<name>和一个<value>。

下面是一个包含两个元素的<struct>的例子：

<struct>

   <member>

      <name>lowerBound</name>

      <value><i4>18</i4></value>

   </member>

   <member>

      <name>upperBound</name>

      <value><i4>139</i4></value>

   </member>

</struct>

 

<struct>可以递归，任何<value>都可以包含一个<struct>或其他任何类型，包括后面将要说明的<array>。

<array>s

<value>也可以是<array>。<array>包含一个<data>元素。<data>可以包含任意个<value>。

下面是一个有4个元素的array：

<array>

   <data>

      <value><i4>12</i4></value>

      <value><string>Egypt</string></value>

      <value><boolean>0</boolean></value>

      <value><i4>-31</i4></value>

   </data>

</array>

 

<array>元素没有名字。可以包含混合类型就像上面的示例一样。<arrays>可以递归，其值可以是<array>或其他类型，包括上面说明的<strut>。

Response例子

下面是一个对XML - RPC请求响应的例子：

HTTP/1.1 200 OK

Connection: close

Content-Length: 158

Content-Type: text/xml

Date: Fri, 17 Jul 1998 19:55:08 GMT

Server: UserLand Frontier/5.1.2-WinNT

 

<?xml version="1.0"?>

<methodResponse>

   <params>

      <param>

         <value><string>South Dakota</string></value>

      </param>

   </params>

</methodResponse>

 

Response格式

除非出现底层操作错误，否则总是返回200 OK。

Content-Type的值必须是text/xml。Content-Length必须指定，并且必须是正确的。

响应主体是一个XML结构体，<methodResponse>包含一个<params>，<params>包含一个<param>,<param>包含一个<value>。

<methodResponse>也可能含有一个<fault>标签。<fault>的值为<struct>类型，<struct>有两个元素，一个名叫faultCode的<int>值和一个名叫faultString的<string>值。

但是，<methodResponse>不能同时包含<fault>和<params>。

Fault例子

HTTP/1.1 200 OK

Connection: close

Content-Length: 426

Content-Type: text/xml

Date: Fri, 17 Jul 1998 19:55:02 GMT

Server: UserLand Frontier/5.1.2-WinNT

 

<?xml version="1.0"?>

<methodResponse>

   <fault>

      <value>

         <struct>

            <member>

               <name>faultCode</name>

               <value><int>4</int></value>

            </member>

            <member>

               <name>faultString</name>

               <value><string>Too many parameters.</string></value>

            </member>

         </struct>

      </value>

   </fault>

</methodResponse>

 

战略目标（Strategies/Goals）

Firewalls. The goal of this protocol is to lay a compatible foundation across different environments, no new power is provided beyond the capabilities of the CGI interface. Firewall software can watch for POSTs whose Content-Type is text/xml.

防火墙，本协议的目标是满足不同环境的兼容性，没有提供超越CGI接口功能的新能力。防火墙可以检查Content-Type为text/xml 的Post请求。

Discoverability. We wanted a clean, extensible format that's very simple. It should be possible for an HTML coder to be able to look at a file containing an XML-RPC procedure call, understand what it's doing, and be able to modify it and have it work on the first or second try.

发现性，我们想要一个干净的，可扩展的，非常简单的格式。我们应该可以使用HTML编码器查看包含XML-RPC过程调用的文件，了解它做了什么，并能够在一、二次尝试修改后使其工作。

Easy to implement. We also wanted it to be an easy to implement protocol that could quickly be adapted to run in other environments or on other operating systems.

易于实现，我们还希望它成为一个易于实现的协议，可以快速适应在其他环境或其他操作系统中运行。