Structure des messages de demande SOAP
Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité.
Si vous souhaitez que votre client SOAP crée ses propres demandes SOAP au lieu d'utiliser les classes proxy fournis par Visual Studio 2005, vous devez utiliser les formats de message ci-dessous.
Formats des messages de demande SOAP pour les procédures stockées et les types définis par l'utilisateur
L'exemple suivant illustre une demande SOAP standard envoyée à une instance de SQL Server. Dans le message SOAP, l'opération GetCustomerInfo est demandée. Notez que seul un fragment de l'en-tête HTTP est présenté.
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>
En-tête HTTP
Dans le code précédent, la valeur du champ d'en-tête HTTP SoapAction est le nom de la méthode précédé de son espace de noms. Cette valeur représente la méthode et l'espace de noms identiques à ceux ajoutés au point de terminaison créé à l'aide de CREATE ENDPOINT. Notez que ce champ est facultatif. L'en-tête HTTP Host identifie le serveur auquel est adressée la demande HTTP.
Élément <soap:Envelope>
Les détails d'une demande SOAP sont inclus dans l'élément <Body> de l'enveloppe SOAP. L'exemple précédent demande la méthode GetCustomerInfo. L'attribut xmlns de <GetCustomerInfo> représente le même espace de noms que celui spécifié pour cette méthode que vous avez utilisée pour créer le point de terminaison à l'aide de CREATE ENDPOINT. Pour plus d'informations sur la procédure stockée et l'espace de noms, consultez Exemples d'applications pour l'envoi de demandes de services Web XML natifs. Les paramètres de méthode suivants sont transmis en tant qu'éléments enfants de l'élément <GetCustomerInfo> :
L'élément <CustomerID> qui possède la valeur 1 est le paramètre d'entrée.
L'élément <OutputParam> est le paramètre de sortie.
Traitement des paramètres d'entrée
Les paramètres d'entrée sont traités des manières suivantes :
Si une méthode SOAP exige un paramètre d'entrée et si ce dernier n'est pas inclus dans la demande SOAP, aucune valeur n'est transmise à la procédure stockée appelée. L'action par défaut définie dans la procédure stockée est exécutée.
Si une méthode SOAP exige un paramètre d'entrée et si ce dernier est inclus dans la demande SOAP sans qu'aucune valeur ne lui soit affectée, le paramètre est transmis à la procédure stockée avec une chaîne vide comme valeur. Notez qu'il ne s'agit pas d'une valeur NULL.
Si une opération SOAP exige un paramètre d'entrée alors que vous souhaitez envoyer une valeur NULL pour ce paramètre, vous devez définir un attribut xsi:nil sur la valeur "true" dans la demande SOAP. Par exemple :
<GetCustomerInfo xmlns="http://tempUri.org/" > <CustomerID xsi:nil="true" /> <OutputParam /> </GetCustomerInfo>Dans Visual Studio 2005, lorsque vous transmettez des valeurs NULL à des variables de chaîne, cette opération crée l'attribut xsi:nil="true" dans la demande SOAP. En revanche, lorsque vous transmettez des valeurs NULL pour des paramètres de type integer ou float (types de valeur), Visual Studio 2005 ne crée pas d'attribut xsi:nil="true" ; à la place, il fournit des valeurs par défaut à ces paramètres, par exemple 0 pour les types integer, 0,0 pour les types float, etc. Par conséquent, si vous voulez transmettre des valeurs NULL à ce type de paramètre, vous devez créer le message SOAP dans votre application en utilisant l'attribut xsi:nil="true". Pour plus d'informations, consultez Instructions et restrictions d'emploi en vigueur dans les services Web XML natifs.
Vous pouvez fournir plusieurs facettes sur les paramètres. Un tableau présenté plus loin dans cette rubrique répertorie plusieurs facettes que vous pouvez spécifier lorsque vous demandez des requêtes SQL ad hoc. Dans ce tableau, toutes les facettes que vous pouvez spécifier pour un nœud <Value> peuvent l'être sur les nœuds des paramètres de la méthode RPC.
Format des messages de demande SOAP lors de demandes de requêtes SQL ad hoc
Lorsque vous envoyez une demande SOAP pour des exécutions de requêtes SQL ad hoc, vous devez appeler la méthode sqlbatch et lui transmettre les requêtes et les éventuels paramètres nécessaires.
L'exemple suivant de demande HTTP SOAP appelle la méthode sqlbatch. Notez que seul un fragment de l'en-tête HTTP est présenté.
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>
En-tête HTTP
Dans l'en-tête HTTP, notez que la valeur du champ d'en-tête HTTP SoapAction représente le nom de la méthode (sqlbatch) utilisé par le client pour spécifier les requêtes SQL. Notez que cet en-tête est facultatif.
Élément <soap:Envelope>
Les détails de la demande SOAP figurent dans l'élément <Body>. L'élément SOAP <Body> possède un seul élément enfant (<sqlbatch>) et identifie la méthode demandée. L'espace de noms identifié dans l'élément est celui où l'opération sqlbatch est définie. Cet élément possède les éléments enfants suivants :
L'élément <BatchCommands> spécifie la requête, ou les requêtes séparées par des points-virgules (;), à exécuter.
L'élément <Parameters> contient une liste facultative de paramètres. Dans l'exemple précédent d'enveloppe de demande, un seul paramètre est transmis à la requête. Chaque paramètre est ajouté au message SOAP en tant qu'élément enfant <SqlParameter> de l'élément <Parameters>. Pour transmettre les paramètres, vous devez au moins transmettre leur nom (attribut Name de l'élément <SqlParameter>) et leur valeur (élément enfant <Value> de l'élément <SqlParameter>).
Pour éviter des conversions inattendues, fournissez autant d'informations de paramètre que vous pouvez. Le tableau ci-dessous répertorie des facettes de paramètre supplémentaires que vous pouvez spécifier pour l'élément <SqlParameter>. Vous pouvez également spécifier certaines de ces facettes pour l'élément <Value>.
Pour les facettes qui peuvent être spécifiées à la fois sur les éléments <SqlParameter> et <Value>, lorsque vous spécifiez l'élément <Value>, les facettes doivent figurer dans l'espace de noms https://schemas.microsoft.com/sqlserver/2004/sqltypes comme illustré dans l'exemple suivant :
<Value xsi:type="xsd:string" sqltypes:maxLength="100" xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">1</Value>
Facette du paramètre |
Commentaire |
Peut être spécifiée sur le nœud |
|---|---|---|
direction |
Spécifie la direction du paramètre (Input, InputOutput). La valeur par défaut est Input. |
<SqlParameter> |
localeID |
Définit les paramètres régionaux Windows pour le classement des types de caractère. Équivaut à la valeur LCID retournée par la commande COLLATIONPROPERTY intrinsèque. |
<SqlParameter> <Value> |
maxLength |
L'attribut de l'élément <SqlParameter> fournit la longueur maximale de la valeur du paramètre. La valeur par défaut est 1. |
<SqlParameter> <Value> |
name |
L'attribut de l'élément <SqlParameter> fournit le nom du paramètre. |
<SqlParameter> |
outputRequested |
Peut être appliqué aux éléments du paramètre pour indiquer s'il doit émettre une sortie. Le comportement par défaut dépend de l'attribut parameterMode utilisé, selon qu'il est explicite ou par défaut. Si l'attribut a la valeur "true" pour un paramètre d'entrée, une erreur se produit. |
<Value> |
precision |
Cet attribut de l'élément <SqlParameter> fournit la précision de la valeur du paramètre. La valeur par défaut est 18. |
<SqlParameter> <Value> |
scale |
Cet attribut de l'élément <SqlParameter> fournit l'échelle de la valeur du paramètre. La valeur par défaut est 0. |
<SqlParameter> <Value> |
sqlCompareOptions |
Définit les options de comparaison à utiliser pour le classement des types de caractère. Il s'agit d'une énumération des valeurs pouvant être combinées, qui correspond à la valeur ComparisonStyle retournée par la commande COLLATIONPROPERTY intrinsèque. |
<SqlParameter><Value> |
sqlDbType |
Spécifie le type de paramètre. |
<SqlParameter> |
clrTypeName |
Permet de spécifier des arguments de type CLR défini par l'utilisateur. clrTypeName peut contenir le nom en trois parties. |
<SqlParameter> <Valeur> |
useDefaultValue |
Indique qu'une valeur par défaut doit être utilisée pour un paramètre. L'élément de paramètre peut être omis de la liste ou l'attribut booléen useDefaultValue avec la valeur "true" peut être spécifié. La valeur par défaut de cet attribut est "false" si l'élément est inclus et "true" si l'élément est omis. |
<SqlParameter> <Valeur> |
XmlNamespace |
Spécifie l'espace de noms du schéma XML associé au paramètre de type xml. |
<SqlParameter> <Value> |
xsi:type |
Spécifie le type de valeur. Pour plus d'informations sur la façon dont la facette xsi:type est mappée aux types de données système de SQL Server, consultez Mappage des types de données dans les services Web XML natifs. |
<Valeur> |
typename |
Permet de spécifier des arguments de type défini par l'utilisateur. typename peut contenir le nom en trois parties. |
<SqlParameter> <Valeur> |