Секция binding
Здесь описывается привязка конкретных операций (Web-методов) к конкретному протоколу и стилю вызова (для SOAP это может быть document- или RPC-стиль). Так как сам WSDL является абстрактным форматом, он не имеет средств для определения зависимых от протокола параметров, его синтаксис позволяет вставлять в определенные места фрагмента binding элементы расширения для конкретного протокола. Вот фрагмент секции binding, взятый из спецификации WSDL:
<wsdl:binding name="nmtoken" type="qname"> * <-- extensibility element (1) --> * <wsdl:operation name="nmtoken"> * <-- extensibility element (2) --> * <wsdl:input name="nmtoken"? > ? <-- extensibility element (3) --> </wsdl:input> <wsdl:output name="nmtoken"? > ? <-- extensibility element (4) --> * </wsdl:output> <wsdl:fault name="nmtoken"> * <-- extensibility element (5) --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> |
Как видите, элементы расширения могут появляться во всех частях связывания, определяя поведение всего связывания (1), конкретной операции (2), входных (3), выходных (4) и ошибочных (5) параметров.
Рассмотрим для примера элементы расширения для протокола SOAP.
<soap:binding style="rpc|document" transport="uri"> – элемент расширения связывания, который определяет стиль SOAP-сообщения и транспорт. Расширение является обязательным.
<soap:operation soapAction="uri"? style="rpc|document"?>? – элемент расширения операции, который определяет элемент заголовка soapAction и переопределяет стиль для конкретного сообщения. Необязательное расширение.
4. и 5. <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?> – элемент расширения параметров.
В нашем случае эта часть WSDL-файла будет выглядеть так:
<wsdl:binding name="SXSBinding" type="tns:SXSPort"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" /> </wsdl:binding> |
Здесь определяется стиль SOAP-сообщения document и транспорт http. Операции, как видите, отсутствуют.
Секция service
Эта последняя секция, которая определяет набор портов для связываний. Порт – это абстрактное понятие конечной точки, которое уточняется с помощью опять же элементов расширения. В случае SOAP элемент расширения задает адрес Web-сервиса. Вот как выглядит этот фрагмент в нашем случае:
<wsdl:service name="webserv"> <wsdl:port name="SXSPort" binding="tns:SXSBinding"> <soap:address location="http://dcit06/srv/webserv" /> </wsdl:port> </wsdl:service> |
Более подробную информацию о WSDL 1.1, элементах расширения, вложениях и проч. можно получить по адресу http://www.w3.org/TR/wsdl.
Создание Web-методов
Давайте попробуем создать Web-метод и обратиться к SQL Server через Web. Допустим, вы настроили Web-сервис на базу Northwind. На вкладке «Virtual Names» консоли «IIS Virtual Directory Management for SQLXML 3.0» выберите из списка webserv и нажмите кнопу «Configure». Появится диалоговое окно, изображенное на рисунке 2.
Рисунок
2. Создание Web-метода.
Более всего здесь интересен раздел «Output as», который позволяет настроить формат результирующего сообщения. Вне зависимости от этих настроек формат SOAP-конверта (soap envelope) будет таким:
<?xml version="1.0" encoding="utf-16"?> <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sqltypes="http://schemas.microsoft.com/SQLServer/2001/12/SOAP/types" xmlns:sqlmessage="http://schemas.microsoft.com/SQLServer/2001/12/SOAP/types/SqlMessage" xmlns:sqlresultstream="http://schemas.microsoft.com/SQLServer/2001/12/SOAP/types/SqlResultStream" xmlns:tns="uri Web-сервиса"> <SOAP-ENV:Body> <tns:ИмяМетодаResponse> <!-- Содержимое зависит от настроек (опции Output as) --> </tns:ИмяМетодаResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope> |
Далее описываются каждый из типов опции «Output as» и их влияние на содержимое SOAP-конверта.
XML objects
В случае указания этот параметра возвращаемый набор рекордсетов будет представлен элементами SqlXml. После набора элементов SqlXml будет идти один элемент SqlResultCode, который описывает возвращаемый хранимой процедурой код.
Оба этих элемента – дочерние элементы ИмяМетодаResult, который имеет тип SqlResultStream.
Если хранимая процедура возвращает не только recordset, но еще и некоторые параметры, то после элемента ИмяМетодаResult будет следовать набор элементов, содержащих значения возвращаемых параметров. Пример:
<tns:ИмяМетодаResult xsi:type="sqlresultstream:SqlResultStream"> <sqlresultstream:SqlXml>результирующий рекордсет</sqlresultstream:SqlXml>* <sqlresultstream:SqlResultCode xsi:type="sqltypes:SqlResultCode" sqltypes:IsNested="false">возвращаемый код</sqlresultstream:SqlResultCode> </tns:ИмяМетодаResult> <tns:ИмяВыходногоПараметра>значение</tns:ИмяВыходногоПараметра>* |
По идее, SQLXML должен еще возвращать элемент SqlMessage, если в процессе выполнения запроса произошла ошибка. Я тестировал на различных конфигурациях, но никогда мне не удавалось получить от него такого сообщения. Вместо него всегда возвращался документ следующего содержания:
<?xml version="1.0" encoding="utf-16"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring>Runtime errors.</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope> |
Dataset objects
С помощью этой опции можно настроить SQLXML так, чтобы результирующий конверт состоял из набора фрагментов в формате DiffGram, который является одним из «родных» форматов объекта DataSet из ADO.NET. Это наиболее предпочтительная опция, если клиент написан с использованием платформы .Net Framework. DiffGram-ы записываются в отдельные элементы SqlRowSet, которые являются дочерними элементу SqlResultStream. Кроме набора DiffGram, элемент SqlResultStream также содержит элемент SqlResultCode, представляющий возвращаемый код хранимой процедуры. После элемента SqlResultStream может идти неопределенное количество элементов выходных параметров. Например:
<tns:ИмяМетодаResult xsi:type="sqlresultstream:SqlResultStream"> <sqlresultstream:SqlRowSet>результирующий рекордсет в формате DiffGram</sqlresultstream:SqlRowSet>* <sqlresultstream:SqlResultCode xsi:type="sqltypes:SqlResultCode" sqltypes:IsNested="false">возвращаемый код</sqlresultstream:SqlResultCode> </tns:ИмяМетодаResult> <tns:ИмяВыходногоПараметра>значение</tns:ИмяВыходногоПараметра>* |
Single dataset
Эта опция с точки зрения пользователя мало чем отличается от предыдущей, если только вы не работаете с несколькими результирующими наборами. Как я уже сказал выше, в случае выбора опции DataSet Object несколько рекордсетов будут представлены соответствующим количеством фрагментов SqlRowSet. Значит, на клиенте вы будете работать с несколькими наборами отдельных объектов DataSet, что не очень удобно, учитывая, что DataSet может содержать множество таблиц. При указании параметра Single dataset SQLXML будет сохранять все рекордсеты в один DiffGram. При этом необходимость в элементе SqlRowSet отпадает. Пример:
<tns:ИмяМетодаResult xsi:type="sqlresultstream:SqlResultStream"> результирующий рекордсет в формате DiffGram <sqlresultstream:SqlResultCode xsi:type="sqltypes:SqlResultCode" sqltypes:IsNested="false">возвращаемый код</sqlresultstream:SqlResultCode> </tns:ИмяМетодаResult> <tns:ИмяВыходногоПараметра>значение</tns:ИмяВыходногоПараметра>* |
Web-методы
Теперь давайте, наконец, создадим несколько Web-методов для тестирования, которое будет описано в следующем разделе. Для начала нужно создать одну хранимую процедуру с output-параметром и одну функцию (ну, не нашлось в базе данных Northwind таковых). Вот скрипт их создания:
Хранимая процедура:
create proc test_output @i int out as set @i = 10 |
UDF:
create function test_ret_func() returns int as begin return 1010 end |
Теперь щелкните на кнопке с тремя точками (см. рисунок 2). Перед вами должно появится диалоговое окошко, изображенное на рисунке 3.
Рисунок
3. Хранимые процедуры и функции базы
данных Northwind.
Выберите из списка: CustOrderHist, test_output и test_ret_func.
После нажатия кнопки ОК, в доселе пустом WSDL-файле, в разделе types схемы http://dcit06/srv/webserv должно появиться следующее:
<xsd:element name="CustOrderHist"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" maxOccurs="1" name="CustomerID" type="xsd:string" nillable="true"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="CustOrderHistResponse"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="1" name="CustOrderHistResult" type="sqlresultstream:SqlResultStream"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="test_output"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" maxOccurs="1" name="i" type="xsd:int" nillable="true"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="test_outputResponse"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="1" name="test_outputResult" type="sqlresultstream:SqlResultStream"/> <xsd:element name="i" type="xsd:int" nillable="true"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="test_ret_func"> <xsd:complexType> <xsd:sequence/> </xsd:complexType> </xsd:element> <xsd:element name="test_ret_funcResponse"> <xsd:complexType> <xsd:sequence> <xsd:element name="returnValue" type="xsd:int" nillable="true"/> </xsd:sequence> </xsd:complexType> </xsd:element> |
Это описания используемых типов элементов, с помощью которых происходит формирование soap-конверта.
Описания параметров выбранных методов (CustOrderHist, test_output и test_ret_func) должны появиться в соответствующих секциях message wsdl-документа.
<wsdl:message name="CustOrderHistIn"> <wsdl:part name="parameters" element="tns:CustOrderHist"/> </wsdl:message> <wsdl:message name="CustOrderHistOut"> <wsdl:part name="parameters" element="tns:CustOrderHistResponse"/> </wsdl:message> <wsdl:message name="test_outputIn"> <wsdl:part name="parameters" element="tns:test_output"/> </wsdl:message> <wsdl:message name="test_outputOut"> <wsdl:part name="parameters" element="tns:test_outputResponse"/> </wsdl:message> <wsdl:message name="test_ret_funcIn"> <wsdl:part name="parameters" element="tns:test_ret_func"/> </wsdl:message> <wsdl:message name="test_ret_funcOut"> <wsdl:part name="parameters" element="tns:test_ret_funcResponse"/> </wsdl:message> |
И, наконец, сами методы появляются в секции portType.
<wsdl:portType name="SXSPort"> <wsdl:operation name="CustOrderHist"> <wsdl:input message="tns:CustOrderHistIn"/> <wsdl:output message="tns:CustOrderHistOut"/> </wsdl:operation> <wsdl:operation name="test_output"> <wsdl:input message="tns:test_outputIn"/> <wsdl:output message="tns:test_outputOut"/> </wsdl:operation> <wsdl:operation name="test_ret_func"> <wsdl:input message="tns:test_ret_funcIn"/> <wsdl:output message="tns:test_ret_funcOut"/> </wsdl:operation> </wsdl:portType> |
Как видите, SQLXML принял решение, что все операции будут идти по сценарию запрос/ответ, о чем свидетельствуют теги input/output каждой операции.
СОВЕТ Возможно, вас не устроят названия секций, которые выбирает SQLXML. SXS – это, скорее всего, акроним от SQL Server Xml Support. Вы вправе дать всем элементами WSDL-файла свои собственные названия. Это совершенно не повлияет на работоспособность Web-сервиса. Правда, после следующей настройки с помощью консоли, все имена будут исправлены на стандартные. |
Что ж, теперь все готово к тестированию.