SOAP 请求消息结构

后续版本的 Microsoft SQL Server 将删除该功能。 请避免在新的开发工作中使用该功能,并着手修改当前还在使用该功能的应用程序。

如果希望 SOAP 客户端生成自己的 SOAP 请求,而不是使用 Visual Studio 2005 提供的代理类,则必须使用下列消息格式。

存储过程和用户定义类型的 SOAP 请求消息格式

下面的示例显示了发送到 SQL Server 实例的一个典型 SOAP 请求。在 SOAP 消息中请求了 GetCustomerInfo 操作。请注意,只会显示 HTTP 标头的一部分。

POST /url HTTP/1.1
Host: HostServerName
Content-type: text/xml; charset=utf-8
Content-length: 350
SoapAction: http://tempUri.org/GetCustomerInfo
...

<?xml version="1.0" encoding="utf-8" ?> 
<soap:Envelope 
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
   <GetCustomerInfo xmlns="http://tempUri.org/">
<CustomerID>1</CustomerID> 
<OutputParam /> 
  </GetCustomerInfo>
</soap:Body>
</soap:Envelope>

HTTP 标头

在前面的代码中,SoapAction HTTP 标头字段的值是其命名空间后面的方法名称。此值与添加到端点(使用 CREATE ENDPOINT 创建的)的方法和命名空间相同。请注意,这是一个可选字段。Host HTTP 标头字段标识接收 HTTP 请求的服务器。

<soap:Envelope> 元素

SOAP 请求的详细信息包含在 SOAP 信封的 <Body> 元素中。上面的示例请求了 GetCustomerInfo 方法。<GetCustomerInfo> 中的 xmlns 属性与为此方法指定的命名空间相同,此方法是使用 CREATE ENDPOINT 创建端点的方法。有关存储过程和命名空间的详细信息,请参阅用于发送本机 XML Web 服务请求的示例应用程序。下列方法参数将作为 <GetCustomerInfo> 元素的子元素传入:

  • 值为 1 的 <CustomerID> 元素是输入参数。

  • <OutputParam> 元素是输出参数。

输入参数处理

输入参数的处理方法如下:

  • 如果 SOAP 方法需要输入参数,并且此参数未包含在 SOAP 请求中,则不会有任何值传入调用的存储过程。此时将执行存储过程中定义的默认操作。

  • 如果 SOAP 方法需要输入参数,并且此参数包含在请求中但未赋值,则该参数将用一个空字符串作为其值传入存储过程。请注意,该值不是 NULL。

  • 如果 SOAP 操作需要输入参数,并且您要为此参数发送 NULL 值,则必须在 SOAP 请求中将 xsi:nil 属性设置为 "true"。例如:

    <GetCustomerInfo xmlns="http://tempUri.org/" >
      <CustomerID xsi:nil="true" />
      <OutputParam />
    </GetCustomerInfo>
    

    在 Visual Studio 2005 中,将 NULL 值传入字符串变量时,将在 SOAP 请求中生成 xsi:nil="true" 属性。但是,为类型为 integer 和 float 类型(值类型)的参数传递 NULL 值时,Visual Studio 2005 不会生成 xsi:nil="true" 属性,而是为这些参数提供默认值。例如,为 integer 类型的参数提供 0,为 float 类型的参数提供 0.0,等等。因此,如果要将 NULL 值传入这些类型的参数,必须使用 xsi:nil="true" 属性在应用程序中生成 SOAP 消息。有关详细信息,请参阅本机 XML Web 服务的指导原则和限制

  • 您可以为参数指定几个方面。本主题后面显示了一个表,其中列出了在请求即席 SQL 查询时可以指定的几个方面。在此表中,可以为 <Value> 节点指定的所有方面均可以对 RPC 方法参数节点指定。

请求即席 SQL 查询时的 SOAP 请求消息格式

为执行即席 SQL 查询发送 SOAP 请求时,必须调用 sqlbatch 方法并传递查询以及可能需要的所有参数。

在下面的示例中,HTTP SOAP 请求调用了 sqlbatch 方法。请注意,只会显示 HTTP 标头的一部分。

POST /url HTTP/1.1
Host: HostServerName
Content-type: text/xml; charset=utf-8
Content-length: 656
SoapAction: https://schemas.microsoft.com/sqlserver/2004/SOAPsqlbatch
...

<?xml version="1.0" encoding="utf-8" ?> 
 <soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
 <sqlbatch xmlns="https://schemas.microsoft.com/sqlserver/2004/SOAP">
<BatchCommands>
SELECT EmployeeID, FirstName, LastName 
FROM Employee 
WHERE EmployeeID=@x 
FOR XML AUTO;
</BatchCommands> 
<Parameters>
   <SqlParameter Name="x" SqlDbType="Int" MaxLength="20" 
   xmlns="https://schemas.microsoft.com/SQLServer/
    2001/12/SOAP/types/SqlParameter">
  <Value xsi:type="xsd:string">1</Value> 
   </SqlParameter>
</Parameters>
  </sqlbatch>
  </soap:Body>
  </soap:Envelope>

HTTP 标头

在 HTTP 标头中,请注意 SoapAction HTTP 标头字段值为客户端用于指定 SQL 查询的方法名 (sqlbatch)。请注意,此标头是可选的。

<soap:Envelope> 元素

SOAP 请求详细信息显示在 <Body> 元素中。SOAP <Body> 元素只有一个子元素 (<sqlbatch>),用于标识所请求的方法。在元素中标识的命名空间是定义 sqlbatch 操作的位置。此元素有下列子元素:

  • <BatchCommands> 元素指定要执行的单个查询或多个查询(由分号 ; 分隔)。

  • <Parameters> 元素提供了可选参数列表。在上面的示例请求信封中,只有一个参数传入了查询。每个参数都作为 <Parameters> 元素的一个 <SqlParameter> 子元素添加到 SOAP 消息中。在传递参数时,必须至少传递参数名称(<SqlParameter> 元素的 Name 属性)和参数值(<SqlParameter> 元素的 <Value> 子元素)。

若要避免意外转换,请提供尽可能多的参数信息。下表列出了可以为 <SqlParameter> 元素指定的其他参数方面。您也可以为 <Value> 元素指定其中的某些方面。

对于可以对 <SqlParameter> 和 <Value> 元素指定的方面,在指定 <Value> 元素时,这些方面必须位于 https://schemas.microsoft.com/sqlserver/2004/sqltypes 命名空间中,如下面的示例所示:

<Value xsi:type="xsd:string" sqltypes:maxLength="100" xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">1</Value>

参数方面

注释

可以指定的节点

direction

指定参数方向(InputInputOutput)。默认值为 Input

<SqlParameter>

localeID

定义字符类型排序规则的 Windows 区域设置。等于 COLLATIONPROPERTY 内部返回的 LCID 值。

<SqlParameter>

<Value>

maxLength

<SqlParameter> 元素属性提供了参数值的最大长度。默认值为 1。

<SqlParameter>

<Value>

name

<SqlParameter> 元素属性提供了参数名。

<SqlParameter>

outputRequested

可以应用到参数元素,以指示是否应该发出输出。默认行为取决于所使用的 parameterMode,而与其是显式还是默认无关。

如果将输入参数的该属性设置为 "true",则将生成一个错误。

<Value>

precision

<SqlParameter> 元素的此属性提供了参数值的精度。默认值为 18。

<SqlParameter>

<Value>

scale

<SqlParameter> 元素的此属性提供了参数值的小数位数。默认值为 0。

<SqlParameter>

<Value>

sqlCompareOptions

定义用于字符类型排序规则的比较选项。它是可以组合的值的枚举,与 COLLATIONPROPERTY 内部返回的 ComparisonStyle 值相匹配。

<SqlParameter><Value>

sqlDbType

指定参数类型。

<SqlParameter>

clrTypeName

用于指定 CLR 用户定义类型参数。clrTypeName 可以包含由三部分构成的名称。

<SqlParameter>

<Value>

useDefaultValue

指示应为参数使用默认值。既可以从列表中省略参数元素,也可以指定值为 "true" 的布尔值属性 useDefaultValue。如果包含元素,则此属性的默认值为 "false";如果省略了元素,则此属性的默认值为 "true"。

<SqlParameter>

<Value>

XmlNamespace

指定与 xml 类型参数关联的 XML 架构命名空间。

<SqlParameter>

<Value>

xsi:type

指定值类型。有关 xsi:type 方面如何映射到 SQL Server 系统数据类型的详细信息,请参阅本机 XML Web 服务中的数据类型映射

<Value>

typename

用于指定用户定义类型参数。typename 可以包含由三部分构成的名称。

<SqlParameter>

<Value>