XML Web-службы в Microsoft SQL Server 2005 - Описание структуры сообщений SOAP

Written on . Posted in MS SQL Server

ОГЛАВЛЕНИЕ

Страница 18 из 19

Описание структуры сообщений SOAP

Запрос

Формат вызова Web-метода не изменился, однако у клиента появилась новая возможность выполнять пакетные команды. Структура запроса при этом выглядит так:

<env:Body>
<sqlbatch xmlns=»http://schemas.microsoft. com/sqlserver/2004/SOAP»>
<BatchCommands> любое TSQL выражение</BatchCommands>
<Parameters>
<SqlParameter xmlns=»http://schemas.microsoft.com/ sqlserver/2004/SOAP/types/SqlParameter»>*
<Value/>
</SqlParameter>
</Parameters>
</sqlbatch>
</env:Body>

Атрибуты элемента SqlParameter описывают точные свойства параметра.

  • Название параметра (указывать обязательно).
  • Тип параметра (указывать обязательно).
  • Длина строкового представления параметра (указывать обязательно).
  • Направление (direction) — входной или входной и выходной.
  • Другие свойства, описание которых можно найти в BOL.

Значение параметра задается в элементе Value, который не имеет конкретного типа по схеме XML. Его тип необходимо указывать непосредственно в сообщении с помощью атрибута xsi:type.

Элементы пакетной команды BatchCommands и Parameters должны быть в пространстве имен http://schemas.microsoft.com/sqlserver/2004/SOAP. Элементы SqlParameter и Value — в пространстве имен http://schemas.microsoft.com/ sqlserver/2004/SOAP/types/SqlParameter.

Ответ

Ответное сообщение имеет более существенные отличия от SQLXML. В нем может появляться один или более из приведенных ниже объектов.

  • Результирующие объекты выборки. Под объектами выборки понимаются xml-документы, полученные в результате запросов for xml либо сериализованные в xml (а точнее, в формат diffgram, который поддерживается классом DataSet из .Net Framework) реляционные строки.
  • Количество выбранных строк.
  • Код возврата в случае вызова хранимой процедуры или пользовательской функции.
  • Значения выходных параметров.
  • Сообщения об ошибках и предупреждениях.
  • Статус транзакции.

Вот как выглядит описание этих объектов в формате схемы XML:

<xsd:complexType name=»SqlResultStream»>
<xsd:choice minOccurs=»1» maxOccurs=»unbounded»>
<xsd:element name=»SqlRowSet» type=»sqlsoaptypes:SqlRowSet»/>
<xsd:element name=»SqlXml» type=»sqlsoaptypes:SqlXml»/>
<xsd:element name=»SqlMessage» type=»sqlmessage:SqlMessage»/>
<xsd:element name=»SqlRowCount» type=»sqlrowcount:SqlRowCount»/>
<xsd:element name=»SqlResultCode» type=»sqlsoaptypes:SqlResultCode»/>
<xsd:element name=»SqlTransaction» type=»sqltransaction:SqlTransaction»/>
</xsd:choice>
</xsd:complexType>

Как уже говорилось выше, в результирующем потоке появилось два новых элемента: SqlRowCount и SqlTransaction. Общая структура ответного сообщения такова:

<method:MethodNameResponse>
<method:MethodNameResult xmlns=»»>
<!— Объекты пространства имен sqlresultstream—>
</method:MethodNameResult>
<method:OutputParam>Value</method:OutputParam>*
</method:MethodNameResponse>

Здесь:

  • MethodName — имя Web-метод. Для пакетных запросов это sqlbatch.
  • Method — префикс пространства имен Web-метода. Для нашего Web-метода hello_world пространством имен является http://tempuri.org. Для пакетных запросов — http://schemas.microsoft.com/sqlserver/2004/SOAP.
  • OutputParam — значения выходных параметров.

Элемент MethodNameResult может содержать один или более объектов, описанных в типе SqlResultStream. Рассмотрим, в каких случаях будет использоваться тот или иной объект.

SqlRowSet — используется в случае, когда результирующий поток содержит результаты реляционной выборки. Этот элемент описан в схеме так:

<xsd:complexType name=»SqlRowSet»>
<xsd:sequence maxOccurs=»unbounded»>
<xsd:any namespace=»http://www.w3.org/2001/XMLSchema»
minOccurs=»0» processContents=»lax»/>
<xsd:any namespace=»urn:schemas-microsoft-com:xml-diffgram-v1»
minOccurs=»0» processContents=»lax»/>
</xsd:sequence>
</xsd:complexType>

Он может содержать любое количество элементов из пространства имен http://www.w3.org/2001/XMLSchema, а также любое количество элементов из пространства имен urn:schemas-microsoft-com:xml-diffgram-v1. Первое пространство имен принадлежит стандарту схемы XML и означает, что в результирующий поток может включаться XSD-схема. Это поведение регулируется с помощью параметра schema конечной точки и Web-метода. Второе пространство имен означает, что результирующая выборка будет представлена в формате diffgram, который поддерживается стандартным классом System.Data.DataSet из .Net Framework. Например, результатом выполнения листинга будет следующая diffgram (несущественные части сообщения удалены):

<diffgr:diffgram xmlns:diffgr=»urn:schemas-microsoft-com:xml-diffgram-v1»>
<SqlRowSet1 xmlns=»urn:schemas-microsoft-com:sql:SqlRowSet1»>
<row>
<EmployeeID>10</EmployeeID>
<LoginID>adventure-works\barryj</LoginID>
<Gender>M</Gender>
</row>
</SqlRowSet1>
</diffgr:diffgram>

SqlXml — используется в случае, если применяются for xml-запросы, которые возвращают xml. Нет необходимости преобразовывать результаты этих запросов в diffgram, потому что они сами представляют собой xml-документы. Описание элемента SqlXml представлено в схеме следующим образом:

<xsd:complexType name=»SqlXml» mixed=»true»>
<xsd:sequence>
<xsd:any/>
</xsd:sequence>
</xsd:complexType>

Элемент SqlXml может содержать любой элемент из любого пространства имен. В качестве примера возьмем тот же самый листинг 2, только с несколько измененным запросом: в конце добавим for xml auto. Вот результат:

<SqlXml>
<HumanResources.Employee EmployeeID=»10»
LoginID=»adventure-works\barryj» Gender=»M»/>
</SqlXml>

SqlMessage — все программные ошибки, не относящиеся к инфраструктуре конечных точек, возвращаются в данном элементе. Структура элемента довольно проста, поэтому ее описание здесь не приводится. Непрограммные ошибки описаны в следующем разделе.

Ошибка

В большинстве случаев Yukon не возвращает ошибки soap при наличии ошибок в запросах SQL, параметрах хранимых процедур и т.д. Soap-ошибки возвращаются только в следующих случаях.

  • Пакет SOAP сформирован неверно.
  • Возникли ошибки во время обработки запроса SOAP.
  • Для вызова Web-метода использовалась неверная учетная запись.
  • Другие ошибки, не относящиеся к обработке http-запросов и выполнению собственно команд T-SQL.

В случае подобного рода ошибок Yukon возвращает 500-й код ошибки http и элемент env:Fault в ответном SOAP-сообщении. Soap-ошибка возвращается в формате soap 1.1, однако более подробная информация об ошибке может быть получена через внутреннюю структуру в формате soap 1.2, которая находится в элементе detail.

форум sql server