• [アーティクル]

SOAP 要求メッセージの構造

この機能は、将来のバージョンの Microsoft SQL Server では削除される予定です。新しい開発作業では、この機能の使用を避け、現在この機能を使用しているアプリケーションは修正するようにしてください。

Visual Studio 2005 で用意されているプロキシ クラスを使用するのではなく、独自の SOAP 要求を SOAP クライアントで作成する場合は、以下のメッセージ形式に従う必要があります。

ストアド プロシージャとユーザー定義型用の 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> 要素の子要素に渡されます。

  • <CustomerID> 要素。これは入力パラメーターで、値 1 を保持します。

  • <OutputParam> 要素。これは出力パラメーターです。

入力パラメーターの処理

入力パラメーターは次のように処理されます。

  • SOAP メソッドに入力パラメーターが必要で、そのパラメーターが 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 などの型 (値型) のパラメーターに渡すと、xsi:nil="true" 属性が生成されず、代わりに、Visual Studio 2005 によってそれらのパラメーターに既定値が指定されます。たとえば、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 ヘッダー フィールド値がメソッド名 (sqlbatch) です。これは、SQL クエリを指定するためにクライアントで使用されます。このヘッダーは省略できます。

<soap:Envelope> 要素

SOAP 要求の詳細は、<Body> 要素内に示されます。SOAP <Body> 要素には子要素 (<sqlbatch>) が 1 つだけあり、要求されるメソッドがこの子要素で特定されます。この要素で特定される名前空間は、sqlbatch メソッドが定義されている場所です。この要素には次の子要素があります。

  • <BatchCommands> 要素。この要素では、実行するクエリ、またはセミコロン (;) で区切られた複数のクエリを指定します。

  • <Parameters> 要素。パラメーターのリストを指定します。このリストは、省略できます。上記の要求のエンベロープ例では、クエリに渡されるパラメーターが 1 つだけ含まれています。各パラメーターは、<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

パラメーターの方向 (Input、InputOutput) を指定します。既定値は 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

パラメーターの型を指定します。指定できる SQL Server のシステム データ型の一覧については、「ネイティブ XML Web サービスでのデータ型マッピング」を参照してください。

<SqlParameter>

clrTypeName

CLR ユーザー定義型の引数を指定するために使用します。clrTypeName には、3 つの部分で構成される名前を指定することができます。

<SqlParameter>

<Value>

useDefaultValue

パラメーターに既定値を使用する必要があることを示します。このパラメーター要素はリストから省略することも、ブール属性 useDefaultValue に値 true を設定して指定することもできます。この属性の既定値は、要素が含まれている場合は false であり、要素が省略されている場合は true です。

<SqlParameter>

<Value>

XmlNamespace

xml 型パラメーターに関連付けられる XML スキーマ名前空間を指定します。

<SqlParameter>

<Value>

xsi:type

値型を指定します。xsi:type ファセットと SQL Server システムデータ型とのマッピングの詳細については、「ネイティブ XML Web サービスでのデータ型マッピング」を参照してください。

<Value>

typename

ユーザー定義型の引数を指定するために使用します。typename には、3 つの部分で構成される名前を指定することができます。

<SqlParameter>

<Value>