Estructura de los mensajes de solicitud SOAP
Esta característica se quitará en una versión futura de Microsoft SQL Server. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan.
Si desea que el cliente SOAP genere sus propias solicitudes SOAP en lugar de utilizar las clases proxy proporcionadas por Visual Studio 2005, debe usar los siguientes formatos de mensaje.
Formato de los mensajes de solicitud SOAP para procedimientos almacenados y tipos definidos por el usuario
En el siguiente ejemplo se muestra una solicitud SOAP típica enviada a una instancia de SQL Server. En el mensaje SOAP, se solicita la operación GetCustomerInfo. Tenga en cuenta que solamente se muestra un fragmento del encabezado 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>
Encabezado HTTP
En el código anterior, el valor del campo del encabezado HTTP SoapAction es el nombre del método precedido por su espacio de nombres. Este valor es el mismo método y espacio de nombres que ha agregado al extremo creado utilizando CREATE ENDPOINT. Tenga en cuenta que es un campo opcional. El encabezado HTTP Hostidentifica el servidor al que se envía la solicitud HTTP.
Elemento <soap:Envelope>
Los detalles de una solicitud SOAP se incluyen en el elemento <Body> de SOAP ENVELOPE. En el ejemplo anterior se solicita el método GetCustomerInfo. El atributo xmlns de <GetCustomerInfo> es el mismo espacio de nombres que se especifica para este método que ha creado el extremo utilizando CREATE ENDPOINT. Para obtener más información acerca del procedimiento almacenado y el espacio de nombres, vea Aplicaciones de ejemplo para enviar solicitudes de servicios web XML nativos. Los siguientes parámetros de método se pasan como elementos secundarios del elemento <GetCustomerInfo>:
El elemento <CustomerID> que tiene el valor 1 es el parámetro de entrada
El elemento <OutputParam> es el parámetro de salida.
Procesar parámetros de entrada
Los parámetros de entrada se procesan de las formas siguientes:
Si un método SOAP requiere un parámetro de entrada y ese parámetro no se incluye en la solicitud SOAP, no se pasa ningún valor al procedimiento almacenado al que se llama. Se produce la acción predeterminada definida en el procedimiento almacenado.
Si un método SOAP requiere un parámetro de entrada y ese parámetro se incluye en la solicitud pero no se le asigna ningún valor, el parámetro se pasa al procedimiento almacenado con una cadena vacía como valor. Tenga en cuenta que no es NULL.
Si una operación SOAP requiere un parámetro de entrada y si desea enviar un valor NULL para ese parámetro, debe establecer un atributo xsi:nil como "true" en la solicitud SOAP. Por ejemplo:
<GetCustomerInfo xmlns="http://tempUri.org/" > <CustomerID xsi:nil="true" /> <OutputParam /> </GetCustomerInfo>En Visual Studio 2005, cuando se pasan valores NULL a las variables de la cadena, se genera el atributo xsi:nil="true" en la solicitud SOAP. Pero cuando se pasan valores NULL para parámetros de tipos como integer y float (tipos de valores), Visual Studio 2005 no genera el atributo xsi:nil="true"; en su lugar, proporciona valores predeterminados para esos parámetros; por ejemplo, 0 para tipos integer, 0,0 para tipos float, etc. Por lo tanto, si desea pasar valores NULL a esos tipos de parámetros, debe generar el mensaje SOAP en su aplicación utilizando el atributo xsi:nil="true". Para obtener más información, vea Directrices y limitaciones de los servicios Web XML nativos.
Puede proporcionar varias facetas en los parámetros. En una tabla que se muestra más adelante en este tema, se enumeran las diversas facetas que puede especificar cuando solicite consultas SQL ad hoc. En esta tabla, todas las facetas que puede especificar para un nodo <Value> se pueden especificar en los nodos de parámetros del método RPC.
Formato de los mensajes de solicitud SOAP cuando se solicitan consultas SQL ad hoc
Cuando se envía una solicitud SOAP para ejecuciones de consultas SQL ad hoc, se debe llamar al método sqlbatch y pasar las consultas y los parámetros que sean necesarios.
En el siguiente ejemplo de solicitud HTTP SOAP se llama al método sqlbatch. Tenga en cuenta que solamente se muestra un fragmento del encabezado 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>
Encabezado HTTP
En el encabezado HTTP, tenga en cuenta que el valor del campo del encabezado HTTP SoapAction es el nombre del método (sqlbatch) que el cliente utiliza para especificar consultas SQL. Tenga en cuenta que el encabezado es opcional.
Elemento <soap:Envelope>
Los detalles de la solicitud SOAP aparecen en el elemento <Body>. El elemento <Body> de SOAP solamente tiene un elemento secundario (<sqlbatch>) que identifica el método solicitado. La operación sqlbatch se define en el espacio de nombres identificado en el elemento. Este elemento tiene los siguientes elementos secundarios:
El elemento <BatchCommands> especifica la consulta o las consultas separadas por punto y coma (;) que se van a ejecutar.
El elemento <Parameters> proporciona una lista opcional de parámetros. En el anterior ejemplo de sobre de solicitud, solamente se pasa un parámetro a la consulta. Cada parámetro se agrega al mensaje SOAP como un elemento secundario <SqlParameter> del elemento <Parameters>. Al pasar los parámetros, debe pasar como mínimo el nombre del parámetro (atributo Name del elemento <SqlParameter>) y el valor del parámetro (elemento secundario <Value> del elemento <SqlParameter>).
Para evitar conversiones no esperadas, proporcione tanta información sobre los parámetros como pueda. En la tabla siguiente se enumeran las facetas de parámetros adicionales que se pueden especificar para el elemento <SqlParameter>. También puede especificar algunas de estas facetas para el elemento <Value>.
Para las facetas que se pueden especificar en los elementos <SqlParameter> y <Value>, cuando especifique el elemento <Value>, las facetas deben estar en el espacio de nombres https://schemas.microsoft.com/sqlserver/2004/sqltypes, como se muestra en el siguiente ejemplo:
<Value xsi:type="xsd:string" sqltypes:maxLength="100" xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">1</Value>
Faceta del parámetro |
Comentario |
Se puede especificar en el nodo |
|---|---|---|
direction |
Especifica la dirección del parámetro (Input, InputOutput). Input es el valor predeterminado. |
<SqlParameter> |
localeID |
Define la configuración regional de Windows para la intercalación de los tipos de caracteres. Equivalente al valor del LCID devuelto por COLLATIONPROPERTY intrínseco. |
<SqlParameter> <Value> |
maxLength |
El atributo del elemento <SqlParameter> proporciona la máxima longitud del valor del parámetro. El valor predeterminado es 1. |
<SqlParameter> <Value> |
name |
El atributo del elemento <SqlParameter> proporciona el nombre del parámetro. |
<SqlParameter> |
outputRequested |
Se puede aplicar a los elementos del parámetro para indicar si se debe emitir la salida. El comportamiento predeterminado depende del parameterMode que se utilice, si es explícito o el valor predeterminado. Si el atributo se establece en "true" en un parámetro de entrada, generará un error. |
<Valor> |
precision |
Este atributo del elemento <SqlParameter> proporciona la precisión del valor del parámetro. El valor predeterminado es 18. |
<SqlParameter> <Value> |
scale |
Este atributo del elemento <SqlParameter> proporciona la escala del valor del parámetro. El valor predeterminado es 0. |
<SqlParameter> <Value> |
sqlCompareOptions |
Define las opciones de comparación que se utilizarán para la intercalación de los tipos de caracteres. Es una enumeración de los valores que se pueden combinar que coincide con el valor de ComparisonStyle devuelto por el COLLATIONPROPERTY intrínseco. |
<SqlParameter><Valor> |
sqlDbType |
Especifica el tipo de parámetro. |
<SqlParameter> |
clrTypeName |
Se utiliza para especificar argumentos de tipo definido por el usuario CLR. clrTypeName puede contener el nombre de tres partes. |
<SqlParameter> <Valor> |
useDefaultValue |
Indica que debe utilizarse un valor predeterminado para un parámetro. El elemento de parámetro se puede omitir en la lista o, alternativamente, puede especificarse el atributo Booleano useDefaultValue con un valor de "true". El valor predeterminado de este atributo es "false" si el elemento se incluye y "true" si se omite. |
<SqlParameter> <Valor> |
XmlNamespace |
Especifica el espacio de nombres del esquema XML asociado al parámetro de tipo xml. |
<SqlParameter> <Value> |
xsi:type |
Especifica el tipo de valor. Para obtener más información acerca de cómo la faceta xsi:type se asigna a tipos de datos del sistema SQL Server, vea Asignaciones de tipos de datos de los servicios Web XML nativos. |
<Valor> |
typename |
Se utiliza para especificar argumentos de tipo definido por el usuario. typename puede contener el nombre de tres partes. |
<SqlParameter> <Valor> |