SOAP version 1.2 中文手冊5

6. 在HTTP中使用SOAP

本节描述了如何在使用或不使用HTTP Extension Framework的前提下将SOAP与HTTP的协同工作机制。将SOAP绑定在HTTP上可以利用HTTP丰富的特性集，提供使用SOAP形式方法和分布适应性的优点。将SOAP在HTTP上传输并不以为着SOAP可以完全超越HTTP的语义，更恰当的描述应当是SOAP的语义通过HTTP的映射而很自然地成为HTTP的语义。

SOAP很自然地利用HTTP的请求/响应消息模型，将SOAP请求的参数放在HTTP请求里，而将SOAP响应的参数放在HTTP响应里面。注意，无论如何，SOAP的中间介与HTTP中间介是不同的。也就是说，根据HTTP Connection头字段来寻址的HTTP中间介一般并不能来处理HTTP请求中的SOAP实体体。

当需要将SOAP消息体包含在HTTP消息中时，HTTP应用程序必须依照RFC2376[3]使用媒体类型“text/xml”。

6.1 SOAP HTTP请求

虽然SOAP可以和多种HTTP请求方法联合使用，但这里的绑定只定义了SOAP是如何在HTTP Post请求中传输的。(可参阅section 7了解如何在RPC中使用SOAP，以及section 6.3如何使用HTTP Extension Framework)

6.1.1 HTTP Header中的SOAPAction字段

SOAPAction HTTP请求头字段(header field)可以用于指示SOAP HTTP请求的目的。它的值是一个标识该目的的URI。SOAP对于格式上并没有严格的限制，同时对URI的描述以及是否要是可解析的都没有严格的限制。当发出SOAP HTTP请求时，HTTP客户必须使用该头字段。

SOAPAction头字段的存在及其内容可以被服务器例如防火墙用于在HTTP中过滤SOAP请求消息。当该字段的值为空字符串( “”)时，则意味着SOAP消息的目的由HTTP Request-URI来提供。而如果没有值则表示对消息的目的没有指示。

例如:

SOAPAction: "http://electrocommerce.org/abc#MyMessage"
SOAPAction: "myapp.sdl"
SOAPAction: ""
SOAPAction:

6.2 SOAP HTTP响应

在HTTP之上的SOAP遵从用于在HTTP中表示通讯状态的HTTP状态代码的语义。例如，2xx状态代码表明这是客户端包含SOAP构件的请求被成功的接收、理解和接受等等。

当处理请求的时候发生SOAP错误的时候，SOAP HTTP服务器必须发出一个HTTP 500 “Internal Server Error”响应同时在包含于该响应的SOAP消息中应包含一个SOAP Fault元素(参阅 section 4.4)来指明SOAP处理的错误。

6.3 HTTP扩展框架

SOAP消息可以与HTTP Extension Framework[6]一起使用来标识SOAP HTTP请求的出现和意图。

是使用Extension Framework还是使用简单HTTP对于通讯各方而言是一个策略及能力的问题。客户端可以通过一个强制扩展声明以及一个“M-”HTTP方法名前缀来强制使用HTTP Extension Framwork。服务器端可以通过使用 510 “Not Extended” HTTP状态代码来强制使用HTTP Extension Framework。也就是说，通过一次额外的环游，每个通讯方都可以检测到其他通讯方和因此的动作。

用于使用Extension Framework标识SOAP的扩展标识是:

http://www.w3.org/2001/06/soap-envelope

6.4 SOAP HTTP示例

POST /StockQuote HTTP/1.1
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://electrocommerce.org/abc#MyMessage"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>

M-POST /StockQuote HTTP/1.1
Man: "http://www.w3.org/2001/06/soap-envelope"; ns=NNNN
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
NNNN-SOAPAction: "http://electrocommerce.org/abc#MyMessage"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>

HTTP/1.1 200 OK
Ext:
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>

7. 在RPC中使用SOAP

SOAP的一个设计目标就是要利用XML的可扩展性和可伸缩性来包装和交换RPC调用。本节定义了一个统一的远程过程调用和响应的表示。

其实我们也可以预想到在RPC环境下的表示很可能是与在其他表示中定义的编码风格结合。SOAP encodingStyle属性(参阅 section 4.3.2)可以被用于指明在本节表示中使用的方法调用/响应的编码风格。

在RPC中使用SOAP与SOAP协议绑定(参阅 section 6)基本是正交的。在使用HTTP作为SOAP协议绑定媒介的情况下，一个RPC调用可以很自然地映射到一个HTTP请求，而RPC响应则可以映射到HTTP响应。无论如何，使用SOAP方式的RPC并不限于HTTP协议绑定。

为实施一个方法调用，需要以下信息:

• 目标SOAP结点的URI

• 方法名

• 可选的方法或过程的特征

• 方法或过程的参数

• 可选的头数据

 SOAP依赖协议绑定来提供传送URI的机制。例如，对HTTP而言，请求URI指明了与该调用相对应的资源。除要求该URI是合法的以外，SOAP对于该地址没有任何限制(参阅[4]以获得URI的更多信息)。

7.1 RPC和SOAP Body

RPC调用和响应都是在SOAP Body元素(参阅 section 4.3)中传送，使用如下表示方式:

• 一个方法调用被建模成一个结构struct。

• 该方法调用显示为一个简单结构struct，包含每个[in]或[in/out]参数的存取标识。该结构的名和类型可使用过程或方法的名来标识。

• 每个[in]或[in/out]参数都被表示为一个存取标识，该存取标识的名和类型都对应于相应参数的名和类型。他们的次序也是按照原来RPC中的次序。

• 一个方法响应被建模成一个结构struct。

• 该方法响应显示为一个简单结构struct，包含每个[out]或[in/out]参数的存取标识。而第一个存取标识是返回值，而随后则是按照原来次序的返回参数。

• 每个[out]或[in/out]参数都被表示为一个存取标识，该存取标识的名和类型都对应于相应参数的名和类型。返回值的存取标识名并没有多少语义。同样的，结构的名也并没有多少语义。当然，无论如何，在添加了“Response”字串的方法名后，要有一个约定来命名它。

• 方法调用出错应使用SOAP Fault元素来编码(餐饮 section 4.4)。如果一个绑定协议对于错误表达还有额外规则，那么这些规则都应当被遵守。

就象先前表述的那样，方法和响应的结构可以使用在section 5中定义的规则来编码，也可以使用在encodingStyle属性中描述的其他编码(参阅 section 4.1.1)。

应用程序可以处理漏写参数的请求不过也可以返回一个错误。

因为在响应中若包含“result”则表明成功，若包含“fault”则表明失败，所以如果方法响应中同时包含了“result”和“fault”则是错误的。

7.2 RPC和SOAP Header

对于那些并非是方法的正式调用数据部分，而是方法请求编码相关的一些额外信息，也可以在RPC编码中表示。如果这样，它必须作为SOAP Header元素的一个子元素来描述。

对于使用header元素的一个例子是在消息中传送一个事务ID。事务ID并不是调用参数表中的一员，它一般是要被下层构件所处理而不仅仅是一个应用程序ID，而这里并没有一个直接的方法在调用中传送这一需要的信息。通过在头上加一个条目并赋予它一个固定的名字，接收方的事务管理器就可以将该事务ID抽取出来，同时就可以在不影响远程过程调用的代码的前提下使用它。

8. 安全机制的考虑

在本文档中并不包含完整性和私密性保护的方法的描述。这些问题将在本文档的以后版本中详细说明。

9. 参考文献

A. SOAP Envelope Examples

A.1 Sample Encoding of Call Requests

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.org/2001/06/quotes"

<env:Envelope
  xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Header>
       <t:Transaction
           xmlns:t="http://example.org/2001/06/tx"
           env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
           env:mustUnderstand="1" >
               5
       </t:Transaction>
   </env:Header>
   <env:Body >
       <m:GetLastTradePrice 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <m:symbol>DEF</m:symbol>
       </m:GetLastTradePrice>
   </env:Body>
</env:Envelope>

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.org/2001/06/quotes"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Body>
       <m:GetLastTradePriceDetailed 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <Symbol>DEF</Symbol>
           <Company>DEF Corp</Company>
           <Price>34.1</Price>
       </m:GetLastTradePriceDetailed>
   </env:Body>
</env:Envelope>

A.2 Sample Encoding of Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Header>
       <t:Transaction xmlns:t="http://example.org/2001/06/tx"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xmlns:xs="http://www.w3.org/2001/XMLSchema"
                      xsi:type="xs:int" 
                      env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
                      env:mustUnderstand="1" >
           5
       </t:Transaction>
   </env:Header>
   <env:Body>
       <m:GetLastTradePriceResponse 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <Price>34.5</Price>
       </m:GetLastTradePriceResponse>
   </env:Body>
</env:Envelope>

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Body>
       <m:GetLastTradePriceResponse 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <PriceAndVolume>
               <LastTradePrice>34.5</LastTradePrice>
               <DayVolume>10000</DayVolume>
           </PriceAndVolume>
       </m:GetLastTradePriceResponse>
   </env:Body>
</env:Envelope>

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope">
   <env:Body>
       <env:Fault>
           <faultcode>env:MustUnderstand</faultcode>
           <faultstring>SOAP Must Understand Error</faultstring>
       </env:Fault>
   </env:Body>
</env:Envelope>

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
  <env:Body>
    <env:Fault>
      <faultcode>env:Server</faultcode>
      <faultstring>Server Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://example.org/2001/06/faults" >
          <message>My application didn't work</message>
          <errorcode>1001</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

B. Acknowledgements

This document is the work of the W3C XML Protocol Working Group.

Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser al Safadi (Philips Research), Vidur Apparao (Netscape), Don Box (DevelopMentor), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Michael Champion (Software AG), David Clay (Oracle), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Ron Daniel (Interwoven), Glen Daniels (Allaire), Doug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE Corporation), Frank DeRose (TIBCO Software, Inc.), Brian Eisenberg (Data Channel), David Ezell (Hewlett-Packard), James Falek (TIBCO Software, Inc.), David Fallside (IBM), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Dietmar Gaertner (Software AG), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Martin Gudgin (Develop Mentor), Hugo Haas (W3C), Marc Hadley (Sun Microsystems), Mark Hale (Interwoven), Randy Hall (Intel), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Compaq), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.), Scott Isaacson (Novell, Inc.), Kazunori Iwasa (Fujitsu Software Corporation), Murali Janakiraman (Rogue Wave), Mario Jeckle (Daimler-Chrysler Research and Technology), Eric Jenkins (Engenia Software), Mark Jones (AT&T), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX s.r.o.), Alan Kropp (Epicentric), Yves Lafon (W3C), Tony Lee (Vitria Technology Inc.), Michah Lerner (AT&T), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Nilo Mitra (Ericsson Research Canada), Jean-Jacques Moreau (Canon), Masahiko Narita (Fujitsu Software Corporation), Mark Needleman (Data Research Associates), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), Mark Nottingham (Akamai Technologies), David Orchard (JamCracker), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Andreas Riegg (Daimler-Chrysler Research and Technology), Hervé Ruellan (Canon), Marwan Sabbouh (MITRE Corporation), Shane Sesta (Active Data Exchange), Miroslav Simek (IDOOX s.r.o.), Simeon Simeonov (Allaire), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Randy Waldrop (WebMethods), Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett-Packard), Amr Yassin (Philips Research) and Dick Brooks (Group 8760). Previous members were: Eric Fedok (Active Data Exchange) Susan Yee (Active Data Exchange) Alex Milowski (Lexica), Bill Anderson (Xerox), Ed Mooney (Sun Microsystems), Mary Holstege (Calico Commerce), Rekha Nagarajan (Calico Commerce), John Evdemon (XML Solutions), Kevin Mitchell (XML Solutions), Yan Xu (DataChannel) Mike Dierken (DataChannel) Julian Kumar (Epicentric) Miles Chaston (Epicentric) Bjoern Heckel (Epicentric) Dean Moses (Epicentric) Michael Freeman (Engenia Software) Jim Hughes (Fujitsu Software Corporation) Francisco Cubera (IBM), Murray Maloney (Commerce One), Krishna Sankar (Cisco), Steve Hole (MessagingDirect Ltd.) John-Paul Sicotte (MessagingDirect Ltd.) Vilhelm Rosenqvist (NCR) Lew Shannon (NCR) Henry Lowe (OMG) Jim Trezzo (Oracle) Peter Lecuyer (Progress Software) Andrew Eisenberg (Progress Software) David Cleary (Progress Software) George Scott (Tradia Inc.) Erin Hoffman (Tradia Inc.) Conleth O'Connell (Vignette) Waqar Sadiq (Vitria Technology Inc.) Tom Breuel (Xerox) David Webber (XMLGlobal Technologies) Matthew MacKenzie (XMLGlobal Technologies) and Mark Baker (Sun Microsystems).

This document is based on the SOAP/1.1 specification whose authors were: Don Box (Develop Mentor), David Ehnebuske (IBM), Gopal Kakivaya (Microsoft Corp.), Andrew Layman (Microsoft Corp.) Noah Mendelsohn (Lotus Development Corp.), Henrik Frystyk Nielsen (Microsoft Corp.), Satish Thatte (Microsoft Corp.) and Dave Winer (UserLand Software, Inc.).

We also wish to thank all the people who have contributed to discussions on [email protected].

C. Version Transition From SOAP/1.1 to SOAP Version 1.2

EdNote: The scope of the mechanism provided in this section is for transition between SOAP/1.1 and SOAP version 1.2. The Working Group is considering providing a more general transition mechanism that can apply to any version.  Such a general mechanism may or may not be the mechanism provided here depending on whether it is deemed applicable.

The SOAP/1.1 specification says the following on versioning in section 4.1.2:

"SOAP does not define a traditional versioning model based on major and minor version numbers. A SOAP message MUST have an Envelope element associated with the "http://schemas.xmlsoap.org/soap/envelope/" namespace. If a message is received by a SOAP application in which the SOAP Envelope element is associated with a different namespace, the application MUST treat this as a version error and discard the message. If the message is received through a request/response protocol such as HTTP, the application MUST respond with a SOAP VersionMismatch faultcode message (see section 4.4) using the SOAP "http://schemas.xmlsoap.org/soap/envelope/" namespace."

That is, rather than a versioning model based on shortnames (typically version numbers), SOAP uses a declarative extension model which allows a sender to include the desired features within the SOAP envelope construct. SOAP says nothing about the granularity of extensions nor how extensions may or may not affect the basic SOAP processing model. It is entirely up to extension designers be it either in a central or a decentralized manner to determine which features become SOAP extensions.

The SOAP extensibility model is based on the following four basic assumptions:

1. SOAP versioning is directed only at the SOAP envelope. It explicitly does not address versioning of blocks, encodings, protocol bindings, or otherwise.
2. A SOAP node must determine whether it supports the version of a SOAP message on a per message basis. In the following, "support" means understanding the semantics of the envelope version identified by the QName of the Envelope element:
   • A SOAP node receiving an envelope that it doesn't support must not attempt to process the message according to any other processing rules regardless of other up- or downstream SOAP nodes.
   • A SOAP node may provide support for multiple envelope versions. However, when processing a message a SOAP node must use the semantics defined by the version of that message.
3. It is essential that the envelope remains stable over time and that new features are added using the SOAP extensibility mechanism. Changing the envelope inherently affects interoperability, adds complexity, and requires central control of extensions -- all of which directly conflicts with the SOAP requirements.
4. No versioning model or extensibility model can prevent buggy implementations. Even though significant work has been going into clarifying the SOAP processing model, there is no guarantee that a SOAP 1.2 implementation will behave correctly. Only extensive testing within the SOAP community and design simplicity at the core can help prevent/catch bugs.

The rules for dealing with the possible SOAP/1.1 and SOAP Version 1.2 interactions are as follows:

1. Because of the SOAP/1.1 rules, a compliant SOAP/1.1 node receiving a SOAP Version 1.2 message will generate a VersionMismatch SOAP fault using an envelope qualified by the "http://schemas.xmlsoap.org/soap/envelope/" namespace identifier.
2. A SOAP Version 1.2 node receiving a SOAP/1.1 message may either process the message as SOAP/1.1 or generate a SOAP VersionMismatch fault using the "http://schemas.xmlsoap.org/soap/envelope/" namespace identifier. As part of the SOAP VersionMismatch fault, a SOAP Version 1.2 node should include the list of envelope versions that it supports using the SOAP upgrade extension identified by the "http://www.w3.org/2001/06/soap-upgrade" identifier.

The upgrade extension contains an ordered list of namespace identifiers of SOAP envelopes that the SOAP node supports in the order most to least preferred. Following is an example of a VersionMismatch fault generated by a SOAP Version 1.2 node including the SOAP upgrade extension:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header>
    <V:Upgrade xmlns:V="http://www.w3.org/2001/06/soap-upgrade">
      <envelope qname="ns1:Envelope" xmlns:ns1="http://www.w3.org/2001/06/soap-envelope"/>
    </V:Upgrade>
  </env:Header>
  <env:Body>
    <env:Fault>
      <faultcode>env:VersionMismatch</faultcode>
      <faultstring>Version Mismatch</faultstring>
    </env:Fault>
  </env:Body>
</env:Envelope> 

Note that existing SOAP/1.1 nodes are not likely to indicate which envelope versions they support. If nothing is indicated then this means that SOAP/1.1 is the only supported envelope.

D. Change Log

D.1 SOAP Specification Changes

D.2 XML Schema Changes

The envelope and encoding schemas have been updated to be compliant with the XML Schema Recomendation[10,11]. The table below shows the categories of change.

The table below lists the changes to the envelope schema.

The table below lists the changes to the encoding schema.

In addition several changes occured in the names of datatypes in the XML Schema specification and some datatypes were removed. The following table lists those changes.