Методы REST API
В разделе приводится описание методов REST API для SMP.
Методы REST API
- add-file. Добавление файла к объекту
- check-status. Проверка доступности приложения
- create. Создание объекта
- create-excl. Создание исключения в указанном классе обслуживания
- create-m2m. Создание объекта для машинного взаимодействия
- createMultiple. Создание множества объектов для машинного взаимодействия
- delete. Удаление объекта
- edit. Редактирование объекта
- edit-excl. Редактирование периода исключения для заданного исключения класса обслуживания
- edit-m2m. Редактирование (для машинного взаимодействия)
- get. Получение информации об объекте
- get-file. Получение контента файла по его UUID
- find. Поиск
- search. Быстрый поиск
- search. Расширенный поиск
Символы "%2e", "%2E, ";", "%3b", "%3B", "%2f", "%2F", "\\", "%5c", "%5C" запрещены для передачи в URI запроса, так как использование этих символов не соответствует требованиям безопасности.
Использование accessKey суперпользователя не рекомендуется из-за соображений безопасности. У пользователя, чей accessKey будет использоваться в REST запросах, должны быть права на действия с объектом (создание, редактирование, просмотр).
Не рекомендуется отправлять пользователю в оповещении ссылку с accessKey другого сотрудника. Ссылка в оповещении либо не содержит ключ, чтобы пользователь мог сам авторизоваться в системе, особенно если настроена сквозная авторизация, либо ключ должен быть одноразовый или с коротким сроком жизни и выписанный для текущего пользователя.
add-file. Добавление файла к объекту
|
Адрес: "/add-file/{uuid}" где:
|
| Метод вызова: POST |
|
Метод возвращает:
|
|
Пример 1: Прикрепление файла с использованием curl к SMP. При использовании curl файл должен находиться на ПК/сервере, из которого запрос выполняется. Файл будет преобразован в массив байт и отправлен внутри REST-запроса. В примере файл находится в директории, из которой осуществляется вызов команды и имеет название index.html curl -F "content=@index.html" http://192.168.225.145:8888/sd/services/rest/add-file/serviceCall$1992?accessKey=bccc11d3-f241-4bed-998e-1e4b3fbf3fe0 curl -F "content=@index.html" http://192.168.225.145:8888/sd/services/rest/add-file/serviceCall$1992?accessKey=bccc11d3-f241-4bed-998e-1e4b3fbf3fe0&attrCode=fileAttr |
|
Пример 2: Прикрепление файла из одного приложения SMP к другому приложению SMP. Copy
|
check-status. Проверка доступности приложения
|
Адрес: "/check-status" |
| Метод вызова: GET |
|
Метод возвращает:
|
|
Пример: http://localhost:8888/sd/services/rest/check-status |
|
Адрес: "/create/{fqn}" или "/create/{fqn}/{attributes}" где:
Форматы передачи атрибутов и их значений описаны в разделе. Метод также можно использовать для добавления комментария к объекту (аналогично utils.create), при этом:
|
|
Методы вызова: POST, GET. Рекомендуется использовать POST во избежание проблем с лимитами на стороне веб-сервера |
|
Метод возвращает:
|
create-excl. Создание исключения в указанном классе обслуживания
|
Адрес: "/create-excl/{uuid}/{attributes}" где:
|
| Метод вызова: GET |
|
Метод возвращает:
|
|
Пример. Переход по ссылке: http://192.168.112.46:8080/sd/services/rest/create-excl/servicetime$2204/{"endTime":54000000,"startTime":28800000,"exclusionDate":"2010-10-04"}?accessKey=470f7276-c183-4d19-bc6f-8b769dbf42fe& Полученный результат: {"UUID":"srvTimeExcl$10502","endTime":54000000,"startTime":28800000,"exclusionDate":"2010-10-04"} |
create-m2m. Создание объекта для машинного взаимодействия
|
Адрес: "/create-m2m/{fqn}/{attributes}" где:
Форматы передачи атрибутов и их значений описаны в разделе. |
|
Параметры метода:
|
| Метод вызова: POST |
|
Метод возвращает:
Возможные ответы сервера, если объект не был создан:
|
|
Примеры:
|
createMultiple. Создание множества объектов для машинного взаимодействия
|
Адрес: "/create-m2m-multiple/[{attributes}, ..., {attributes}]" где:
|
|
Параметр метода:
|
| Метод вызова: POST/GET |
|
Метод возвращает:
|
|
Примеры:
Ответы сервера:
|
|
Адрес: "/delete/{uuid}" где:
|
|
Метод возвращает:
|
|
Адрес: "/edit/{uuid}" или "/edit/{uuid}/{attributes}" где:
Форматы передачи атрибутов и их значений описаны в разделе. Если при редактировании объекта (например, при смене статуса) обязательно добавление комментария, то среди изменяемых атрибутов {attributes} необходимо указать параметр @comment и в качестве его значения передать текст комментария (аналогично utils.edit). Не рекомендуется использовать метод только для добавления комментария, т.к. он вызывает выполнение действия по событию на изменение объекта. Корректным способом добавления комментария является метод create. |
|
Метод вызова: POST, GET. Рекомендуется использовать POST во избежание проблем с лимитами на стороне веб-сервера |
|
Метод возвращает:
|
edit-excl. Редактирование периода исключения для заданного исключения класса обслуживания
|
Адрес: "/edit-excl/{uuid}/{attributes}" где:
|
|
Метод возвращает:
|
|
Пример: Переход по ссылке: http://192.168.112.46:8080/sd/services/rest/edit-excl/srvTimeExcl$10502/{"endTime":54000000,"startTime":28800000}?accessKey=470f7276-c183-4d19-bc6f-8b769dbf42fe& Полученный результат: {"UUID":"srvTimeExcl$10502","endTime":54000000,"startTime":28800000,"exclusionDate":"2010-10-04"} |
edit-m2m. Редактирование (для машинного взаимодействия)
|
Адрес: "/edit-m2m/{uuid}/{attributes}" где:
Форматы передачи атрибутов и их значений описаны в разделе. |
| Метод вызова: POST |
|
Параметры метода:
|
|
Метод возвращает:
|
|
Примеры:
|
get. Получение информации об объекте
|
Адрес: "/get/{uuid}" где:
|
|
Параметры метода:
|
| Метод вызова: GET |
|
Примеры:
|
Использование GET запросов с фигурными скобками и точками с запятыми не соответствует требованиям безопасности. Необходимо отказаться от таких HTTP GET запросов, поменяв их на POST запросы.
get-file. Получение контента файла по его UUID
|
Адрес: "/get-file/{uuid}" где:
|
| Метод вызова: GET |
|
Пример: http://localhost:8888/sd/services/rest/get-file/file$123?accessKey=e2469fa1-123c-492d-ada3-42f8be19afa8 |
Метод find нельзя использовать для поиска файлов. Для скачивания файлов можно воспользоваться методом get-file-by-func, для получения информации о файлах — методом exec.
|
Адрес: "/find/{fqn}" или "/find/{fqn}/{attributes}" где:
Форматы передачи атрибутов и их значений описаны в разделе. |
|
Методы вызова: POST, GET. Рекомендуется использовать POST во избежание проблем с лимитами на стороне веб-сервера |
|
Параметры метода:
|
|
Метод возвращает:
У найденных объектов отображаются только те атрибуты, на просмотр которых есть права у пользователя, указанного в accessKey. Лимит числа возвращаемых объектов настраивается в конфигурационном файле dbaccess.properties. |
|
Примеры ссылок для поиска по различным параметрам:
Примеры ссылок, сгенерированных с помощью утилит api.rest:
Пример рукописных ссылок (соблюдать последовательность параметров offset, limit, attrs, accessKey, после запроса (то, что после ?) не обязательно, главное они должны разделяться символом &):
|
| Адрес: "/search" |
| Метод вызова: GET |
|
Параметры метода:
|
|
Описание: Чтобы метод работал, необходимо настроить быстрый поиск по используемым в методе атрибутам, см. Настройка поиска по атрибутам объектов определенного класса/типа и проиндексировать, см. Переиндексация. |
|
Примеры: http://192.168.240.92:10080/sd/services/rest/search?term=Asura&accessKey=9baec4d6-ad92-4645-b032-3e671772804c http://192.168.240.92:10080/sd/services/rest/search?term=Asura&mode=active&accessKey=9baec4d6-ad92-4645-b032-3e671772804c http://192.168.240.92:10080/sd/services/rest/search?term=Asura&mode=active&limit=20&accessKey=9baec4d6-ad92-4645-b032-3e671772804c http://192.168.240.92:10080/sd/services/rest/search?term=Service%20call&mode=active&limit=20 http://192.168.240.92:10080/sd/services/rest/search?term=%D0%91%D1%83%D1%85%D0%B3%D0%B0%D0%BB%D1%82%D0%B5%D1%80%D0%B8%D1%8F&accessKey=9baec4d6-ad92-4645-b032-3e671772804c |
|
Адрес: "/search/{fqn}/{attributes}" где:
|
| Метод вызова: GET |
|
Параметры метода:
|
|
Описание: Чтобы метод работал, необходимо настроить расширенный поиск по используемым в методе атрибутам, см. Настройка поиска по атрибутам объектов определенного класса/типа и проиндексировать, см. Переиндексация. |
|
Пример: http://192.168.240.92:10080/sd/services/rest/search/music$Artists/{%22title%22:%22Asura%22}?accessKey=9baec4d6-ad92-4645-b032-3e671772804c http://192.168.240.92:10080/sd/services/rest/search/serviceCall$Task/{%22title%22:%22%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B0%22}?accessKey=9baec4d6-ad92-4645-b032-3e671772804c http://192.168.240.92:10080/sd/services/rest/search/serviceCall$Task/%7B%22title%22%3A%22Task%22%2C%22description%22%3A%22This%20task%20is%22%7D?accessKey=9baec4d6-ad92-4645-b032-3e671772804c http://192.168.240.92:10080/sd/services/rest/search/serviceCall$Task/{%22title%22:%22%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B0%22}?mode=removed http://192.168.240.92:10080/sd/services/rest/search/serviceCall$Task/{%22title%22:%22%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B0%22}?limit=20 |
Методы REST API, вызываемые через модуль
- exec-post. Выполнение скрипта через POST запрос
- exec. Выполнение скрипта через запрос GET
- execM2H. Выполнение скрипта через GET с предварительным вводом логина и пароля
- get-file-by-func. Скачивание файла с помощью вызова метода из модуля
- createWithRedirect. Создание объекта с переадресацией
- editWithRedirect. Редактирование объекта с переадресацией
- deleteWithRedirect. Удаление объекта с переадресацией
Скрипт оформляется в модуль, скриптовый модуль загружается в систему.
exec-post. Выполнение скрипта через POST запрос
| Адрес: "/exec-post" |
|
Параметры метода:
|
| Метод вызова: POST |
|
Пример. Вызов метода "someMethod" модуля "restModule" с параметрами "Какой-то текст", 10 и "Some data", и ключом доступа: http://localhost:8888/sd/services/rest/exec-post?accessKey=db1ba6f4-c440-437d-b4ce-e965cf4516d7&func=modules.restModule.someMethod¶ms=%22%D0%9A%D0%B0%D0%BA%D0%BE%D0%B9-%D1%82%D0%BE%20%D1%82%D0%B5%D0%BA%D1%81%D1%82%22,10,%22Some%20data%22 |
|
Общие особенности метода
Copy
|
|
Допустимые символы для передачи в параметрах метода (params) До версии 4.15.5 есть ограничение на символы, допустимые для использования в параметре params. Они определяются регулярным выражением: [а-яА-ЯееA-Za-z0-9,\[\]$'\"_\s\*\-%@&\\]* Чтобы отправить символы, не являющиеся допустимыми, в рамках определенного выше регулярного выражения, необходимо выразить их через допустимые одним из способов:
С версии 4.15.5 нет ограничения на использование символов в параметре params. С версии 4.15.5 не рекомендуется передача массивов и объектов (а также других конструкций, для передачи которых необходимо использование запятой внутри самой конструкции). Если необходима передача подобных значений, то следует оборачивать весь параметр в кавычки. В таком случае в скрипт параметр будет передан в виде строки. http://localhost:8888/services/rest/exec-post?accessKey=4be017dc-fba6-4ada-b00a-9a3f3dc0e10afunc=modules.restModule.someMethod¶ms="[1,'abc',2]",2,3,"[1,['ab','bc']]" |
|
Передача данных в формате form-data (метод поддерживает получение данных в формате form-data). Пример скрипта, который прикрепляет файлы к объектам, используя указанное описание Copy
|
|
Получение дополнительной информации о запросе в параметрах метода (params)
|
|
Подробнее о параметре raw
|
|
Подробнее о параметре response Возвращаемый тип ответа У response можно установить ContentType с помощью метода setContentType(String contentType), где строка contentType может принимать одно из общепринятых значений MIME-типов. В итоге результат выполнения API-метода будет с проставленным content-type. Пример модуля Copy
Результат выполнение такого модуля будет с content-type: text/html;charset=UTF-8 Copy
Этот же модуль без setContentType Copy
Результат выполнение такого модуля будет с content-type: application/json;charset=UTF-8 Copy
|
|
Доступные методы в response
|
exec. Выполнение скрипта через запрос GET
В случае если отправка файла со скриптом в POST запросе невозможна, то скрипт можно оформить в модуль. После загрузки модуля в приложение GET запрос выполняется через функции, определенные в модуле.
| Адрес: "/exec" |
| Метод вызова: GET |
|
Параметры метода:
|
|
Пример вызова метода: Вызов метода "someMethod" модуля "restModule" с параметрами "Какой-то текст", 10 и "Some data", и ключом доступа: http://localhost:8888/sd/services/rest/exec?accessKey=db1ba6f4-c440-437d-b4ce-e965cf4516d7&func=modules.restModule.someMethod¶ms=%22%D0%9A%D0%B0%D0%BA%D0%BE%D0%B9-%D1%82%D0%BE%20%D1%82%D0%B5%D0%BA%D1%81%D1%82%22,10,%22Some%20data%22 |
|
Особенности работы метода
Метода также касаются разделы Допустимые символы для передачи в параметрах метода (params), Получение дополнительной информации о запросе в параметрах метода (params) и Подробнее о параметре response из описания метода exec-post |
execM2H. Выполнение скрипта через GET с предварительным вводом логина и пароля
| Адрес: "/execM2H" |
| Метод вызова: GET |
|
Параметры метода:
|
|
Пример. Вызов метода "someMethod" модуля "restModule" с параметрами "Какой-то текст", 10 и "Some data": http://localhost:8888/sd/services/rest/execM2H?func=modules.restModule.someMethod¶ms=%22%D0%9A%D0%B0%D0%BA%D0%BE%D0%B9-%D1%82%D0%BE%20%D1%82%D0%B5%D0%BA%D1%81%D1%82%22,10,%22Some%20data%22 |
|
Особенности работы метода:
Метода также касаются разделы Допустимые символы для передачи в параметрах метода (params), Получение дополнительной информации о запросе в параметрах метода (params) и Подробнее о параметре response из описания метода exec-post |
get-file-by-func. Скачивание файла с помощью вызова метода из модуля
|
Адрес: "/get-file-by-func=modules.<код модуля>.<имя метода>¶ms=" " |
|
Описание: Метод из модуля возвращает uuid файла в системе. После func= указывается ключевое слово modules, через точку код модуля, через точку название метода и ¶ms=. Если параметров нет, то больше ничего не указывается. Если параметры есть, то они указываются далее через запятую без пробелов. |
|
Проверка прав при выполнении метода включается в конфигурационном файле системы dbaccess.properties Если проверка включена, то вызов метода выполняется с правами:
Если нет авторизации и не передан accessKey, то метод возвращает ошибку |
|
Пример ссылки: http://localhost:8888/services/rest/get-file-by-func?accessKey=e2469fa1-123c-492d-ada3-42f8be19afa8&func=modules.m2.getFileUuid¶ms=123,qwerty Пример модуля: Copy
|
createWithRedirect. Создание объекта с переадресацией
Описание метода createWithRedirect
editWithRedirect. Редактирование объекта с переадресацией
Описание метода editWithRedirect
deleteWithRedirect. Удаление объекта с переадресацией
Описание метода deleteWithRedirect
Параметр response
response — ответ на запрос javax.servlet.http.HttpServletResponse (позволяет выполнить редирект или проставить заголовки).
В методе модуля response передается в параметре:
http://localhost:8080/sd/services/rest/exec-post?accessKey=b8f7a2e3-e8b9-41bd-97ec-d0a91158792b&func=modules.someModule.test¶ms=request,response
В сигнатуре метода аналогично указывается
def test (def request, def response)
{
...
}
У response можно установить ContentType с помощью метода setContentType(String contentType), где строка contentType может принимать одно из общепринятых значений MIME-типов. В итоге результат выполнения API-метода будет с проставленным content-type.
Пример модуля:
http://localhost:8080/sd/services/rest/exec-post?accessKey=41cf3619-aa04-4b68-ba5b-08dacdec3669&func=modules.someModule.test¶ms=request,response
def getHtml(def request, def response)
{
response.setContentType('text/html; charset=UTF-8')
return '<HTML><HEAD><TITLE>Test</TITLE></HEAD></HTML>'
}Результат выполнение такого модуля будет с content-type: text/html;charset=UTF-8:
Headers:
cache-control → no-cache, no-store, max-age=0, must-revalidate
connection → keep-alive
content-type → text/html;charset=UTF-8
...
responseurl → /sd/services/rest/exec-post?accessKey=41cf3619-aa04-4b68-ba5b-08dacdec3669&func=modules.test.getHtml¶ms=request,response
Body:
<HTML>
<HEAD>
<TITLE>Test</TITLE>
</HEAD>
</HTML>Этот же модуль без setContentType:
http://localhost:8080/sd/services/rest/exec-post?accessKey=41cf3619-aa04-4b68-ba5b-08dacdec3669&func=modules.someModule.test¶ms=request,response
def getHtml(def request, def response)
{
return '<HTML><HEAD><TITLE>Test</TITLE></HEAD></HTML>'
}Результат выполнение такого модуля будет с content-type: application/json;charset=UTF-8:
Headers:
cache-control → no-cache, no-store, max-age=0, must-revalidate
connection → keep-alive
content-type → application/json;charset=UTF-8
...
responseurl → /sd/services/rest/exec-post?accessKey=41cf3619-aa04-4b68-ba5b-08dacdec3669&func=modules.test.getHtml¶ms=request,response
Body:
Unexpected '<'addDateHeader(name, date)
| Описание: Добавляет заголовок ответа с указанным именем и датой-значением. |
|
Параметры:
|
|
Возвращаемое значение: void |
|
Пример: Copy
|
addHeader(name, value)
| Описание: Добавляет заголовок ответа с указанным именем и значением. |
|
Параметры:
|
| Возвращаемое значение: void |
|
Пример: Copy
|
addIntHeader(name, value)
| Описание: Добавляет заголовок ответа с указанным именем и целочисленным значением. |
|
Параметры:
|
| Возвращаемое значение: void |
|
Пример: Copy
|
containsHeader(name)
|
Описание: Возвращает логическое значение, указывающее, был ли заданный заголовок ответа уже установлен. |
|
Параметр:
|
|
Возвращаемое значение:
|
|
Пример: Copy
|
getHeader(name)
|
Описание: Получает значение заголовка ответа с заданным именем. |
|
Параметр:
|
|
Возвращаемое значение:
|
|
Пример: Copy
|
getHeaderNames()
|
Описание: Получает имена заголовков этого ответа |
| Возвращаемое значение: java.util.Collection<java.lang.String> — коллекция (возможно пустая) названий заголовков, содержащихся в response |
|
Пример: Copy
|
getHeaders(name)
|
Описание: Получает значение заголовка ответа с заданным именем. |
|
Параметр:
|
| Возвращаемое значение: java.util.Collection<java.lang.String> — коллекция (возможно пустая) значений заголовков, с переданным именем. |
|
Пример: Copy
|
getStatus()
|
Описание: Получает текущий код состояния этого ответа. |
| Возвращаемое значение: int — текущий код статуса response. |
|
Пример: Copy
|
sendError(sc)
|
Описание: Отправляет клиенту ответ об ошибке, используя указанный код состояния, и очищает буфер. |
|
Параметр:
|
| Возвращаемое значение: void |
|
Особенности работы метода: throws: IOException – если произошла ошибка ввода/вывода. IllegalStateException – если response был отправлен (commited в документации HttpServletResponse) до того, как вызван этот метод. |
|
Пример: Copy
|
sendError(sc, msg)
|
Описание: Отправляет клиенту ответ об ошибке, используя указанный статус, и очищает буфер. |
|
Параметры:
|
| Возвращаемое значение: void |
|
Особенности работы метода: throws: IOException – если произошла ошибка ввода/вывода. IllegalStateException – если response был отправлен (commited в документации HttpServletResponse) до того, как вызван этот метод. |
|
Пример: Copy
|
sendRedirect(location)
|
Описание: Отправляет временный ответ перенаправления клиенту, используя указанный URL-адрес местоположения перенаправления, и очищает буфер. |
|
Параметр:
|
| Возвращаемое значение: void |
|
Особенности работы метода: throws: IOException – если произошла ошибка ввода/вывода. IllegalStateException – если response был отправлен (commited в документации HttpServletResponse) до того, как вызван этот метод ИЛИ если URL была передана в неверном формате |
|
Пример: Copy
|
setDateHeader(name, date)
|
Описание: Устанавливает заголовок ответа с указанным именем и датой-значением. |
|
Параметры:
|
| Возвращаемое значение: void |
|
Пример: Copy
|
setHeader(name, value)
|
Описание: Устанавливает заголовок ответа с указанным именем и значением. |
|
Параметры:
|
| Возвращаемое значение: void |
|
Пример: Copy
|
setIntHeader(name, value)
|
Описание: Устанавливает заголовок ответа с заданным именем и целочисленным значением. |
|
Параметры:
|
| Возвращаемое значение: void |
|
Пример: Copy
|
setStatus(sc)
|
Описание: Устанавливает код состояния для этого ответа. |
|
Параметр:
|
| Возвращаемое значение: void |
|
Пример: Copy
|
