Структура сообщения SOAP-запроса
В будущей версии Microsoft SQL Server эта возможность будет удалена. Избегайте использования этой возможности в новых разработках и запланируйте изменение существующих приложений, в которых она применяется.
Если требуется, чтобы клиент SOAP создавал собственные запросы SOAP вместо использования классов-посредников, предусмотренных в Visual Studio 2005, необходимо использовать следующие форматы сообщений.
Формат сообщения SOAP-запроса для хранимых процедур и определяемых пользователем типов
Следующий образец иллюстрирует типичный запрос SOAP, отправляемый экземпляру SQL Server. В сообщении SOAP запрашивается операция GetCustomerInfo. Следует отметить, что отображается лишь фрагмент заголовка 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>
Заголовок HTTP
В вышеприведенном коде значение поля заголовка HTTP SoapAction — это имя метода, перед которым следует его пространство имен. Этим значением является тот же метод и пространство имен, что и добавленное в конечную точку, которая создана с помощью инструкции CREATE ENDPOINT. Следует отметить, что заполнение этого поля необязательно. Поле заголовка HTTP Host определяет сервер, которому отправляется запрос HTTP.
Элемент <soap:Envelope>
Сведения о запросе SOAP включаются в элемент <Body> конверта SOAP. В предыдущем примере запрашивается метод GetCustomerInfo. Атрибут xmlns в <GetCustomerInfo> — это то же пространство имен, что и заданное в методе, для которого создана конечная точка с помощью инструкции CREATE ENDPOINT. Дополнительные сведения о хранимых процедурах и пространствах имен см. в разделе Образцы приложений, отправляющих запросы к собственным веб-службам с поддержкой XML. Следующие параметры метода передаются в качестве дочерних элементов для <GetCustomerInfo>.
Элемент <CustomerID> со значением 1 — это входной параметр.
Элемент <OutputParam> — это выходной параметр.
Обработка входных параметров
Входные параметры обрабатываются следующими способами.
Если в методе SOAP требуется входной параметр, который не включен в запрос SOAP, в вызванную хранимую процедуру не передаются значения. Выполняется действие по умолчанию, определенное в хранимой процедуре.
Если в методе SOAP требуется входной параметр, который включен в запрос, но ему не присвоено значение, этот параметр передается в хранимую процедуру с пустой строкой в качестве значения. Следует отметить, что это значение не равно NULL.
Если в операции SOAP требуется входной параметр и ему следует присвоить значение NULL, необходимо задать атрибуту xsi:nil значение "true" в запросе SOAP. Например:
<GetCustomerInfo xmlns="http://tempUri.org/" > <CustomerID xsi:nil="true" /> <OutputParam /> </GetCustomerInfo>В Visual Studio 2005 при передаче в строковые переменные значений NULL в запросе SOAP формируется атрибут xsi:nil="true". Однако в случае передачи значений NULL для параметров таких типов, как integer и float (типов значений), Visual Studio 2005 не формирует атрибут xsi:nil="true", а вместо этого предоставляет этим параметрам значения по умолчанию. Например, значение 0 — для типов integer, 0,0 — для типов float и т. д. Следовательно, если требуется передать значения NULL в эти типы параметров, необходимо сконструировать сообщение SOAP в приложении с помощью атрибута xsi:nil="true". Дополнительные сведения см. в разделе Правила и ограничения собственных веб-служб с поддержкой XML.
Параметрам можно предоставлять несколько аспектов. Далее в разделе приведена таблица, содержащая несколько аспектов, которые можно указывать при выполнении нерегламентированных запросов SQL. В этой таблице все аспекты, которые можно задавать для узла <Value>, могут определяться в узлах параметров методов RPC.
Формат сообщения-запроса SOAP при выполнении нерегламентированных запросов SQL
При отправке запроса SOAP на выполнение нерегламентированного запроса SQL следует вызвать метод sqlbatch и передать запросы и все требуемые параметры.
В следующем образце запрос HTTP SOAP вызывает метод sqlbatch. Следует отметить, что отображается лишь фрагмент заголовка 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>
Заголовок HTTP
Следует отметить, что значение поля заголовка HTTP SoapAction — это имя метода (sqlbatch), используемого клиентом для задания запросов SQL. Следует отметить, что этот заголовок необязателен.
Элемент <soap:Envelope>
Сведения о запросе SOAP выводятся в элементе <Body>. Элемент SOAP <Body> имеет только один дочерний элемент (<sqlbatch>), который определяет запрошенный метод. Пространство имен, задаваемое в элементе, принадлежит пространству, где определяется операция sqlbatch. Данный элемент имеет следующие дочерние элементы.
Элемент <BatchCommands> задает один или несколько выполняемых запросов, разделенных точкой с запятой (;).
Элемент <Parameters> содержит необязательный список параметров. В конверте запроса предыдущего примера в запрос передается только один параметр. Все параметры добавляются в сообщение SOAP в качестве дочерних элементов <SqlParameter> элемента <Parameters>. При их передаче необходимо указывать по меньшей мере имя параметра (атрибут Name элемента <SqlParameter>) и значение параметра (дочерний элемент <Value> элемента <SqlParameter>).
Чтобы избежать непредвиденных преобразований, предоставляйте максимально подробные сведения о параметрах. В следующей таблице перечислены аспекты параметров, которые можно задавать для элемента <SqlParameter>. Некоторые из них также можно задавать для элемента <Value>.
Аспекты, которые можно задавать для обоих элементов (<SqlParameter> и <Value>), при задании элемента <Value> должны быть в пространстве имен https://schemas.microsoft.com/sqlserver/2004/sqltypes, например:
<Value xsi:type="xsd:string" sqltypes:maxLength="100" xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">1</Value>
Аспект параметра |
Комментарий |
Можно задавать в узле |
|---|---|---|
direction |
Определяет направление параметра (Input, InputOutput). Input — это значение по умолчанию. |
<SqlParameter> |
localeID |
Задает языковой стандарт Windows для параметров сортировки символьных типов. Эквивалент значения кода языка, возвращаемого внутренним свойством COLLATIONPROPERTY. |
<SqlParameter> <Значение> |
maxLength |
Атрибут элемента <SqlParameter> содержит максимальную длину значения параметра. По умолчанию установлено значение 1. |
<SqlParameter> <Значение> |
name |
Атрибут элемента <SqlParameter> содержит имя параметра. |
<SqlParameter> |
outputRequested |
Может применяться к элементам параметра, чтобы указать, должен ли он выдавать результаты. Режим работы по умолчанию зависит от значения parameterMode, неявного или по умолчанию. Если этому атрибуту во входном параметре присвоено значение "true", возникает ошибка. |
<Значение> |
precision |
Этот атрибут элемента <SqlParameter> содержит точность значения параметра. По умолчанию установлено значение 18. |
<SqlParameter> <Значение> |
scale |
Этот атрибут элемента <SqlParameter> содержит масштаб значения параметра. По умолчанию установлено значение 0. |
<SqlParameter> <Значение> |
sqlCompareOptions |
Определяет параметры сравнения, используемые для параметров сортировки символьных типов. Является перечислением значений, которые можно объединить со значением ComparisonStyle, возвращаемым внутренним свойством COLLATIONPROPERTY. |
<SqlParameter><Значение> |
sqlDbType |
Определяет тип параметра. |
<SqlParameter> |
clrTypeName |
Указывает аргументы определяемого пользователем типа данных CLR. Аспект clrTypeName может содержать трехкомпонентное имя. |
<SqlParameter> <Значение> |
useDefaultValue |
Указывает, что для параметра должно быть использовано значение по умолчанию. Элемент параметра можно исключить из списка либо указать логический атрибут useDefaultValue со значением "true". По умолчанию этот атрибут имеет значение "false", если элемент включен, и "true", если элемент пропущен. |
<SqlParameter> <Значение> |
XmlNamespace |
Задает пространство имен XML-схемы, связанной с типом параметра xml. |
<SqlParameter> <Значение> |
xsi:type |
Определяет тип значения. Дополнительные сведения о том, как аспект xsi:type сопоставляется с системными типами данных SQL Server, см. в разделе Сопоставления типов данных в собственных веб-службах с поддержкой XML. |
<Значение> |
typename |
Указывает аргументы определяемого пользователем типа. Аспект typename может содержать трехкомпонентное имя. |
<SqlParameter> <Значение> |