為什么80%的碼農都做不了架構師?>>> ??
這篇文章提供所有實現XML-RPC協議所需要的內容。
?
一覽
XML-RPC是一個工作在因特網上的遠端程序調用(Remote Procedure Calling)協議。
XML-RPC消息是一個HTTP-POST請求(Request)。請求的主題是在XML中。一個在服務器上執行的程序和它返回的值也是使用XML來格式化的。
被終端調用的程序參數可以是標量(scalars)、數值、字符串、日期等;并且還可以是混合記錄和列表結構。
示例
下面是一個XML-RPC請求的例子:
1: POST /RPC2 HTTP/1.0
2: User-Agent: Frontier/5.1.2 (WinNT)
3: Host: betty.userland.com
4: Content-Type: text/xml
5: Content-length: 181
6:?
7: <?xml version="1.0"?>
8: <methodCall>
9: <methodName>examples.getStateName</methodName>
10: <params>
11: <param>
12: <value>
13: <i4>41</i4>
14: </value>
15: </param>
16: </params>
17: </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>元素的例子。
1: <struct>
2: <member>
3: <name>lowerBound</name>
4: <value>
5: <i4>18</i4>
6: </value>
7: </member>
8: <member>
9: <name>upperBound</name>
10: <value>
11: <i4>139</i4>
12: </value>
13: </member>
14: </struct>
<array>數組
值可以是<array>數組類型的。
一個<array>包括一個獨立的<data>元素,這個元素可以包括任意多個<value>。
下面是一個四元素數組的示例:
1: <array>
2: <data>
3: <value><i4>12</i4></value>
4: <value><string>Egypt</string></value>
5: <value><boolean>0</boolean></value>
6: <value><i4>-31</i4></value>
7: </data>
8: </array>
<array>元素沒有名字。
你可以在上面的示例中使用混合類型。
<arrays>是可以遞歸的,任何值可以包括一個<array>或任意的類型,包括上文描述過的<struct>。
響應(Response)示例
下面是一個對XML-RPC請求的響應示例:
1: HTTP/1.1 200 OK
2: Connection: close
3: Content-Length: 158
4: Content-Type: text/xml
5: Date: Fri, 17 Jul 1998 19:55:08 GMT
6: Server: UserLand Frontier/5.1.2-WinNT
7:?
8: <?xml version="1.0"?>
9: <methodResponse>
10: <params>
11: <param>
12: <value>
13: <string>South Dakota</string>
14: </value>
15: </param>
16: </params>
17: </methodResponse>
響應(Response)格式
除非有一個層等級的錯誤,不然總是會返回200成功碼。
內容類型是text/xml。內容長度必須呈現且正確。
響應體是一個簡單的XML結構<methodResponse>,它可以包括一個<params>,<params>可以包括一個獨立的<value>。
<methodResponse>還可以包括一個<fault>。<fault>可以包括一個<value>。<value>可以包括一個包含有兩個元素的<struct>,一個元素是<faultCode>,一個元素是<faultString>。
<methodResponse>可以不包括一個<fault>和<params>。
錯誤(Fault)示例
1: HTTP/1.1 200 OK
2: Connection: close
3: Content-Length: 426
4: Content-Type: text/xml
5: Date: Fri, 17 Jul 1998 19:55:02 GMT
6: Server: UserLand Frontier/5.1.2-WinNT
7:?
8: <?xml version="1.0"?>
9: <methodResponse>
10: <fault>
11: <value>
12: <struct>
13: <member>
14: <name>faultCode</name>
15: <value>
16: <int>4</int>
17: </value>
18: </member>
19: <member>
20: <name>faultString</name>
21: <value>
22: <string>Too many parameters.</string>
23: </value>
24: </member>
25: </struct>
26: </value>
27: </fault>
28: </methodResponse>
29:?
?
策略和目標
明文。這個協議的目標是在沒有新的可以超越CGI接口的力量被提供時,制訂一個可以跨越不同環境的兼容性的“根據”,防火墻軟件可以看到內容類型是text/xml的POSTs。
可讀。我們想要一個干凈的可擴展的非常簡單的格式。這使得一個HTML程序員能夠看懂包括XML-RPC協議調用的文件、理解這個文件的用途以及可以修改它并讓它在第一次或第二次嘗試后工作起來成為了可能。
容易。我們想要它成為一個可以被很容易實現去快速在不同的環境與不同的操作系統中運行的協議。