SOAP协议规范（二）

2024-07-21 02:29:12

字体：大中小

来源：转载

供稿：网友

以下是描述上面结构的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">http://www.dartmouth.edu/~milton/reading_room/  </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>http://www.dartmouth.edu/~milton/reading_room/  </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:  "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,  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="http://schemas.xmlsoap.org/soap/envelope/";
soap-env:encoding_blank" encoding>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:encoding_blank" encoding>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:encoding_blank" encoding>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:encoding_blank" encoding>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  didn't  work
</message>
<errorcode>  1001  </errorcode>
</e:myfaultdetails>
</detail>
</soap-env:fault>
</soap-env:body>
</soap-env:envelope>