Estrutura de mensagens de solicitação SOAP
Esse recurso será removido em uma versão futura do Microsoft SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.
Se você quiser que o seu cliente SOAP crie suas próprias solicitações SOAP em vez de usar as classes de proxy fornecidas pelo Visual Studio 2005, você deve usar os seguintes formatos de mensagem.
Formato da mensagem de solicitação SOAP para procedimentos armazenados e tipos definidos pelo usuário
O seguinte exemplo mostra uma solicitação SOAP típica enviada a uma instância do SQL Server. Na mensagem SOAP, a operação GetCustomerInfo é solicitada. Observe que só um fragmento do cabeçalho HTTP é mostrado.
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>
Cabeçalho HTTP
No código anterior, o valor do campo de cabeçalho HTTP SoapAction é o nome de método precedido por seu namespace. Esse valor é o mesmo método e namespace que você adicionou ao ponto de extremidade criado usando CREATE ENDPOINT. Observe que este campo é opcional. O campo de cabeçalho HTTP Host identifica o servidor para o qual a solicitação HTTP é enviada.
<soap:Envelope> Element
Os detalhes de uma solicitação SOAP são incluídos no elemento <Body> no envelope SOAP. O exemplo anterior solicita o método GetCustomerInfo. O atributo xmlns em <GetCustomerInfo> é o mesmo namespace que é especificado para este método para o qual você criou o ponto de extremidade usando CREATE ENDPOINT. Para obter mais informações sobre o procedimento armazenado e o namespace, consulte Aplicativos de exemplo para enviar solicitações de XML Web Services Nativos. Os seguintes parâmetros de método são passados como elementos filhos do elemento <GetCustomerInfo>:
O elemento <CustomerID> que tem valor 1 é o parâmetro de entrada
O elemento <OutputParam> é o parâmetro de saída.
Manipulação de parâmetros de entrada
Os parâmetros de entrada são manipulados das seguintes formas:
Se um método SOAP exigir um parâmetro de entrada e esse parâmetro não tiver sido incluído na solicitação SOAP, nenhum valor será passado ao procedimento armazenado chamado. A ação padrão definida no procedimento armazenado ocorre.
Se um método SOAP exigir um parâmetro de entrada e esse parâmetro tiver sido incluído na solicitação, mas nenhum valor tiver sido atribuído a ele, o parâmetro será passado ao procedimento armazenado com uma cadeia de caracteres vazia como valor. Observe que não é NULL.
Se uma operação SOAP exigir um parâmetro de entrada e se você quiser enviar um valor NULL para esse parâmetro, deverá definir um atributo xsi:nil como "true" na solicitação SOAP. Por exemplo:
<GetCustomerInfo xmlns="http://tempUri.org/" > <CustomerID xsi:nil="true" /> <OutputParam /> </GetCustomerInfo>No Visual Studio 2005, quando você passa valores NULL para variáveis de cadeia de caracteres, isto gera o atributo xsi:nil = "true" na solicitação SOAP. Mas quando você passa valores NULL para parâmetros de tipos como integer e float (tipos de valor), o Visual Studio 2005 não gera o atributo xsi:nil="true"; em vez disso, ele fornece os valores padrão para esses parâmetros; por exemplo, 0 para tipos integer, 0,0 para tipos float e assim por diante. Portanto, se você quiser passar valores NULL para esses tipos de parâmetros, deverá criar a mensagem SOAP no seu aplicativo usando o atributo xsi:nil="true". Para obter mais informações, consulte Diretrizes e limitações dos XML Web Services Nativos
Você pode fornecer várias facetas dos parâmetros. Uma tabela mostrada mais adiante neste tópico lista várias facetas que você pode especificar quando solicitar consultas SQL ad hoc. Nessa tabela, podem ser especificadas todas as facetas que você pode especificar para um nó <Value> nos nós de parâmetro de método do RPC.
Formato da mensagem de solicitação SOAP ao solicitar consultas SQL ad hoc
Quando você envia uma solicitação SOAP para execuções de consultas SQL ad hoc, deve chamar o método sqlbatch e passar as consultas e quaisquer parâmetros que possam ser necessários.
O seguinte exemplo de solicitação do SOAP HTTP chama o método sqlbatch. Observe que só um fragmento do cabeçalho HTTP é mostrado.
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>
Cabeçalho HTTP
No cabeçalho HTTP, observe que o valor do campo do cabeçalho HTTP SoapAction é o nome do método (sqlbatch) que o cliente usa para especificar consultas SQL. Observe que este cabeçalho é opcional.
<soap:Envelope> Element
Os detalhes da solicitação SOAP são exibidos no elemento <Body>. O elemento SOAP <Body> tem só um elemento filho (<sqlbatch>) e identifica o método solicitado. O namespace identificado no elemento é onde a operação sqlbatch é definida. Este elemento tem os seguintes elementos filhos:
O elemento <BatchCommands> especifica a consulta ou as consultas separadas por ponto-e-vírgula (;) a serem executadas.
O elemento <Parameters> fornece uma lista opcional de parâmetros. No envelope de solicitação do exemplo anterior, existe somente um parâmetro passado para a consulta. Cada parâmetro é adicionado à mensagem SOAP como um elemento filho <SqlParameter> do elemento<Parameters>. Ao passar os parâmetros, você deve passar pelo menos o nome do parâmetro (atributo (Name do elemento <SqlParameter>) e o valor do parâmetro (elemento filho <Value> do elemento <SqlParameter>).
Para evitar conversões inesperadas, forneça o máximo de informações do parâmetro que puder. A seguinte tabela lista facetas de parâmetros adicionais que você pode especificar para o elemento <SqlParameter>. Você também pode especificar algumas destas facetas para o elemento <Value>.
Para facetas que podem ser especificadas no <SqlParameter> e também no elemento <Value>, quando você especificar o elemento <Value>, as facetas deverão estar no namespace https://schemas.microsoft.com/sqlserver/2004/sqltypes, conforme mostrado no exemplo a seguir:
<Value xsi:type="xsd:string" sqltypes:maxLength="100" xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">1</Value>
Faceta de parâmetro |
Comentário |
Pode ser especificado no nó |
|---|---|---|
direção |
Especifica a direção do parâmetro (Input, InputOutput). Input é o padrão. |
<SqlParameter> |
localeID |
Define a localidade das janelas para o agrupamento de tipos de caractere. Equivalente ao valor de LCID retornado pela COLLATIONPROPERTY intrínseca. |
<SqlParameter> <Valor> |
maxLength |
O atributo do elemento <SqlParameter> elemento fornece o comprimento máximo do valor do parâmetro. O valor padrão é 1. |
<SqlParameter> <Valor> |
name |
O atributo do elemento <SqlParameter> fornece o nome do parâmetro. |
<SqlParameter> |
outputRequested |
Pode ser se aplicado aos elementos de parâmetro para indicar se deveria emitir saída. O comportamento padrão depende do parameterMode usado, se é explícito ou padrão. Se o atributo for definido como "true" em um parâmetro de entrada, será gerado um erro. |
<Valor> |
precision |
Este atributo do elemento <SqlParameter> fornece a precisão do valor do parâmetro. O valor padrão é 18. |
<SqlParameter> <Valor> |
scale |
Este atributo do elemento <SqlParameter> fornece a escala do valor do parâmetro. O padrão é 0. |
<SqlParameter> <Valor> |
sqlCompareOptions |
Define as opções de comparação a serem usadas para o agrupamento de tipos de caractere. É uma enum de valores que podem ser combinados de acordo com o valor ComparisonStyle retornado pela COLLATIONPROPERTY intrínseca. |
<SqlParameter><- Valor> |
sqlDbType |
Especifica o tipo do parâmetro. Para obter uma lista dos tipos de dados do sistema do SQL Server que você pode especificar, consulte Mapeamentos de tipo de dados em XML Web Services Nativos. |
<SqlParameter> |
clrTypeName |
Usado para especificar argumentos de tipo do CLR definidos pelo usuário. clrTypeName pode conter o nome em três partes. |
<SqlParameter> <Valor> |
useDefaultValue |
Indica que um valor padrão deve ser usado para um parâmetro. O elemento de parâmetro pode ser omitido da lista ou, alternativamente, o atributo Boolean useDefaultValue com um valor "true" pode ser especificado. O valor padrão desse atributo será "false" se o elemento for incluído e "true" se o elemento for omitido. |
<SqlParameter> <Valor> |
XmlNamespace |
Especifica o namespace de esquema XML associado ao parâmetro de tipo xml. |
<SqlParameter> <Valor> |
xsi:type |
Especifica o tipo do valor. Para obter mais informações sobre como a faceta xsi:type é mapeada para os tipos de dados do sistema do SQL Server, consulte Mapeamentos de tipo de dados em XML Web Services Nativos. |
<Valor> |
typename |
Usado para especificar argumentos de tipo definidos pelo usuário. typename pode conter o nome em três partes. |
<SqlParameter> <Valor> |