Struktur der SOAP-Anforderungsnachricht

Artikel
12/15/2008

Wenn der SOAP-Client eigene SOAP-Anforderungen erstellen soll, anstatt die Proxyklassen zu verwenden, die von Visual Studio 2005 bereitgestellt werden, müssen Sie die folgenden Nachrichtenformate verwenden.

Format der SOAP-Anforderungsnachricht für gespeicherte Prozeduren und benutzerdefinierte Typen

Das folgende Beispiel zeigt eine typische SOAP-Anforderung, die an eine Instanz von SQL Server 2005 gesendet wird. In dieser SOAP-Nachricht wird die GetCustomerInfo-Operation angefordert. Beachten Sie, dass nur ein Fragment des HTTP-Headers gezeigt wird.

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-Header

Im vorherigen Code ist der Wert des SoapAction-HTTP-Headerfeldes der Methodenname, dem sein Namespace vorangestellt wurde. Dieser Wert ist die gleiche Methode und der gleiche Namespace, die Sie dem erstellten Endpunkt mithilfe von CREATE ENDPOINT hinzugefügt haben. Beachten Sie, dass dieses Feld optional ist. Das Host-HTTP-Headerfeld gibt den Server an, an den die HTTP-Anforderung gesendet wird.

<soap:Envelope>-Element

Die Einzelheiten einer SOAP-Anforderung sind im <Body>-Element im SOAP-Umschlag enthalten. Im vorherigen Beispiel wird die GetCustomerInfo-Methode angefordert. Das xmlns-Attribut in <GetCustomerInfo> ist der gleiche Namespace, der für diese Methode beim Erstellen des Endpunktes mithilfe von CREATE ENDPOINT angegeben wurde. Weitere Informationen zu der gespeicherten Prozedur und dem Namespace finden Sie unter Beispielanwendungen für das Senden systemeigener XML-Webdiensteanforderungen. Die folgenden Methodenparameter werden als untergeordnete Elemente des <GetCustomerInfo>-Elements übergeben:

Das <CustomerID>-Element, das den Wert 1 besitzt, ist der Eingabeparameter.
Das <OutputParam>-Element ist der Ausgabeparameter.

Verarbeitung der Eingabeparameter

Eingabeparameter werden auf folgende Weise verarbeitet:

Wenn eine SOAP-Methode einen Eingabeparameter erfordert und dieser Parameter nicht in der SOAP-Anforderung enthalten ist, wird kein Wert an die aufgerufene gespeicherte Prozedur übergeben. Die Standardaktion, die in der gespeicherten Prozedur definiert ist, wird ausgeführt.
Wenn eine SOAP-Methode einen Eingabeparameter erfordert und dieser Parameter in der SOAP-Anforderung enthalten ist, ihm jedoch kein Wert zugewiesen wurde, wird der Parameter an die aufgerufene gespeicherte Prozedur mit einer leeren Zeichenfolge als Wert übergeben. Beachten Sie, dass dieser Wert kein NULL-Wert ist.
Wenn eine SOAP-Operation einen Eingabeparameter erfordert und Sie einen NULL-Wert für diesen Parameter senden möchten, müssen Sie in der SOAP-Anforderung ein xsi:nil-Attribut auf "true" festlegen. Beispiel:
```
<GetCustomerInfo xmlns="http://tempUri.org/" >
  <CustomerID xsi:nil="true" />
  <OutputParam />
</GetCustomerInfo>
```
Wenn Sie in Visual Studio 2005 NULL-Werte an Zeichenfolgevariablen übergeben, wird das xsi:nil="true"-Attribut in der SOAP-Anforderung erstellt. Wenn Sie jedoch NULL-Werte für Parameter z. B. vom Typ integer oder float (Werttypen) übergeben, generiert Visual Studio 2005 nicht das xsi:nil="true"-Attribut, sondern stellt Standardwerte für diese Parameter bereit, z. B. den Wert 0 für integer-Typen oder den Wert 0,0 für float-Typen usw. Wenn Sie NULL-Werte an diese Typen von Parametern übergeben möchten, müssen Sie die SOAP-Nachrichten mithilfe des xsi:nil="true"-Attributs in Ihre Nachrichten integrieren. Weitere Informationen finden Sie unter Richtlinien und Einschränkungen für die Verwendung der systemeigenen XML-Webdienste.
Sie können mehrere Aspekte für die Parameter bereitstellen. Eine Tabelle, die Sie weiter unten in diesem Thema finden, nennt verschiedene Aspekte, die Sie beim Anfordern von Ad-hoc-SQL-Abfragen angeben können. In dieser Tabelle können alle Aspekte, die für einen <Value>-Knoten angegeben werden können, auch für die RPC-Methodenparameterknoten angegeben werden.

Format der SOAP-Anforderungsnachricht für das Anfordern von Ad-hoc-SQL-Abfragen

Wenn Sie eine SOAP-Anforderung für Ad-hoc-SQL-Abfrageausführungen senden, müssen Sie die sqlbatch-Methode aufrufen und die Abfragen sowie die ggf. erforderlichen Parameter übergeben.

Die folgende HTTP SOAP-Beispielanforderung ruft die sqlbatch-Methode auf. Beachten Sie, dass nur ein Fragment des HTTP-Headers gezeigt wird.

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-Header

Beachten Sie im HTTP-Header, dass der SoapAction-HTTP-Headerfeldwert der Methodenname (sqlbatch) ist, den der Client zum Angeben von SQL-Abfragen verwendet. Beachten Sie, dass dieser Header optional ist.

<soap:Envelope>-Element

Die Einzelheiten der SOAP-Anforderung sind im <Body>-Element enthalten. Das SOAP <Body>-Element besitzt nur ein untergeordnetes Element (<sqlbatch>) und gibt die angeforderte Methode an. In dem Namespace, der im Element aufgeführt wird, wird die sqlbatch-Operation definiert. Dieses Element besitzt die folgenden untergeordneten Elemente:

Das <BatchCommands>-Element gibt die Abfrage oder durch Semikolons (;) getrennte Abfragen an, die ausgeführt werden soll(en).
Das <Parameters>-Element stellt eine optionale Liste von Parametern bereit. Im vorherigen Beispielabfrageumschlag wird nur ein Parameter an die Abfrage übergeben. Jeder Parameter, der der SOAP-Nachricht hinzugefügt wird, ist ein untergeordnetes <SqlParameter>-Element des <Parameters>-Elements. Bei der Übergabe von Parametern müssen Sie mindestens den Parameternamen (Name-Attribut des <SqlParameter>-Elements) und den Parameterwert (untergeordnetes <Value>-Element des <SqlParameter>-Elements) übergeben.

Damit unerwartete Konvertierungen vermieden werden, stellen Sie so umfangreiche Parameterinformationen wie möglich zur Verfügung. Die folgende Tabelle listet zusätzliche Parameteraspekte auf, die Sie für das <SqlParameter>-Element angeben können. Sie können einige dieser Aspekte auch für das <Value>-Element angeben.

Wenn Sie für Aspekte, die sowohl für das <SqlParameter>- als auch für das <Value>-Element angegeben werden können, das <Value>-Element angeben, müssen sich die Aspekte im https://schemas.microsoft.com/sqlserver/2004/sqltypes-Namespace befinden, wie das folgende Beispiel zeigt:

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

Parameteraspekt	Kommentar	Kann für folgenden Knoten angegeben werden
direction	Gibt die Richtung (Input, InputOutput) eines Parameters an. Input ist die Standardeinstellung.	<SqlParameter>
localeID	Definiert das Windows-Gebietsschema für die Sortierung von Zeichentypen. Entspricht dem LCID-Wert, der von COLLATIONPROPERTY systemintern zurückgegeben wird.	<SqlParameter> <Wert>
maxLength	Attribut des <SqlParameter>-Elements; stellt die maximale Länge des Parameterwertes zur Verfügung. Der Standardwert ist 1.	<SqlParameter> <Wert>
name	Attribut des <SqlParameter>-Elements; stellt den Parameternamen zur Verfügung.	<SqlParameter>
outputRequested	Kann auf die Parameterelemente angewendet werden, wenn eine Ausgabe erfolgen soll. Das Standardverhalten hängt vom verwendeten parameterMode ab (explizit oder Standard). Wenn das Attribut für einen Eingabeparameter auf "true" festgelegt wird, wird ein Fehler generiert.	<Wert>
precision	Attribut des <SqlParameter>-Elements; stellt die Genauigkeit des Parameterwertes zur Verfügung. Der Standardwert ist 18.	<SqlParameter> <Wert>
scale	Attribut des <SqlParameter>-Elements; stellt die Dezimalstellen des Parameterwertes zur Verfügung. Der Standardwert ist 0.	<SqlParameter> <Wert>
sqlCompareOptions	Definiert die Vergleichsoptionen, die für die Sortierung von Zeichentypen verwendet werden sollen. Es handelt sich um eine Enumeration von Werten, die kombiniert werden können; die Enumeration entspricht dem ComparisonStyle-Wert, der von COLLATIONPROPERTY systemintern zurückgegeben wird.	<SqlParameter><Wert>
sqlDbType	Gibt den Parametertyp an. Eine Liste der Systemdatentypen von SQL Server 2005, die Sie angeben können, finden Sie unter Datentypzuordnungen in systemeigenen XML-Webdiensten.	<SqlParameter>
typeName	Wird zum Angeben benutzerdefinierter Typargumente verwendet. typeName muss einen dreiteiligen Namen enthalten.	<SqlParameter> <Wert>
useDefaultValue	Gibt an, dass ein Standardwert für einen Parameter verwendet werden soll; das Parameterelement kann entweder aus der Liste ausgelassen werden, oder alternativ kann das Boolesche Attribut useDefaultValue mit einem Wert von "true" angegeben werden. Der Standardwert dieses Attributs ist "false", wenn das Element enthalten ist, und "true", wenn das Element ausgelassen wird.	<SqlParameter> <Wert>
XmlNamespace	Gibt den XML-Schemanamespace an, der dem xml-Typparameter zugeordnet ist.	<SqlParameter> <Wert>
xsi:type	Gibt den Werttyp an. Weitere Informationen, wie der xsi:type-Aspekt den Systemdatentypen von SQL Server 2005 zugeordnet wird, finden Sie unter Datentypzuordnungen in systemeigenen XML-Webdiensten.	<Wert>

Siehe auch

Verweis

Struktur der SOAP-Anforderungs- und -Antwortnachrichten
SOAP-Erweiterungsheader
Struktur der SOAP-Antwortnachricht
Struktur der SOAP-Fehlernachricht
In SOAP-Anforderungen und -Antworten verwendete Namespaces

Hilfe und Informationen

Informationsquellen für SQL Server 2005