Struktur der SOAP-Anforderungsnachricht
Diese Funktion wird in zukünftigen Versionen von Microsoft SQL Server nicht mehr bereitgestellt. Verwenden Sie diese Funktion beim Entwickeln neuer Anwendungen nicht, und planen Sie das Ändern von Anwendungen, in denen es zurzeit verwendet wird.
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 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-Webdienstanforderungen. 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 Facets für die Parameter bereitstellen. Eine Tabelle, die Sie weiter unten in diesem Thema finden, nennt verschiedene Facets, die Sie beim Anfordern von Ad-hoc-SQL-Abfragen angeben können. In dieser Tabelle können alle Facets, 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.
Um unerwartete Konvertierungen zu vermeiden, stellen Sie so viele Parameterinformationen bereit wie möglich. In der folgenden Tabelle werden zusätzliche Parameterfacets aufgeführt, die Sie für das <SqlParameter>-Element angeben können,. Sie können einige dieser Facets auch für das <Value>-Element angeben.
Wenn Sie für Facets, 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 Facets 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>
Parameterfacet |
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. |
<Value> |
precision |
Dieses Attribut des <SqlParameter>-Elements stellt die Genauigkeit des Parameterwerts zur Verfügung. Der Standardwert ist 18. |
<SqlParameter> <Wert> |
scale |
Dieses Attribut des <SqlParameter>-Elements stellt die Dezimalstellen des Parameterwerts 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. |
<SqlParameter> |
clrTypeName |
Wird zum Angeben benutzerdefinierter CLR-Typargumente verwendet. clrTypeName kann den dreiteiligen Namen enthalten. |
<SqlParameter> <Value> |
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> <Value> |
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-Facet den Systemdatentypen von SQL Server zugeordnet wird, finden Sie unter Datentypzuordnungen in systemeigenen XML-Webdiensten. |
<Value> |
typename |
Wird zum Angeben benutzerdefinierter Typargumente verwendet. typename kann den dreiteiligen Namen enthalten. |
<SqlParameter> <Value> |