IDC资讯中心
6. 在http中使用soap
这一节讲述了如何在http中使用soap。把soap绑定到http，无论使用或不用http扩展框架，都有很大的好处：在利用soap的形式化和灵活性的同时，使用http种种丰富的特性。在http中携带soap消息，并不意味着soap改写了http已有的语义，而是将构建在http之上soap语义自然地对应到http语义。
soap自然地遵循http的请求/应答消息模型使得soap的请求和应答参数可以包含在http请求和应答中。注意，soap的中间节点与http的中间节点并不等同，即，不要期望一个根据http连接头中的域寻址到的http中间节点能够检查或处理http请求中的soap消息。
在http消息中包含soap实体时，按照rfc2376[3] http应用程序必须使用媒体类型 "text/xml"。
6.1 soap http请求
虽然soap可能与各种http请求方式相结合，但是绑定仅定义了在http post请求中包含soap消息。（第7节中描述了如何在rpc中使用soap，第6.3节描述了如何使用http扩展框架）
6.1.1 http头中soapaction域
一个http请求头中的soapaction域用来指出这是一个soap http请求，它的值是所要的uri。在格式、uri的特性和可解析性上没有任何限制。当http客户发出soap http请求时必须使用在http头中使用这个域。
soapaction = "soapaction" ":" [ <"> uri-reference <"> ]
uri-reference = <as defined in rfc 2396 [4]>
http头中soapaction域使服务器（如防火墙）能正确的过滤http中soap请求消息。如果这个域的值是空字符串（""），表示soap消息的目标就是http请求的uri。这个域没有值表示没有soap消息的目标的信息。
例子:
soapaction: "http://electrocommerce.org/abc#mymessage"
soapaction: "myapp.sdl"
soapaction: ""
soapaction:
6.2 soap http应答
soap http遵循http 中表示通信状态信息的http状态码的语义。例如，2xx状态码表示这个包含了soap组件的客户请求已经被成功的收到，理解和接受。
在处理请求时如果发生错误，soap http服务器必须发出应答http 500 "internal server error"，并在这个应答中包含一个soap fault元素（见4.4节）表示这个soap处理错误。
6.3 http扩展框架
一个soap消息可以与http扩展框架 [6]一起使用以区分是否有soap http请求和它的目标。
是使用扩展框架或是普通的http关系到通信各方的策略和能力。通过使用一个必需的扩展声明和"m-"http方法名前缀，客户可以强制使用http扩展框架。服务器可以使用http状态码510 "not extended"强制使用http扩展框架。也就是说，使用一个额外的来回，任何一方都可以发现另一方的策略并依照执行。
用来表示soap使用了扩展框架的扩展标志符是：
http://schemas.xmlsoap.org/soap/envelope/
6.4 soap http举例
例3 使用post的soap http
post /stockquote http/1.1
content-type: text/xml; charset="utf-8"
content-length: nnnn
soapaction: "http://electrocommerce.org/abc#mymessage"
<soap-env:envelope…
http/1.1 200 ok
content-type: text/xml; charset="utf-8"
content-length: nnnn
<soap-env:envelope…
例4 使用扩展框架的soap http
m-post /stockquote http/1.1
man: "http://schemas.xmlsoap.org/soap/envelope/"; ns=nnnn
content-type: text/xml; charset="utf-8"
content-length: nnnn
nnnn-soapaction: "http://electrocommerce.org/abc#mymessage"
<soap-env:envelope…
http/1.1 200 ok
ext:
content-type: text/xml; charset="utf-8"
content-length: nnnn
<soap-env:envelope…
7. 在rpc中使用soap
设计soap的目的之一就是利用xml的扩展性和灵活性来封装和交换rpc调用。这一节定义了远程过程调用和应答的统一表示形式。
虽然可以预计到这种表示形式最可能被用于与第5节中定义的编码方式相结合，但也可能有其它的表示形式。soap的encodingstyle属性（见4.3.2节）可以用来表明方法调用和应答都使用这一节所指定的表示方式。
在rpc中使用soap和soap协议绑定（见第6节）是紧密相关的。在使用http作为绑定协议时，一个rpc调用自然地映射到一个http请求，rpc应答同样映射到http应答。但是，在rpc中使用soap并不限于绑定http协议。
要进行方法调用，以下的信息是必需的：
目标对象的uri
方法名
方法signature（可选）
方法的参数
头数据（可选）
soap依靠协议绑定提供传送uri的机制。例如，对http来说，请求的uri指出了调用的来源。除了必须是一个合法的uri之外，soap对一个地址的格式没有任何限制。（更多uri的信息参见 [4]）
7.1 rpc和soap体
rpc方法调用和应答都包含在soap body元素中（见4.3节），它们使用如下的表示形式：
一个方法调用用一个结构表示
一个方法调用被看作一个单个的结构，每个[in]和[in/out]参数有一个accessor。结构的名和类型与方法相同。
每个[in]和[in/out]参数都被看作一个accessor，这个accessor的名和类型与参数的名和类型相对应。它们的出现顺序和方法中定义的参数顺序相同。
一个方法应答用一个结构表示。
一个方法应答被看作一个单个的结构，返回值和每个[in]和[in/out]参数有一个accessor。第一个accessor是返回值，之后是参数accessor，参数accessor的出现顺序和方法中定义的参数顺序相同。
每个参数accessor的名称和类型与参数的名称和类型相对应。返回值accessor的名称并不重要。同样，结构的名称也不重要，不过，通常在方法名称的后面加上字符串"response"作为结构的名称。
方法错误使用soap fault元素（见4.4节）表示。如果绑定的协议有额外的规则表示错误，则这些规则也必须要遵从。
正如上面所述，方法调用和应答结构可以按照第5节中规则编码，或者用encodingstyle属性（见4.1.1节）指定编码方式。
应用程序可以处理缺少参数的请求，但是可能返回一个错误。
因为返回结果表示调用成功，错误表示调用失败，所以，在方法应答中同时包含返回结果和错误是错误的。
7.2 rpc和soap头
在rpc编码中，可能会有与方法请求有关但不是正规的方法signature的附加信息。如果这样，它必须作为soap头元素的子元素。
使用这种头元素的一个例子是在消息中传递事务id。由于事务id不是方法signature的一部分，通常由底层的组件而不是应用程序代码控制，所以没有一种直接的方法在调用中传递这个必要的信息。通过在头中添加一个给定名字的条目，接收方的事务管理器就可以析取这个事务id，而且不影响远程过程调用的代码。
8. 安全性考虑
这篇文档中没有涉及完整性和保密性，这些问题将在以后的版本中描述。
9. 参考文献
[1] s. bradner, "the internet standards process — revision 3", rfc2026, harvard university, october 1996
[2] s. bradner, "key words for use in rfcs to indicate requirement levels", rfc 2119, harvard university, march 1997
[3] e. whitehead, m. murata, "xml media types", rfc2376, uc irvine, fuji xerox info. systems, july 1998
[4] t. berners-lee, r. fielding, l. masinter, "uniform resource identifiers (uri): generic syntax", rfc 2396, mit/lcs, u.c. irvine, xerox corporation, august 1998.
[5] r. fielding, j. gettys, j. c. mogul, h. frystyk, t. berners-lee, "hypertext transfer protocol — http/1.1", rfc 2616, u.c. irvine, dec w3c/mit, dec, w3c/mit, w3c/mit, january 1997
[6] h. nielsen, p. leach, s. lawrence, "an http extension framework", rfc 2774, microsoft, microsoft, agranat systems
[7] w3c recommendation "the xml specification"
[8] w3c recommendation "namespaces in xml"
[9] w3c working draft "xml linking language". this is work in progress.
[10] w3c working draft "xml schema part 1: structures". this is work in progress.
[11] w3c working draft "xml schema part 2: datatypes". this is work in progress.
[12] transfer syntax ndr, in "dce 1.1: remote procedure call"
[13] n. freed, n. borenstein, "multipurpose internet mail extensions (mime) part one: format of internet message bodies", rfc2045, innosoft, first virtual, november 1996
a. soap封装举例
a.1 请求编码举例
例5 类似于例1，但有一个必要的头
post /stockquote http/1.1
host: www.stockquoteserver.com
content-type: text/xml; charset="utf-8"
content-length: nnnn
soapaction: "some-uri"
<soap-env:envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingstyle="http://schemas.xmlsoap.org/soap/encoding/"/>
<soap-env:header>
<t:transaction
xmlns:t="some-uri"
soap-env:mustunderstand="1">
5
</t:transaction>
</soap-env:header>
<soap-env:body>
<m:getlasttradeprice xmlns:m="some-uri">
<symbol>def</symbol>
</m:getlasttradeprice>
</soap-env:body>
</soap-env:envelope>
例6 类似于例1，但有多个请求参数
post /stockquote http/1.1
host: www.stockquoteserver.com
content-type: text/xml; charset="utf-8"
content-length: nnnn
soapaction: "some-uri"
<soap-env:envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingstyle="http://schemas.xmlsoap.org/soap/encoding/"/>
<soap-env:body>
<m:getlasttradepricedetailed
xmlns:m="some-uri">
<symbol>def</symbol>
<company>def corp</company>
<price>34.1</price>
</m:getlasttradepricedetailed>
</soap-env:body>
</soap-env:envelope>
a.2 应答编码举例
例7 与例2类似，但有必要的头部
http/1.1 200 ok
content-type: text/xml; charset="utf-8"
content-length: nnnn
<soap-env:envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingstyle="http://schemas.xmlsoap.org/soap/encoding/"/>
<soap-env:header>
<t:transaction
xmlns:t="some-uri"
xsi:type="xsd:int" mustunderstand="1">
5
</t:transaction>
</soap-env:header>
<soap-env:body>
<m:getlasttradepriceresponse
xmlns:m="some-uri">
<price>34.5</price>
</m:getlasttradepriceresponse>
</soap-env:body>
</soap-env:envelope>
例8 与例2类似，但有一个结构
http/1.1 200 ok
content-type: text/xml; charset="utf-8"
content-length: nnnn
<soap-env:envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingstyle="http://schemas.xmlsoap.org/soap/encoding/"/>
<soap-env:body>
<m:getlasttradepriceresponse
xmlns:m="some-uri">
<priceandvolume>
<lasttradeprice>
34.5
</lasttradeprice>
<dayvolume>
10000
</dayvolume>
</priceandvolume>
</m:getlasttradepriceresponse>
</soap-env:body>
</soap-env:envelope>
例9 与例2类似，但处理必要的头出错
http/1.1 500 internal server error
content-type: text/xml; charset="utf-8"
content-length: nnnn
<soap-env:envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:body>
<soap-env:fault>
<faultcode>soap-env:mustunderstand</faultcode>
<faultstring>soap must understand error</faultstring>
</soap-env:fault>
</soap-env:body>
</soap-env:envelope>
例10 与例2类似，但处理body出错
http/1.1 500 internal server error
content-type: text/xml; charset="utf-8"
content-length: nnnn
<soap-env:envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:body>
<soap-env:fault>
<faultcode>soap-env:server</faultcode>
<faultstring>server error</faultstring>
<detail>
<e:myfaultdetails xmlns:e="some-uri">
<message>
my application didnt work
</message>
<errorcode>
1001
</errorcode>
</e:myfaultdetails>
</detail>
</soap-env:fault>
</soap-env:body>
</soap-env:envelope>
