Struttura dei messaggi di richiesta SOAP

Articolo
12/15/2008

Nel seguente argomento vengono illustrati i formati dei messaggi che è necessario utilizzare per consentire a un client SOAP di costruire le proprie richieste SOAP invece di utilizzare le classi proxy offerte da Visual Studio 2005.

Formato dei messaggi di richiesta SOAP per stored procedure e tipi definiti dall'utente

Nell'esempio seguente viene mostrata una tipica richiesta SOAP inviata a un'istanza di SQL Server 2005. Nel messaggio SOAP viene richiesta l'operazione GetCustomerInfo. Si noti che viene mostrato solo un frammento dell'intestazione 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>

Intestazione HTTP

Nell'esempio di codice precedente, il valore del campo SoapAction dell'intestazione HTTP è il nome di metodo preceduto dal suo spazio dei nomi. Questo valore rappresenta lo stesso metodo e lo stesso spazio dei nomi aggiunti all'endpoint creato utilizzando CREATE ENDPOINT. Si noti che si tratta di un campo facoltativo. Il campo Host dell'intestazione HTTP identifica il server al quale viene inviata la richiesta HTTP.

Elemento <soap:Envelope>

I dettagli di una richiesta SOAP vengono racchiusi nell'elemento <Body> all'interno della busta SOAP. Nell'esempio precedente viene richiesto il metodo GetCustomerInfo. L'attributo xmlns in <GetCustomerInfo> è lo stesso spazio dei nomi specificato per il metodo con cui è stato creato l'endpoint utilizzando CREATE ENDPOINT. Per ulteriori informazioni sulla stored procedure e sullo spazio dei nomi, vedere Applicazioni di esempio per l'invio di richieste ai servizi Web XML nativi. I seguenti parametri di metodo vengono passati come elementi figlio dell'elemento <GetCustomerInfo>:

L'elemento <CustomerID> che ha valore 1 è il parametro di input.
L'elemento <OutputParam> è il parametro di output.

Gestione dei parametri di input

I parametri di input vengono gestiti nei modi seguenti:

Se un metodo SOAP richiede un parametro di input e questo non è incluso nella richiesta SOAP, alla stored procedure chiamata non viene passato alcun valore. Si verifica l'azione predefinita della stored procedure.
Se un metodo SOAP richiede un parametro di input e questo è incluso nella richiesta ma senza alcun valore a esso assegnato, alla stored procedure viene passato il parametro avente come valore una stringa vuota. Si noti che il valore non è NULL.
Se un'operazione SOAP richiede un parametro di input e si desidera inviare il valore NULL per tale parametro, è necessario impostare un attributo xsi:nil su "true" nella richiesta SOAP. Ad esempio:
```
<GetCustomerInfo xmlns="http://tempUri.org/" >
  <CustomerID xsi:nil="true" />
  <OutputParam />
</GetCustomerInfo>
```
In Visual Studio 2005, quando si passano valori NULL a variabili stringa viene generato l'attributo xsi:nil="true" nella richiesta SOAP. Quanto tuttavia si passano valori NULL per parametri di tipo, ad esempio, integer o float (tipi valore), Visual Studio 2005 non genera l'attributo xsi:nil="true". Per tali parametri vengono al contrario assegnati valori predefiniti (ad esempio 0 per tipi integer, 0,0 per tipi float e così via). Se pertanto nella propria applicazione si desidera passare valori NULL a questi tipi di parametri, è necessario costruire il messaggio SOAP utilizzando l'attributo xsi:nil="true". Per ulteriori informazioni, vedere Linee guida e limitazioni per i servizi Web XML nativi.
Sui parametri è possibile implementare diversi facet. Nella tabella riportata di seguito in questo argomento vengono elencati diversi facet che è possibile specificare quando si richiedono query SQL ad hoc. In questa tabella, tutti i facet che è possibile specificare per un nodo <Value> possono essere specificati sui nodi dei parametri dei metodi RPC.

Formato dei messaggi di richiesta SOAP per la richiesta di query SQL ad hoc

Quando si invia una richiesta SOAP per esecuzioni di query SQL ad hoc, è necessario chiamare il metodo sqlbatch e passare le query e ogni altro parametro necessario.

Nella richiesta SOAP HTTP di esempio seguente viene chiamato il metodo sqlbatch. Si noti che viene mostrato solo un frammento dell'intestazione 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>

Intestazione HTTP

Si noti che il valore del campo SoapAction all'interno dell'intestazione HTTP è il nome del metodo (sqlbatch) utilizzato dal client per specificare query SQL. Questa intestazione è facoltativa.

Elemento <soap:Envelope>

I dettagli della richiesta SOAP sono inclusi nell'elemento <Body>. L'elemento <Body> SOAP presenta un unico elemento figlio (<sqlbatch>) e identifica il metodo richiesto. L'operazione sqlbatch viene definita nello spazio dei nomi identificato nell'elemento. Questo elemento presenta gli elementi figli seguenti:

L'elemento <BatchCommands> specifica la query o le query da eseguire, separate da punti e virgola (;).
L'elemento <Parameters> contiene un elenco facoltativo di parametri. Nella busta della richiesta dell'esempio precedente c'è un solo parametro passato alla query. Tutti i parametri vengono aggiunti al messaggio SOAP come elementi figlio <SqlParameter> dell'elemento <Parameters>. Nel passaggio dei parametri è necessario passare almeno il nome del parametro (attributo Name dell'elemento <SqlParameter>) e il valore del parametro (elemento figlio <Value> dell'elemento <SqlParameter>).

Per evitare conversioni inattese, specificare quante più informazioni possibile sui parametri. Nella tabella seguente vengono elencati facet di parametri aggiuntivi che è possibile specificare per l'elemento <SqlParameter>. È inoltre possibile specificare alcuni di questi facet per l'elemento <Value>.

Per i facet che è possibile specificare sia sull'elemento <SqlParameter> che sull'elemento <Value>, quando si specifica l'elemento <Value> è necessario che i facet siano nello spazio dei nomi https://schemas.microsoft.com/sqlserver/2004/sqltypes, come mostrato nell'esempio seguente:

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

Facet del parametro	Commenti	Nodo su cui è possibile specificare il facet
direction	Specifica la direzione del parametro (Input, InputOutput). La direzione predefinita è Input.	<SqlParameter>
localeID	Definisce le impostazioni internazionali per le regole di confronto dei tipi carattere. Equivalente al valore di LCID restituito dalla funzione intrinseca COLLATIONPROPERTY.	<SqlParameter> <Value>
maxLength	Attributo dell'elemento <SqlParameter>, specifica la lunghezza massima del valore del parametro. Il valore predefinito è 1.	<SqlParameter> <Value>
name	Attributo dell'elemento <SqlParameter>, specifica il nome del parametro.	<SqlParameter>
outputRequested	Può essere applicato agli elementi del parametro per indicare se esso deve emettere output. Il funzionamento predefinito dipende dalla modalità specificata in parameterMode (esplicita o predefinita). Se l'attributo viene impostato su "true" su un parametro di input, verrà generato un errore.	<Value>
precision	Attributo dell'elemento <SqlParameter>, specifica la precisione del valore del parametro. Il valore predefinito è 18.	<SqlParameter> <Value>
scale	Attributo dell'elemento <SqlParameter>, specifica la scala del valore del parametro. Il valore predefinito è 0.	<SqlParameter> <Value>
sqlCompareOptions	Definisce le opzioni di confronto da utilizzare per le regole di confronto dei tipi carattere. Enumerazione di valori che possono essere combinati corrispondente al valore di ComparisonStyle restituito dalla funzione intrinseca COLLATIONPROPERTY.	<SqlParameter><Value>
sqlDbType	Specifica il tipo di parametro. Per un elenco dei tipi di dati di sistema di SQL Server 2005 che è possibile specificare, vedere Mapping dei tipi di dati in servizi Web XML nativi.	<SqlParameter>
typeName	Utilizzato per specificare gli argomenti dei tipi definiti dall'utente. typeName deve contenere il nome in tre parti.	<SqlParameter> <Value>
useDefaultValue	Indica la necessità di utilizzare un valore predefinito per un parametro. L'elemento del parametro può essere omesso dall'elenco o, in alternativa, è possibile specificare l'attributo booleano useDefaultValue con il valore "true". Il valore predefinito di questo attributo è "false" se l'elemento viene incluso e "true" se l'elemento viene omesso.	<SqlParameter> <Value>
XmlNamespace	Specifica lo spazio dei nomi dello schema XML associato al parametro di tipo xml.	<SqlParameter> <Value>
xsi:type	Specifica il tipo di valore. Per ulteriori informazioni sulle modalità di esecuzione del mapping dei facet xsi:type nei tipi di dati di sistema di SQL Server 2005, vedere Mapping dei tipi di dati in servizi Web XML nativi.	<Value>

Vedere anche

Riferimento

Struttura dei messaggi di richiesta e di risposta SOAP
Intestazioni di estensioni SOAP
Struttura del messaggio di risposta SOAP
Struttura dei messaggi di errore SOAP
Spazi dei nomi utilizzati nelle richieste e nelle risposte SOAP

Guida in linea e informazioni

Assistenza su SQL Server 2005

Condividi tramite