Веб-сервисы Showcase

Материал из Course Orchestra
Перейти к: навигация, поиск
Showcase

Создание решений на КУРС:Showcase

Описание

Showcase предоставляет возможность интеграции с внешними приложениями посредством веб-сервисов.

Имя веб-сервиса: ShowcaseExternalsService

Адрес конечной точки (endpoint): ${showcase_app}/forall/webservices

WSDL: ${showcase_app}/forall/webservices?wsdl

XSD: ${showcase_app}/forall/webservices?xsd=1

где ${showcase_app} - URL развернутого Showcase.


Веб-сервис реализован в SOA стиле - т.е. посредством обмена сообщениями.

Обмен данными идет по протоколу http.

namespace по умолчанию для веб-сервиса - http://showcase.curs.ru.

Поддержка веб-сервисов реализована с помощью компоненты JAX-WS.

Поддерживаются следующие стандарты веб-служб:

  • WS-I Basic Profile 1.2 and 2.0
  • WS-I Attachments Profile 1.0
  • WS-I Simple SOAP Binding Profile 1.0
  • WS-Addressing 1.0 - Core, SOAP Binding, WSDL Binding


Поддерживается 2 способа обмена - т.е. 2 типа входящих сообщений - с передачей данных в виде строки и в виде произвольного XML документа. В обоих случаях вызов веб-службы трансформируется в вызов Jython скрипта или хранимой процедуры. Это позволяет организовать обработку любых входных данных или просто запустить скрипт или процедуру на сервере.

Имя универсального сообщения для обработки строк - handle. Сообщение должно содержать 2 параметра:

  1. procName - имя процедуры, которую нужно выполнить. Этот параметр должен быть задан!. Значение обрабатывается в соответствии с принципом универсальных источников.
  2. request - строка, содержащая описание того, что нужно сделать. Если требуемое действие полностью определяется процедурой - передавайте пустую строку.

В ответ на handle клиент может получить одно из 2 сообщений:

  1. handleResponse - успешное выполнение запроса, возвращается строка с результатом
  2. ShowcaseExportException - исключение при выполнении запроса, в исключении возвращается текст ошибки.

Имя универсального сообщения для обработки XML - handleXML. Сообщение должно содержать 2 параметра:

  1. procName - передается в заголовке (header)! Содержит имя процедуры, которую нужно выполнить. Должен быть задан!. Значение обрабатывается в соответствии с принципом универсальных источников.
  2. requestAnyXML - XML документ, содержащий описание того, что нужно сделать. Корневым тегом входящего документа обязательно должен быть тэг requestAnyXML с нашим namespace! Обращаем внимание - корневым тегом не может быть handleXML, т.к. мы используем non wrapped (bare) способ передачи данных, при котором тэг с именем сообщения опускается. Если требуемое действие полностью определяется процедурой - можно не передавать ничего.

В ответ на handle клиент может получить одно из 2 сообщений:

  1. handleXMLResponse - успешное выполнение запроса, возвращается документ с результатом. Корневым тегом возвращаемого Showcase-документа обязательно должен быть тэг responseAnyXML без namespace!
  2. ShowcaseExportException - исключение при выполнении запроса, в исключении возвращается текст ошибки.

Ниже приведены примеры входящих и исходящих сообщений.

Входящее сообщение для текста:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:show="http://showcase.curs.ru">
   <soapenv:Header/>
   <soapenv:Body>
      <show:handle>         
         <!--Optional:-->
         <request></request>
         <procName>ws/GetFile.py</procName>
      </show:handle>
   </soapenv:Body>
</soapenv:Envelope>

Исходящее сообщение для текста:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:handleResponse xmlns:ns2="http://showcase.curs.ru">
         <response><![CDATA[]]></response>
      </ns2:handleResponse>
   </S:Body>
</S:Envelope>

Входящее сообщение для XML:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:show="http://showcase.curs.ru">
   <soapenv:Header>
      <show:procName>ws/GetFile.py</show:procName>
   </soapenv:Header>
   <soapenv:Body>
      <show:requestAnyXML>
         <command type="getDP" param="b.xml">
            <context param="?"/>
         </command>
      </show:requestAnyXML>
   </soapenv:Body>
</soapenv:Envelope>

Исходящее сообщение для XML:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:responseAnyXML xmlns:ns2="http://showcase.curs.ru">
      </ns2:responseAnyXML>
   </S:Body>
</S:Envelope>

Техническую информацию о формате обмена можно получить из WSDL (см. выше адрес).

Обращаем внимание на следующие ограничения:

  1. WSDL не содержит описания того, что делает данный сервис. Он содержит всю информацию, необходимую для обмена данными. Не больше, не меньше.
  2. веб-служба развернута поверх Showcase и поэтому для их работы требуется запуск Showcase
  3. веб-служба не требует авторизации (она находится в разделе forall)
  4. веб-служба работает только с default userdata - т.е. скрипты Jython для веб-сервисов должны лежать в default userdata
  5. на данный момент веб-служба не экспонирует схемы принимаемых и передаваемых XML документов, а также не осуществляет проверку документов на соответствие какой-либо схеме.

Создание клиента

"Болванку" для клиента на Java можно быстро создать с помощью команды:

wsimport -Xnocompile ${showcase_app}/forall/webservices?wsdl

wsimport находится в каталоге bin JDK, который должен быть в Windows PATH. Обращаем внимание: в код клиента Java зашит адрес сервера, поэтому при смене адреса клиента его нужно сгенерировать повторно.

Для написания кода для клиента на Python рекомендуется использовать библиотеку [[1]]. Она включена в дистрибутив Jython, поставляемый с Showcase.

Вот пример работы с suds:

from suds.client import Client


def mainproc():
    request = '''<command type="getDP" param="b.xml"/>'''
    url = 'http://localhost/Showcase/forall/webservices?wsdl'
    client = Client(url)
    print client
    print client.service.handle(request = request, procName = "ws/GetFile.py")

Если нужен клиент на другом языке, ищите библиотеку для работы с веб-сервисами для своего языка.

Для тестирования веб-служб рекомендуется использовать утилиту SoapUI [[2]]. (ее бесплатную версию).

Формат хранимой процедуры для использования в Web Service

CREATE PROCEDURE [dbo].[asmToAnyInd]
     
           @inputData nvarchar(max), 
           @outputData nvarchar(max) out,
           @errMes nvarchar(max) out
               
AS
BEGIN
set nocount on 
set @outputData = '<responseAnylang="xml"><anlug>434www</anlug></responseAnylang="xml">'
set @errMes = 'fdffd'
END

Пример Celesta-скрипта для работы с вебсервисами

# coding: utf-8

def testFunction(context, xmlIn):
    xmlOut = xmlIn
    print xmlOut 
    #
    #Здесь может быть остальной код
    #
    return xmlOut

Здесь в параметр xmlIn функции testFunction приходит входное xml-сообщение из вебсервиса. А выходное значение xmlOut функции testFunction служит выходным xml-сообщением для вебсервиса. В параметр context приходит celesta-контекст, созданный от пользователя с sid-ом userCelestaSid. Таким образом для корректной работы функции-обработчика вебсервиса необходимо наличие в системе пользователя с sid-ом userCelestaSid. Также у этого пользователя должны быть необходимые разрешения для работы с таблицами.