Структура сообщения-запроса SOAP

Статья
12/15/2008

Если требуется, чтобы клиент SOAP создавал собственные запросы SOAP вместо использования классов-посредников, предусмотренных в Visual Studio 2005, необходимо использовать следующие форматы сообщений.

Формат сообщения-запроса SOAP для хранимых процедур и типов, определяемых пользователем

Следующий пример иллюстрирует типичный запрос SOAP, отправляемый экземпляру SQL Server 2005. В сообщении SOAP запрашивается операция GetCustomerInfo. Следует отметить, что отображается лишь фрагмент заголовка HTTP.

Заголовок 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. Например:
```
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>
```
В 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.

Заголовок 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, например:

<GetCustomerInfo xmlns="http://tempUri.org/" >
  <CustomerID xsi:nil="true" />
  <OutputParam />
</GetCustomerInfo>

Аспект параметра	Комментарий	Можно задавать в узле
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	Определяет тип параметра. Список системных типов данных SQL Server 2005, которые можно задавать, см. в разделе Сопоставления типов данных в собственных веб-службах с поддержкой XML.	<SqlParameter>
typeName	Задает аргументы типа, определяемого пользователем. Параметр typeName должен содержать имя из трех частей.	<SqlParameter> <Значение>
useDefaultValue	Указывает, что для параметра должно быть использовано значение по умолчанию, при этом элемент параметра можно исключить из списка либо задать логический атрибут useDefaultValue со значением true. По умолчанию этот атрибут имеет значение false, если элемент включен, и true, если элемент исключен.	<SqlParameter> <Значение>
XmlNamespace	Задает пространство имен XML-схемы, связанной с типом параметра xml.	<SqlParameter> <Значение>
xsi:type	Определяет тип значения. Дополнительные сведения о том, как аспект xsi:type сопоставляется с системными типами данных SQL Server 2005, см. в разделе Сопоставления типов данных в собственных веб-службах с поддержкой XML.	<Значение>

См. также

Справочник

Структура запроса и ответного сообщения SOAP
Дополнительные SOAP-заголовки
Структура сообщения-ответа SOAP
Структура сообщения о сбое SOAP
Пространства имен, используемые в запросах и ответах SOAP

Справка и поддержка

Получение помощи по SQL Server 2005