SOAP-сервис. Методы SOAP
Документ рассчитан на пользователя, обладающего уверенными навыками работы с компьютером и веб-интерфейсом, обладающего навыками работы с SOAP-сервисом.
- Описание использования SOAP-сервиса
- Метод AddFile. Добавление файла к объекту
- Метод Create. Создание объекта
- Метод Edit. Редактирование объекта
- Метод Delete. Удаление объекта
- Метод Find. Поиск объектов
- Метод GetFile. Получение файлов, прикрепленных к объекту
- Метод Get. Получение значений атрибутов объекта
- Метод CreateExcl. Добавление исключения в класс обслуживания
- Редактирование исключения в классе обслуживания
Описание использования 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>accessKey.UUID</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>accessKey.UUID</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>accessKey.UUID</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>
<!--Левая угловая скобка в тегах должна быть написана в виде: <-->
<ser:string><b><i><u>Описание отдела</u></i></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>accessKey.UUID</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>accessKey.UUID</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>accessKey.UUID</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>accessKey.UUID</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>accessKey.UUID</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>accessKey.UUID</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 зависит от типа атрибутов:
-
Агрегирующий:
Copy<ns2:value>
<ns2:aggregate>
<team>team$5801</team>
<employee>employee$5601</employee>
</ns2:aggregate>
</ns2:value> -
Вещественное число:
Copy<ns2:value>
<ns2:string>1.0</ns2:string>
</ns2:value> -
Временной интервал:
Copy<ns2:value>
<ns2:dateTimeInterval interval="MINUTE" length="10"/>
</ns2:value> -
Группы пользователей:
Copy<ns2:objects xsi:type="ns2:anyType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:string>SecGroup [code=a15dd65f-77, title=Системная группа]</ns2:string>
</ns2:objects> -
Дата:
Copy<ns2:value>
<ns2:string>2014.10.14 00:00:00</ns2:string>
</ns2:value> -
Дата/время:
Copy<ns2:value>
<ns2:string>2014.10.14 10:03:54</ns2:string>
</ns2:value> -
Гиперссылка:
Copy<ns2:value>
<ns2:hyperlink text="" url=""/>
</ns2:value> -
Лицензия:
Copy<ns2:value>
<ns2:string>concurrent</ns2:string>
</ns2:value> -
Логический:
Copy<ns2:value>
<ns2:string>false</ns2:string>
</ns2:value> -
Набор ссылок на бизнес-объекты:
Copy<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> -
Набор элементов справочника:
Copy<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> -
Обратная ссылка:
Copy<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> -
Папка:
Copy<ns2:value>
<ns2:catalogItems>
<ns2:items ns2:code="e1" ns2:title="e1" ns2:uuid="folder$9503"/>
</ns2:catalogItems>
</ns2:value> -
Ссылка на бизнес-объект:
Copy<ns2:value>
<ns2:entity ns2:title="Департамент управления" ns2:uuid="ou$5501"/>
</ns2:value> -
Статус:
Copy<ns2:value>
<ns2:string>registered</ns2:string>
</ns2:value> -
Строка:
Copy<ns2:value>
<ns2:string>Сервисный отдел</ns2:string>
</ns2:value> -
Счетчик времени:
Copy<ns2:value>
<ns2:string>Timer [status=ACTIVE, elapsed=139981]</ns2:string>
</ns2:value> -
Счетчик времени (обратный):
Copy<ns2:value>
<ns2:string>BackTimerDto [getStatus()=ACTIVE, deadLineTime=Tue Oct 21 11:29:14 CEST 2014, allowance=518260018]</ns2:string>
</ns2:value> -
Текст:
Copy<ns2:value>
<ns2:string>Описание задач отдела</ns2:string>
</ns2:value> -
Тест в формате RTF:
Copy<ns2:value>
<ns2:string><b><font color="#ff0000" size="7">ИНСТРУКЦИЯ ПО ПОДКЛЮЧЕНИЮ</font></b></ns2:string>
</ns2:value> -
Тип объекта:
Copy<ns2:value>
<ns2:string>ou$OUType</ns2:string>
</ns2:value> -
Элемент справочника:
Copy<ns2:value>
<ns2:catalog-item ns2:code="Europe/Moscow" ns2:title="Msk" ns2:uuid="timezone$2101"/>
</ns2:value> -
Файл:
Copy<ns2:value>
<ns2:objectsStr>
<ns2:objectsStr>file$11716</ns2:objectsStr>
</ns2:objectsStr>
</ns2:value> -
Целое число:
Copy<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>accessKey.UUID</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>accessKey.UUID</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>