SOAP сервис. Методы SOAP

Документ рассчитан на пользователя, обладающего уверенными навыками работы с компьютером и веб-интерфейсом, обладающего навыками работы c SOAP сервисом.

Описание использования SOAP сервиса

SOAP сервис предоставляет внешним системам возможность управлять данными в системе SMP:

  • Внешняя система отправляет в SMP запрос на доступ в систему и выполнение определенной операции.
  • SOAP сервис обрабатывает запрос и формирует ответ.

SOAP сервис реализован на WSDL-схеме. WSDL-схема доступна по ссылке:

{ссылка на стенд}/sd/soap/soapService.wsdl

Содержание запросов и ответов указывается в теге <SOAP-ENV:Body></SOAP-ENV:Body>.

Пример SOAP-запроса

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://naumen.ru/soap/server">
   <soapenv:Header/>
   <soapenv:Body>
     <ser:CreateRequest>
<ser:accessKey>2da56302-8020-4190-99be-ad2699826e88</ser:accessKey>
      <ser:attributes>
         <ser:entry>
           <ser:key>title</ser:key>
             <ser:value>
               <ser:string>Новый отдел</ser:string>
             </ser:value>
         </ser:entry>
      </ser:attributes>
      <ser:fqn>ou$ou</ser:fqn>
     </ser:CreateRequest>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns1:objectUUIDResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:uuid>ou$4001</ns1:uuid>
</ns1:objectUUIDResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP-запросы не выполняются с accessKey заблокированного пользователя.

Метод AddFile. Добавление файла к объекту

Описание метода рассматривается на примере добавления файла в карточку отдела.

Запрос на добавление файла

<ser:AddFileRequest>
<!--AccessKey сотрудника, под которым будет выполняться добавление файла-->
<ser:accessKey>0ee041f7-6f2d-448b-932c-eacddc82f8ae</ser:accessKey>
<!--Content в виде base64-->
<ser:content>bGZsZmxm</ser:content>
<!--MimeType файла-->
<ser:mimeType>application/vnd.oasis.opendocument.text</ser:mimeType>
<!--UUID объекта, к которому необходимо прикрепить файл-->
<ser:sourceUUID>ou$5501</ser:sourceUUID>
<!--Название файла с указанием расширения-->
<ser:title>odt2.odt</ser:title>
</ser:AddFileRequest>

Ответ (добавление файла)

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Файл добавлен</ns1:message>
</ns1:messageResponse>

Метод Create. Создание объекта

Описание метода рассматривается на примере создания отдела.

Запрос на создание отдела

<ser:CreateRequest>
<!--AccessKey сотрудника, под которым будет выполняться создание объекта-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--Атрибуты объекта, которые необходимо заполнить-->
<ser:attributes>
<!--Заполнение атрибута типа "Агрегирующий". Указание сотрудника и отдела-->
<ser:entry>
<ser:key>aggrCode</ser:key>
<ser:value>
<ser:aggregate>
<ser:ou>ou$5501</ser:ou>
<ser:team>?</ser:team>
<ser:employee>employee$5601</ser:employee>
</ser:aggregate>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Вещественное число"-->
<ser:entry>
<ser:key>doubleCode</ser:key>
<ser:value>
<ser:string>2014.10</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Временной интервал"-->
<ser:entry>
<ser:key>timeIntervalCode</ser:key>
<ser:value>
<ser:dateTimeInterval length="10" interval="HOUR"/>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Гиперссылка"-->
<ser:entry>
<ser:key>hyperlinkCode</ser:key>
<ser:value>
<ser:hyperlink text="Naumen" url="http://naumen.ru"/>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Дата/время"-->
<ser:entry>
<ser:key>dateTimeCode</ser:key>
<ser:value>
<ser:string>2014.10.12 14:00</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Дата"-->
<ser:entry>
<ser:key>dateCode</ser:key>
<ser:value>
<ser:string>2014.10.12</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа Набор элементов справочника-->
<ser:entry>
<ser:key>catItemsCode</ser:key>
<ser:value>
<ser:objects>
<ser:objectsStr>test21</ser:objectsStr>
<ser:objectsStr>test1</ser:objectsStr>
</ser:objects>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Обратная ссылка"-->
<ser:entry>
<ser:key>backLinksCode</ser:key>
<ser:value>
<ser:objects>
<!--Zero or more repetitions:-->
<ser:objectsStr>ou$10402</ser:objectsStr>
<ser:objectsStr>ou$10403</ser:objectsStr>
<ser:objectsStr>ou$10404</ser:objectsStr>
</ser:objects>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Ссылка на бизнес-объект"-->
<ser:entry>
<ser:key>objLinkCode</ser:key>
<ser:value>
<ser:string>slmService$2402</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Строка"-->
<ser:entry>
<ser:key>title</ser:key>
<ser:value>
<ser:string>Название отдела</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Текст"-->
<ser:entry>
<ser:key>textCode</ser:key>
<ser:value>
<ser:string>
Описание 
отдела
</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Текст в формате RTF"-->
<ser:entry>
<ser:key>rtfCode</ser:key>
<ser:value>
<!--Левая угловая скобка в тегах должна быть написана в виде: &lt;-->
<ser:string>&lt;b>&lt;i>&lt;u>Описание отдела&lt;/u>&lt;/i>&lt;/b></ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Целое число"-->
<ser:entry>
<ser:key>intCode</ser:key>
<ser:value>
<ser:string>2014</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Элемент справочника"-->
<ser:entry>
<ser:key>catItemCode</ser:key>
<ser:value>
<ser:string>rating$1805</ser:string>
</ser:value>
</ser:entry>
<!--Заполнение атрибута типа "Набор ссылок на БО"-->
<ser:entry>
<ser:key>linksCode</ser:key>
<ser:value>
<ser:objects>
<!--Zero or more repetitions:-->
<ser:objectsStr>ou$10501</ser:objectsStr>
<ser:objectsStr>ou$105502</ser:objectsStr>
<ser:objectsStr>ou$10503</ser:objectsStr>
</ser:objects>
</ser:value>
</ser:entry>
</ser:attributes>
<!--Тип создаваемого объекта-->
<ser:fqn>ou$intOU</ser:fqn>
</ser:CreateRequest>

Ответ (создание отдела)

<ns1:objectUUIDResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:uuid>ou$3641601</ns1:uuid>
</ns1:objectUUIDResponse>

Ответ (ошибка, нет прав на добавление объекта):

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>У Вас нет прав на Добавление объекта в типе OG_ou класса Отдел</ns1:message>
</ns1:messageResponse>

Метод Edit. Редактирование объекта

Описание метода рассматривается на примере редактирования атрибутов отдела.

Запрос на редактирование атрибутов отдела

<ser:EditRequest>
<!--AccessKey сотрудника, под которым будет выполняться редактирование объекта-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--Атрибуты, которые необходимо заполнить. Атрибуты заполняются по аналогии с методом Create-->
<ser:attributes>
<ser:entry>
<ser:key>title</ser:key>
<ser:value>
<ser:string>Новое название отдела</ser:string>
</ser:value>
</ser:entry>
</ser:attributes>
<!--UUID редактируемого объекта-->
<ser:uuid>ou$3641602</ser:uuid>
</ser:EditRequest>

Ответ (редактирование отдела)

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Объект отредактирован</ns1:message>
</ns1:messageResponse>

Метод Delete. Удаление объекта

Описание метода рассматривается на примере удаления отдела.

Запрос на удаление отдела

<ser:DeleteRequest>
<!--AccessKey сотрудника, под которым будет выполняться удаление объекта-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--UUID удаляемого объекта-->
<ser:uuid>ou$1602</ser:uuid>
</ser:DeleteRequest>

Ответ (удаление отдела)

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Объект удален</ns1:message>
</ns1:messageResponse>

Метод Find. Поиск объектов

Описание метода рассматривается на примере поиска отдела.

Запрос на поиск отдела

<ser:FindRequest>
<!--AccessKey сотрудника, под которым будет выполняться поиск объектов-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--Атрибуты, по которым будет производиться поиск. Атрибуты заполняются по аналогии с методом create-->
<ser:attributes>
<ser:entry>
<ser:key>parent</ser:key>
<ser:value>
<ser:string>ou$1765</ser:string>
</ser:value>
</ser:entry>
</ser:attributes>
<!--Полный код типа объектов, который ищется-->
<ser:fqn>ou$intOU</ser:fqn>
</ser:FindRequest>

Для поиска по атрибутам типа "Дата" и "Дата/время" можно указывать точное значение или определенный диапазон времени.

Пример заполнения значения атрибута типа "Дата/время" для поиска по точному значению:

<ser:value>
<ser:string>2014.10.12 14:00</ser:string>
</ser:value>

Пример заполнения значения атрибута типа "Дата/время" для поиска по интервалу времени:

<ser:value>
<ser:period>
<ser:periodStart>2017.12.22 11:25</ser:periodStart>
<ser:periodEnd>2017.12.22 14:37</ser:periodEnd>
</ser:period>
</ser:value>

Тэги <ser:periodStart> и <ser:periodEnd> являются необязательными.

Если не указан тег <ser:periodStart>, то в результаты поиска попадут все объекты, по дату, указанную в <ser:periodEnd>.

Если не указан тег <ser:periodEnd>, то в результаты поиска попадут все объекты, начиная с даты, указанной в <ser:periodStart>.

Если не указаны оба тега, то в результаты поиска попадут объекты, у которых дата не заполнена.

Ответ (поиск отдела)

<ns1:manyObjectsResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:objects>
<ns1:entry>
<ns1:key>title</ns1:key>
<ns1:value>
<ns1:string>Отдел технической поддержки</ns1:string>
</ns1:value>
</ns1:entry>
<ns1:entry>
<ns1:key>UUID</ns1:key>
<ns1:value>
<ns1:string>ou$5304</ns1:string>
</ns1:value>
</ns1:entry>
</ns1:objects>
<ns1:objects>
<ns1:entry>
<ns1:key>title</ns1:key>
<ns1:value>
<ns1:string>Сервисная служба</ns1:string>
</ns1:value>
</ns1:entry>
<ns1:entry>
<ns1:key>UUID</ns1:key>
<ns1:value>
<ns1:string>ou$6301</ns1:string>
</ns1:value>
</ns1:entry>
</ns1:objects>
</ns1:manyObjectsResponse>

Ответ (метакласс не существует):

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Метакласс не найден: fqn=ou$rt</ns1:message>
</ns1:messageResponse>

Ответ (access-key зарегистрирован на несуществующего пользователя):

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message xmlns:ns1="http://naumen.ru/soap/server">Not found</ns1:message>
</ns1:messageResponse>

Метод GetFile. Получение файлов, прикрепленных к объекту

Описание метода рассматривается на примерах получения файлов, прикрепленных к карточке отдела.

Все методы в запросах возвращают только те данные, которые описаны в примере, то есть работают аналогично.

Пример 1. Получение файлов, прикрепленных к карточке отдела

Запрос на получение списка UUID файлов, прикрепленных к отделу

<ser:GetFileRequest>
<!--AccessKey сотрудника, под которым будет выполняться действие-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--UUID отдела, список файлов которого необходимо получить-->
<ser:uuid>ou$5303</ser:uuid>
</ser:GetFileRequest>

Ответ (получение списка UUID файлов, прикрепленных к отделу):

<ns1:filesResponse xmlns:ns1="http://naumen.ru/soap/server>
<filesUUIDS>file$8007</filesUUIDS>
<filesUUIDS>file$8006</filesUUIDS>
<filesUUIDS>file$8005</filesUUIDS>
<filesUUIDS>file$8004</filesUUIDS>
<filesUUIDS>file$8003</filesUUIDS>
</ns1:filesResponse>

Пример 2. Получение файла по его UUID

Запрос на получение файла по его UUID:

<ser:GetFileRequest>
<!--AccessKey сотрудника, под которым будет выполняться действие-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--UUID получаемого файла-->
<ser:uuid>file$8007</ser:uuid>
</ser:GetFileRequest>

Ответ (получение файла по его UUID):

<ns1:filesResponse xmlns:ns1="http://naumen.ru/soap/server">
<file>
<ns1entry>
<!--Содержимое файла в формате base64-->
<ns2:key>content</ns2:key>
<ns2:value>
<ns1:string>0M8R4KGA…….</ns1:string>
</ns1:value>
</ns1:entry>
<ns1:entry>
<ns1:key>metaClass</ns1:key>
<ns1:value>
<ns1:string>file</ns1:string>
</ns1:value>
</ns1:entry>
<ns1:entry>
<ns1:key>title</ns1:key>
<ns1:value>
<ns1:string>letter.txt</ns1:string>
</ns1:value>
</ns1:entry>
<ns1:entry>
<ns1:key>UUID</ns1:key>
<ns1:value>
<ns1:string>file$8007</ns1:string>
</ns1:value>
</ns1:entry>
<ns1:entry>
<ns1:key>mimeType</ns1:key>
<ns1:value>
<ns1:string>text/plain</ns1:string>
</ns1:value>
</ns1:entry>
</file>
</ns1:filesResponse>

Ответ (объекта с указанным идентификатором не существует).

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Object not found [uuid=ou$860772, class=class ru.naumen.core.server.bo.ou.OU]</ns1:message>
</ns1:messageResponse>

Метод Get. Получение значений атрибутов объекта

Описание метода рассматривается на примере получения значений атрибутов отдела.

Запрос на получение значений атрибутов

<ser:GetRequest>
<!--AccessKey сотрудника, под которым будет выполняться действие-->
<ser:accessKey>64a2e6b2-5318-4ff1-8f40-9c7cf6314b92</ser:accessKey>
<!--UUID получаемого объекта-->
<ser:uuid>ou$7307</ser:uuid>
</ser:GetRequest>

Для файлов необходимо использовать Метод GetFile. Получение файлов, прикрепленных к объекту.

Ответ (получения значений атрибутов)

<ns2:objectResponse xmlns:ns2="http://naumen.ru/soap/server">
<ns2:attributes>
<ns2:entry>
<ns2:key>adDateTime</ns2:key>
<ns2:value>
<ns2:string>2013.10.14 10:26:00</ns2:string>
</ns2:value>
</ns2:entry>
</ns2:attributes>
</ns2:objectResponse>

Значение тега value зависит от типа атрибутов:

  • Агрегирующий:

    <ns2:value>
    <ns2:aggregate>
    <team>team$5801</team>
    <employee>employee$5601</employee>
    </ns2:aggregate>
    </ns2:value>
  • Вещественное число:

    <ns2:value>
    <ns2:string>1.0</ns2:string>
    </ns2:value>
  • Временной интервал:

    <ns2:value>
    <ns2:dateTimeInterval interval="MINUTE" length="10"/>
    </ns2:value>
  • Группы пользователей:

    <ns2:objects xsi:type="ns2:anyType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ns2:string>SecGroup [code=a15dd65f-7c48-410f-89dc-9d3fb0d5ebe7, title=Системная группа]</ns2:string>
    </ns2:objects>
  • Дата:

    <ns2:value>
    <ns2:string>2014.10.14 00:00:00</ns2:string>
    </ns2:value>
  • Дата/время:

    <ns2:value>
    <ns2:string>2014.10.14 10:03:54</ns2:string>
    </ns2:value>
  • Гиперссылка:

    <ns2:value>
    <ns2:hyperlink text="" url=""/>
    </ns2:value>
  • Лицензия:

    <ns2:value>
    <ns2:string>concurrent</ns2:string>
    </ns2:value>
  • Логический:

    <ns2:value>
    <ns2:string>false</ns2:string>
    </ns2:value>
  • Набор ссылок на бизнес-объекты:

    <ns2:value>
    <ns2:objects>
    <ns2:objects ns2:title="Отдел1" ns2:uuid="ou$10501"/>
    <ns2:objects ns2:title="Отдел2" ns2:uuid="ou$10502"/>
    <ns2:objects ns2:title="Отдел3" ns2:uuid="ou$10503"/>
    </ns2:objects>
    </ns2:value>
  • Набор элементов справочника:

    <ns2:value>
    <ns2:catalogItems>
    <ns2:items ns2:code="category1" ns2:title="category1" ns2:uuid="category$9905"/>
    <ns2:items ns2:code="category2" ns2:title="category2" ns2:uuid="category$9906"/>
    <ns2:items ns2:code="category3" ns2:title="category3" ns2:uuid="category$9903"/>
    </ns2:catalogItems>
    </ns2:value>
  • Обратная ссылка:

    <ns2:value>
    <ns2:objects ns2:title="Отдел1" ns2:uuid="ou$10402"/>
    <ns2:objects ns2:title="Отдел2" ns2:uuid="ou$10411"/>
    <ns2:objects ns2:title="Отдел3" ns2:uuid="ou$10412"/>
    </ns2:value>
  • Папка:

    <ns2:value>
    <ns2:catalogItems>
    <ns2:items ns2:code="e1" ns2:title="e1" ns2:uuid="folder$9503"/>
    </ns2:catalogItems>
    </ns2:value>
  • Ссылка на бизнес-объект:

    <ns2:value>
    <ns2:entity ns2:title="Департамент управления" ns2:uuid="ou$5501"/>
    </ns2:value>
  • Статус:

    <ns2:value>
    <ns2:string>registered</ns2:string>
    </ns2:value>
  • Строка:

    <ns2:value>
    <ns2:string>Сервисный отдел</ns2:string>
    </ns2:value>
  • Счетчик времени:

    <ns2:value>
    <ns2:string>Timer [status=ACTIVE, elapsed=139981]</ns2:string>
    </ns2:value>
  • Счетчик времени (обратный):

    <ns2:value>
    <ns2:string>BackTimerDto [getStatus()=ACTIVE, deadLineTime=Tue Oct 21 11:29:14 CEST 2014, allowance=518260018]</ns2:string>
    </ns2:value>
  • Текст:

    <ns2:value>
    <ns2:string>Описание задач отдела</ns2:string>
    </ns2:value>
  • Тест в формате RTF:

    <ns2:value>
    <ns2:string><b><font color="#ff0000" size="7">ИНСТРУКЦИЯ ПО ПОДКЛЮЧЕНИЮ</font></b></ns2:string>
    </ns2:value>
  • Тип объекта:

    <ns2:value>
    <ns2:string>ou$OUType</ns2:string>
    </ns2:value>
  • Элемент справочника:

    <ns2:value>
    <ns2:catalog-item ns2:code="Europe/Moscow" ns2:title="Msk" ns2:uuid="timezone$2101"/>
    </ns2:value>
  • Файл:

    <ns2:value>
    <ns2:objectsStr>
    <ns2:objectsStr>file$11716</ns2:objectsStr>
    </ns2:objectsStr>
    </ns2:value>
  • Целое число:

    <ns2:value>
    <ns2:string>7</ns2:string>
    </ns2:value>

Ответ (ошибка, объект с указанным идентификатором не существует)

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Object not found [uuid=ou$860002, class=class ru.naumen.core.server.bo.ou.OU]</ns1:message>
</ns1:messageResponse>

Метод CreateExcl. Добавление исключения в класс обслуживания

Запрос на добавление исключения в класс обслуживания

Если время начала и окончания периода исключения не указаны, исключение добавляется на весь день.

<ser:CreateExclRequest>
  <ser:accessKey>d18bd01e-c24f-4187-a110-c40915d75fb2</ser:accessKey>
  <ser:attributes>
    <ser:entry>
       <!--Дата исключения-->
       <ser:key>exclusionDate</ser:key>
       <ser:value>
          <ser:string>2011-11-25 00:00:00.0</ser:string>
       </ser:value>
    </ser:entry>
    <ser:entry>
       <!--Время начала периода исключения(мс с начала дня)-->
       <ser:key>startTime</ser:key>
       <ser:value>
          <ser:long>28800000</ser:long>
       </ser:value>
    </ser:entry>
    <ser:entry>
       <!--Время конца периода исключения (мс с начала дня)-->
       <ser:key>endTime</ser:key>
       <ser:value>
          <ser:long>54000000</ser:long>
       </ser:value>
    </ser:entry>
</ser:attributes>
<!--UUID класса обслуживания-->
<ser:uuid>servicetime$2204</ser:uuid>
</ser:CreateExclRequest>

Ответ (исключение добавлено, возвращается UUID исключения)

<ns1:objectUUIDResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:uuid>srvTimeExcl$11901</ns1:uuid>
</ns1:objectUUIDResponse>

Редактирование исключения в классе обслуживания

Запрос на изменение исключения в классе обслуживания

<ser:EditExclRequest>
<ser:accessKey>79729264-476c-4e2c-9a67-50ac3986e55b</ser:accessKey>
<ser:attributes>
   <ser:entry>
       <!--Время начала периода исключения(мс с начала дня)-->
       <ser:key>startTime</ser:key>
       <ser:value>
          <ser:long>28800000</ser:long>
       </ser:value>
   </ser:entry>
   <ser:entry>
       <!--Время конца периода исключения (мс с начала дня)-->
       <ser:key>endTime</ser:key>
       <ser:value>
          <ser:long>64000000</ser:long>
       </ser:value>
   </ser:entry>
</ser:attributes>
<!--UUID класса обслуживания-->
<ser:uuid>srvTimeExcl$11901</ser:uuid>
</ser:EditExclRequest>

Ответ (исключение изменено)

<ns1:messageResponse xmlns:ns1="http://naumen.ru/soap/server">
<ns1:message>Объект отредактирован</ns1:message>
</ns1:messageResponse>