共用方式為

  • 發行項

SOAP 要求訊息結構

未來的 Microsoft SQL Server 版本將移除這項功能。請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。

若要讓 SOAP 用戶端建立其自己的 SOAP 要求而非使用由 Visual Studio 2005 提供的 Proxy 類別，您必須使用下列訊息格式。

預存程序與使用者定義型別的 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 Envelope 的 <Body> 元素中。上述範例要求使用 GetCustomerInfo 方法。<GetCustomerInfo> 中的 xmlns 屬性，與您使用 CREATE ENDPOINT 建立的結束點方法指定的屬性是同一個命名空間。如需有關預存程序與命名空間的詳細資訊，請參閱＜傳送原生 XML Web Service 要求的範例應用程式＞。下列方法參數當做 <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" 屬性。但是為參數類型傳遞 NULL 值時，例如 integer 和 float (數值類型)，Visual Studio 2005 就不會產生 xsi:nil="true" 屬性，而是提供這些參數的預設值，例如，integer 類型為 0，float 類型為 0.0 等。因此，若要傳遞 NULL 值至這些參數類型，必須使用 xsi:nil="true" 屬性在應用程式中建立 SOAP 訊息。如需詳細資訊，請參閱＜原生 XML Web Service 中的指導方針和限制＞

  • 您可以為參數提供數個 Facet。本主題稍後顯示的表格中會列出要求特定 SQL 查詢時可以指定的數個 Facet。在此表中，可以為 <Value> 節點指定的所有 Facet，皆可在 RPC 方法參數節點上指定。

要求特定 SQL 查詢時的 SOAP 要求訊息格式

當您傳送 SOAP 要求欲執行特定 SQL 查詢時，必須呼叫 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> 元素提供選擇性的參數清單。在之前的要求封套 (Envelope) 範例中，僅傳遞一個參數給查詢。每個參數做為 <Parameters> 元素的 <SqlParameter> 子元素加入到 SOAP 訊息中。傳遞參數時，您至少必須傳遞參數名稱 ( <SqlParameter> 元素的 Name 屬性) 和參數值 (<SqlParameter> 元素的 <Value> 子元素 )。

為避免非預期的轉換，盡可能提供多一點參數資訊。下表列出您可以針對 <SqlParameter> 元素指定的其他參數 Facet。您也可以為 <Value> 元素指定表中所示的某些 Facet。

對於可以在 <SqlParameter> 與 <Value> 兩種元素上指定的 Facet，當指定 <Value> 元素時，Facet 必須位於 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>

參數 Facet

註解

可以在節點上指定

direction

指定參數方向 (Input、InputOutput)。預設為 Input。

<SqlParameter>

localeID

定義字元類型定序的視窗地區設定。相當於 COLLATIONPROPERTY 內建傳回的 LCID 值。

<SqlParameter>

<值>

maxLength

<SqlParameter> 元素的屬性提供參數值的最大長度。預設值為 1。

<SqlParameter>

<Value>

name

<SqlParameter> 元素的屬性提供參數名稱。

<SqlParameter>

outputRequested

可套用至參數元素，指示是否應該發出輸出。預設行為取決於使用的 parameterMode，與外顯或預設模式無關。

如果輸入參數上的屬性設定為 "true"，將會產生錯誤。

<值>

precision

<SqlParameter> 元素的這個屬性會提供參數值的有效位數。預設值為 18。

<SqlParameter>

<Value>

scale

<SqlParameter> 元素的這個屬性會提供參數值的小數位數。預設值為 0。

<SqlParameter>

<值>

sqlCompareOptions

定義字元類型定序使用的比較選項。其為可以組合的列舉值，與 COLLATIONPROPERTY 內建傳回之 ComparisonStyle 值相符。

<SqlParameter><值>

sqlDbType

指定參數類型。

<SqlParameter>

clrTypeName

用來指定 CLR 使用者定義型別引數。clrTypeName 可以包含三部分的名稱。

<SqlParameter>

<値>

useDefaultValue

表示參數應該使用預設值。此參數元素可以從清單省略，或者可以指定值為 "true" 的布林屬性 useDefaultValue。如果包含此元素，此屬性的預設值為 "false"，如果省略此元素，則預設值為 "true"。

<SqlParameter>

<値>

XmlNamespace

指定與 xml 類型參數相關聯的 XML 結構描述命名空間。

<SqlParameter>

<值>

xsi:type

指定值類型。如需有關 xsi:type Facet 如何對應到 SQL Server 系統資料類型的詳細資訊，請參閱＜原生 XML Web Service 中的資料類型對應＞。

<値>

typename

用來指定使用者定義型別引數。typename 可以包含三部分的名稱。

<SqlParameter>

<値>