『协议』XML-RPC 协议规格说明

这篇文章提供所有实现XML-RPC协议所需要的内容。

 

---

一览

XML-RPC是一个工作在因特网上的远端程序调用（Remote Procedure Calling）协议。

XML-RPC消息是一个HTTP-POST请求（Request）。请求的主题是在XML中。一个在服务器上执行的程序和它返回的值也是使用XML来格式化的。

被终端调用的程序参数可以是标量（scalars）、数值、字符串、日期等；并且还可以是混合记录和列表结构。

示例

下面是一个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请求，我们允许URI帮助将请求导向到程序处理XML-RPC请求的代码处。如，/RPC2告诉服务器将请求导向到“RPC2”响应器。

一个用户代理(User-Agent)和主机(Host)必须被指定。

内容类型（Content-Type）必须是text/xml。

内容长度（Conteng-Length）必须被指定且必须正确。

负载（Payload）格式

payload是在xml中的一个简单的<methodCall>方法调用结构。

<methodCall>必须包括<methodName>子项，一个包括被调用方法的名字的字符串。这个字符串也许只是包括标识字符（大写或小写的A-Z）、数值字符（0-9）、下划线、点、冒号、斜线。这已经足够服务器云决定如何解释方法名了。

例如，方法名可以是一个包含执行引入请求（incoming request）脚本的文件名。它可以是数据库中的一个表的单元格名。或者它可以是被一个在层级式目录中的的一文件路径。

如果程序调用有参数，<methodCall>发源包括一个<params>参数子项。这个<params>子项能够包括任意数量的<param>，每一个<param>都有一个值。

标量（scalar）<value>值

<value>值可以是标量（scalar），类型如下表所示：

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>	ase64-encoded binary	eW91IGNhbid0IHJlYWQgdGhpcyE=

如果没有指定类型，类型就是字符串。

<struct>结构

一个值可以是<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>数组

值可以是<array>数组类型的。

一个<array>包括一个独立的<data>元素，这个元素可以包括任意多个<value>。

下面是一个四元素数组的示例：

<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>或任意的类型，包括上文描述过的<struct>。

响应（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成功码。

内容类型是text/xml。内容长度必须呈现且正确。

响应体是一个简单的XML结构<methodResponse>，它可以包括一个<params>，<params>可以包括一个独立的<value>。

<methodResponse>还可以包括一个<fault>。<fault>可以包括一个<value>。<value>可以包括一个包含有两个元素的<struct>，一个元素是<faultCode>，一个元素是<faultString>。

<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>

 

策略和目标

明文。这个协议的目标是在没有新的可以超越CGI接口的力量被提供时，制订一个可以跨越不同环境的兼容性的“根据”，防火墙软件可以看到内容类型是text/xml的POSTs。

可读。我们想要一个干净的可扩展的非常简单的格式。这使得一个HTML程序员能够看懂包括XML-RPC协议调用的文件、理解这个文件的用途以及可以修改它并让它在第一次或第二次尝试后工作起来成为了可能。

容易。我们想要它成为一个可以被很容易实现去快速在不同的环境与不同的操作系统中运行的协议。