SOAP协议规范（二）

2022-07-15 80酷酷网 80kuku.com

　　规范

以下是描述上面结构的schema片断：

5.4.2 数组
SOAP数组定义为具有"SOAP-ENC:Array"类型或一个从"SOAP-ENC:Array"衍生的类型（参见规则8）。数组表示为元素值，对元素的名没有特别的约束（正如元素值并不约束它们所属的元素）。数组可以包含任意类型的元素，包括嵌套数组。可以创建新的类型（受SOAP-ENC:Array
类型限制）来表示数组，如整数数组或某些用户定义的枚举。数组值表示为组成这个数组的项的元素的规则序列。在数组值中，元素名对于区分accesor并不重要。元素可以有任意的名。实际上，元素常常用它们在schema中暗示或确定的数组类型来命名元素。并且一般情况下对于复合值来说，如果数组中数组项的值是single-reference值，则这个数组项包含它的值，否则，该数组项通过"href"属性引用这个值。下面的例子是一个整型数组的schema片断：

在这个例子中，数组"myfavoritenumbers"包括几个成员，每个成员是一个类型为soap-enc:int的值。注意soap-enc:array允许不受限制的元素名，它们不传达任何类型信息，所以在使用时，或者它们有xsi:type属性，或者它们所属的元素有soap-enc:arraytype属性。自然，由soap-enc:array衍生的类型可以声明局部元素，但这种情况下要包括类型信息。上面已经提到，soap-enc schema包含了元素的声明，元素名与"xml schema part 2: datatypes"规范[11]中的简单类型一致。其中包括了对"array"的声明。于是，我们可以这样写：

<soap-enc:array soap-enc:arraytype="xsd:int[2]">
<SOAP-ENC:int>3</SOAP-ENC:int>
<SOAP-ENC:int>4</SOAP-ENC:int>
</SOAP-ENC:Array>

数组可以包含特定arraytype的任意子类型的实例。即，数组成员可以是arrytype属性值指定的类型的任意子类型，这个类型对于arraytype属性中指定的类型来说是可替换的（根据schema中的替换规则）。例如，一个整型数组可以包含从整型衍生的任意类型（如"int"或任意用户定义的从整型衍生的类型）。同样，一个"address"数组可能包含一个address的受限类型或扩展类型如"internationaladdress"。因为提供的soap-enc:array类型允许任意类型的成员，所以可以包含任意类型的混合除非使用arraytype属性加以特别的限制。在实例中，可以使用xsi:type指定成员元素的类型，或通过schema中成员元素的声明来指定。下面是两个例子。

<soap-enc:array  soap-enc:arraytype="soap-enc:ur-type[4]">
<thing  xsi:type="xsd:int">12345</thing>
<thing  xsi:type="xsd:decimal">6.789</thing>
<thing  xsi:type="xsd:string">
Of  Mans  First  Disobedience,  and  the  Fruit
Of  that  Forbidden  Tree,  whose  mortal  tast
Brought  Death  into  the  World,  and  all  our  woe,
</thing>
<thing  xsi:type="xsd:uriReference">  </thing>
</SOAP-ENC:Array>
<SOAP-ENC:Array  SOAP-ENC:arrayType="SOAP-ENC:ur-type[4]">
<SOAP-ENC:int>12345</SOAP-ENC:int>
<SOAP-ENC:decimal>6.789</SOAP-ENC:decimal>
<xsd:string>
Of  Mans  First  Disobedience,  and  the  Fruit
Of  that  Forbidden  Tree,  whose  mortal  tast
Brought  Death  into  the  World,  and  all  our  woe,
</xsd:string>
<SOAP-ENC:uriReference>  </SOAP-ENC:uriReference  >
</SOAP-ENC:Array>

数组值可以是结构或其它复合值。例如"xyz:order"结构数组：

<soap-enc:array soap-enc:arraytype="xyz:order[2]">
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</SOAP-ENC:Array>

数组成员值也可以是数组。下例是两个字符串数组组成的数组：

<soap-enc:array  soap-enc:arraytype="xsd:string[][2]">
<item  href="#array-1"/>
<item  href="#array-2"/>
</SOAP-ENC:Array>
<SOAP-ENC:Array  id="array-1"  SOAP-ENC:arrayType="xsd:string[2]">
<item>r1c1</item>
<item>r1c2</item>
<item>r1c3</item>
</SOAP-ENC:Array>
<SOAP-ENC:Array  id="array-2"  SOAP-ENC:arrayType="xsd:string[2]">
<item>r2c1</item>
<item>r2c2</item>
</SOAP-ENC:Array>

包含数组的元素无需命名为"soap-enc:array"。它可以有任意的名，只要元素的类型是soap-enc:array或由之衍生的类型。例如，下面是一个schema片断和与之一致的数组实例。

数组可能是多维的。在这种情况下，在arraytype属性的asize部分将不止有一个值：

<soap-enc:array soap-enc:arraytype="xsd:string[2,3]">
<item>r1c1</item>
<item>r1c2</item>
<item>r1c3</item>
<item>r2c1</item>
<item>r2c2</item>
<item>r2c3</item>
</SOAP-ENC:Array>

虽然上面的例子把数组编码为独立的元素，但元素值也可以是嵌入形式，而且若元素值是single reference时，必须编码为嵌入形式。下例是一个schema片断，电话号码数组嵌入到一个类型为"person"的结构中，并且通过accessor "phone-numbers"访问它：

<simpletype  name="phonenumber"  base="string"/>
<element  name="ArrayOfPhoneNumbers">
<complexType  base="SOAP-ENC:Array">
<element  name="phoneNumber"  type="tns:phoneNumber"  maxOccurs="unbounded"/>
</complexType>
<anyAttribute/>
</element>
<element  name="Person">
<complexType>
<element  name="name"  type="string"/>
<element  name="phoneNumbers"  type="tns:ArrayOfPhoneNumbers"/>
</complexType>
</element>
<xyz:Person>
<name>John  Hancock</name>
<phoneNumbers  SOAP-ENC:arrayType="xyz:phoneNumber[2]">
<phoneNumber>206-555-1212</phoneNumber>
<phoneNumber>1-888-123-4567</phoneNumber>
</phoneNumbers>
</xyz:Person>

下面的例子中，数组值为single-reference，被编码为嵌入元素，包含它的元素名即为入口名：

<xyz:purchaseorder>
<CustomerName>Henry  Ford</CustomerName>
<ShipTo>
<Street>5th  Ave</Street>
<City>New  York</City>
<State>NY</State>
<Zip>10010</Zip>
</ShipTo>
<PurchaseLineItems  SOAP-ENC:arrayType="Order[2]">
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PurchaseLineItems>
</xyz:PurchaseOrder>

5.4.2.1 部分储值（partially transmitted）数组
SOAP提供了对部分储值（partially transmitted）数组的支持，如某些上下文中的可变数组。一个partially transmitted 数组由一个"SOAP-ENC:offset"属性（从第一个transmitted的元素开始的偏移量，基于0）指示。如果省略，偏移量取0。下面的例子中数组的大小为5，但只有从0起，第三和第四个元素被储值。

<soap-enc:array  ;soap-enc:arraytype="xsd:string[5]"  ;soap-enc:offset="[2]">
<item>The  third  element</item>
<item>The  fourth  element</item>
</SOAP-ENC:Array>

5.4.2.2 稀疏数组sparse arrays
SOAP提供了对稀疏数组的支持。每个表示成员值的元素包含一个"SOAP-ENC:position"属性，用来指示它在数组中的位置。下例是两维字符串稀疏数组的例子，数组大小是4，但只用到第2个。

<soap-enc:array  soap-enc:arraytype="xsd:string[,][4]">
<SOAP-ENC:Array  href="#array-1"  SOAP-ENC:position="[2]"/>
</SOAP-ENC:Array>
<SOAP-ENC:Array  id="array-1"  SOAP-ENC:arrayType="xsd:string[10,10]">
<item  SOAP-ENC:position="[2,2]">Third  row,  third  col</item>
<item  SOAP-ENC:position="[7,2]">Eighth  row,  third  col</item>
</SOAP-ENC:Array>

如果对array-1的引用仅发生在数组内部，上例也可以编码如下：

<soap-enc:array  soap-enc:arraytype="xsd:string[,][4]">
<SOAP-ENC:Array  SOAP-ENC:position="[2]"  SOAP-ENC:arrayType="xsd:string[10,  10]>
<item  SOAP-ENC:position="[2,2]">Third  row,  third  col</item>
<item  SOAP-ENC:position="[7,2]">Eighth  row,  third  col</item>
</SOAP-ENC:Array>
</SOAP-ENC:Array>

5.4.3 一般复合类型
在这里提到的编码规则不仅仅限于accessor名已知的情况，如果accessor名是运行环境下实时获得的，编码规则同样适用，也就是说accessor编码成一个元素名与accessor名匹配的元素，同时accessor可能包含或者引用该元素的值。如果accessor包含类型不能事先确定的值，它必须包含一个合适的属性xsi:type 。类似地，上述引用的规则已经足够用于复合类型的序列化，这些复合类型可能包含用名区分的accessors（结构）和用名及序数位置区分的accessors。（可能包含重复的accessor）实际上这并不要求任何schema模式包含这些类型，但更为准确的说法是：一个类型模型（type-model）schema如果有这些类型，就可以构造一个符合XML句法规则的schema和XML文档实例。

<xyz:purchaseorder>
<CustomerName>Henry  Ford</CustomerName>
<ShipTo>
<Street>5th  Ave</Street>
<City>New  York</City>
<State>NY</State>
<Zip>10010</Zip>
</ShipTo>
<PurchaseLineItems>
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PurchaseLineItems>
</xyz:PurchaseOrder>

类似地，将一个结构上类似数组但实际上不是一个 soap-enc:array类型或者 soap-enc:array子类型的复合值序列化同样是允许的，例如：

<purchaselineitems>
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PurchaseLineItems>

5.5 缺省值
省略accessor元素意味着或者有一个缺省值或者值不知道。具体细节依靠这个accessor，方法和上下文。例如，对于多态accessor，省略accessor一般意味着一个Null值。同样，省略布尔accessor一般意味着False值或者值不知道，省略数字accessor一般意味着值为零或者值不知道。

5.6 soap root属性
SOAP root 属性可用于标记一个序列化root，从而一个对象可以反序列化（deserialized），而实际上该root并不是真正的对象root。这个属性有两个可选值"1" or "0"。对象真正的roots属性值为“1” ，序列化root但不是真正的root属性值也为“1”，元素如果要显式地指定不能为序列化root，只需将该属性设置为“0” SOAP root属性可以出现在SOAP头和SOAP体元素的任意子元素中。（译者注：SOAP root属性为0的元素不是一个独立的实体，外部的应用不能访问到该元素，但该元素可以被SOAP文档本身的其它元素访问到）SOAP root属性可以出现在SOAP头和SOAP体元素的任意子元素中。这个属性没有缺省值。

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:  "#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使用了扩展框架的扩展标志符是

6.4 soap http举例
例3 使用POST的SOAP HTTP

post  /stockquote  http/1.1
Content-Type:  text/xml;  charset="utf-8"
Content-Length:  nnnn
SOAPAction:  "#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:  ";;  ns=NNNN
Content-Type:  text/xml;  charset="utf-8"
Content-Length:  nnnn
NNNN-SOAPAction:  "#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,  A  ugust  1998.
[5]  R.  Fielding,  J.  Gettys,  J.  C.  Mogul,  H.  Frystyk,  T.  Berners-Lee,  "Hypert  ext  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  Virtu  al,  November  1996

10。附录
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=";
SOAP-ENV: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=";
SOAP-ENV: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=";
SOAP-ENV: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=";
SOAP-ENV: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=";>
<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=";>
<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  didn't  work
</message>
<errorcode>  1001  </errorcode>
</e:myfaultdetails>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>