Struttura dei messaggi di richiesta SOAP
Questa caratteristica verrà rimossa a partire da una delle prossime versioni di Microsoft SQL Server. Evitare di utilizzare questa funzionalità in un nuovo progetto di sviluppo e prevedere interventi di modifica nelle applicazioni in cui è attualmente implementata.
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 illustrata una tipica richiesta SOAP inviata a un'istanza di SQL Server. 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 impreviste, fornire quante più informazioni sui parametri possibile. Nella tabella seguente vengono elencati facet di parametro 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 locali per le regole di confronto dei tipi carattere. Equivalente al valore di LCID restituito dalla funzione intrinseca COLLATIONPROPERTY. |
<SqlParameter> <Valore> |
maxLength |
Attributo dell'elemento <SqlParameter>, specifica la lunghezza massima del valore del parametro. Il valore predefinito è 1. |
<SqlParameter> <Valore> |
name |
Attributo dell'elemento <SqlParameter>, specifica il nome del parametro. |
<SqlParameter> |
outputRequested |
Può essere applicato agli elementi del parametro per indicare se questo deve emettere output. Il funzionamento predefinito dipende dalla modalità specificata in parameterMode (esplicita o predefinita). Se l'attributo è impostato su "true" in un parametro di input, verrà generato un errore. |
<Valore> |
precision |
Questo attributo dell'elemento <SqlParameter>, specifica la precisione del valore del parametro. Il valore predefinito è 18. |
<SqlParameter> <Valore> |
scale |
Questo attributo dell'elemento <SqlParameter>, specifica la scala del valore del parametro. Il valore predefinito è 0. |
<SqlParameter> <Valore> |
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. |
<SqlParameter> |
clrTypeName |
Utilizzato per specificare gli argomenti dei tipi CLR definiti dall'utente. clrTypeName può contenere il nome in tre parti. |
<SqlParameter> <Valore> |
useDefaultValue |
Indica che per un parametro deve essere utilizzato un valore predefinito. 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> <Valore> |
XmlNamespace |
Specifica lo spazio dei nomi dello schema XML associato al parametro di tipo xml. |
<SqlParameter> <Valore> |
xsi:type |
Specifica il tipo di valore. Per ulteriori informazioni sul modo in cui il facet xsi:type viene mappato ai tipi di dati di sistema di SQL Server, vedere Mapping dei tipi di dati in servizi Web XML nativi. |
<Valore> |
typename |
Utilizzato per specificare gli argomenti dei tipi CLR definiti dall'utente. typename può contenere il nome in tre parti. |
<SqlParameter> <Valore> |