Как вызвать конфигурационный сервис с помощью Postman
Glossary Item Box
Общие сведения
Для интеграции с конфигурационными сервисами bpm'online необходимо выполнять HTTP-запросы к этим сервисам. Запросы можно формировать с помощью любого языка программирования, например, C#, PHP и т. п. Но для понимания принципов формирования запросов удобно использовать такие инструменты редактирования и отладки HTTP-запросов, как Postman или Fiddler. В этой статье приведены примеры запросов к конфигурационным сервисам bpm'online с помощью Postman.
К СВЕДЕНИЮ
Пример выполнения запросов к сервису bpm'online с помощью Fiddler описан в статье "Выполнение запросов по протоколу OData с помощью Fiddler".
Предварительные настройки
В этой статье используется пользовательский конфигурационный сервис, созданный по примеру, приведенному в статье "Как создать свой конфигурационный сервис". Для установки конфигурационного сервиса в свое приложение воспользуйтесь пакетом, доступным по ссылке. Установка пакета описывается в статье "Установка приложений marketplace из *.zip-архива".
Аутентификация
Прежде чем выполнять запросы к конфигурационному сервису, необходимо выполнить аутентификацию и получить соответствующие cookies. Для аутентификации в bpm'online предназначен отдельный сервис AuthService.svc (см. "Сервис аутентификации AuthService.svc").
К СВЕДЕНИЮ
Для доступа к анонимным сервисам аутентфикация не требуется.
Для выполнения запроса к сервису AuthService.svc с помощью Postman выполните следующие действия (рис. 1):
Рис. 1. — Запрос к сервису аутентификации
1. Выберите HTTP-метод POST.
2. Укажите URL сервиса аутентификации. URL формируется по следующей маске:
http(s)://[Адрес приложения bpm'online]/ServiceModel/AuthService.svc/Login
Например:
https://009189-studio.bpmonline.com/ServiceModel/AuthService.svc/Login
3. На вкладке [Body] выберите способ формирования содержимого тела запроса "raw".
4. Укажите тип содержимого тела запроса (JSON (application/json)).
5. Добавьте тело запроса — JSON-объект, содержащий аутентификационные данные (логин и пароль):
{"UserName": "User01", "UserPassword":"User01"}
6. Нажмите кнопку [Send] для отправки запроса к сервису.
ВАЖНО
Полученные в HTTP-ответе cookie (BPMLOADER, .ASPXAUTH, BPMCSRF и UserName) необходимо использовать в дальнейших запросах к сервисам bpm'online, требующих аутентификационных данных. Полученные cookie можно просмотреть на вкладке [Cookies] (рис. 1, 7).
При включенной защите от CSRF-атак использование cookie BPMCSRF и токена BPMCSRF (см. ниже) является обязательным. Подробнее читайте в статье "Защита от CSRF-атак при интеграции c bpm'online". Если токен BPMCSRF не будет использован, сервер вернет ошибку с кодом 403.
На демо-сайтах пробных версий bpm'olnline защита от CSRF-атак отключена. Поэтому для таких сайтов использовать cookie и токен BPMCSRF в заголовках запросов не нужно.
Если аутентификация пользователя выполнена успешно, то в теле ответа будет содержаться JSON-объект, у которого для свойства Code будет установлено значение 0 (рис. 1, 8). В случае ошибки в свойствах JSON-объекта будут содержаться соответствующие код и сообщение. Например, если в приложении не создан пользователь, указанный на шаге 5, то сервис аутентификации вернет ошибку неправильного воода логина и пароля (рис.2).
Рис. 2. — Запрос к сервису аутентификации с данными несуществующего пользователя
Запрос к конфигурационному сервису
К СВЕДЕНИЮ
Конфигурационный сервис UsrCustomConfigurationService, используемый в этой статье (см. "Предварительные настройки", "Как создать свой конфигурационный сервис"), работает с HTTP запросами только по методу GET. Такие запросы не содержат тела. При необходимости выполнять другие типы запросов (например, POST-запросы) добавьте соответствующее тело запроса (например, как в шаге 5 раздела "Аутентификация").
Для формирования запроса к конфигурационному сервису UsrCustomConfigurationService (рис. 3):
Рис. 3. — Запрос к конфигурационному сервису
1. Выберите HTTP-метод GET.
2. Укажите URL конфигурационного сервиса. URL формируется по следующей маске:
[Адрес приложения]/0/rest/[Название конфигурационного сервиса]/[Конечная точка пользовательского сервиса]?[Опциональные параметры]
Например:
https://009189-studio.bpmonline.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=User01
3. Добавьте необходимые cookie (BPMLOADER, .ASPXAUTH, BPMCSRF и UserName), полученные в HTTP-ответе от сервиса аутентификации (рис. 4).
Рис. 4. — Добавление в запрос cookie
ВАЖНО
При включенной защите от CSRF-атак использование cookie BPMCSRF и токена BPMCSRF (см. ниже) является обязательным.. Для этого добавьте пару "ключ-значение" в заголовок запроса. В качестве ключа используйте "BPMCSRF", а в качестве значения — то же значение, что и для cookie BPMCSRF (рис. 5).
Рис. 5. — Добавление в запрос токена BPMCSRF
4. Во всех запросах, кроме первого после аутентификации, добавьте cookie BPMSESSIONID.
ВАЖНО
Сессия пользователя будет создана только при первом запросе к конфигурационному сервису. После этого в HTTP-ответе будет возвращен cookie BPMSESSIONID (см. вкладку [Cоokies] HTTP-ответа рис. 3, 4). Следовательно, в заголовок самого первого запроса cookie BPMSESSIONID добавлять не нужно.
Если в последующие запросы не добавлять cookie BPMSESSIONID, то каждый раз будет создаваться новая пользовательская сессия. При достаточно большом количестве запросов (даже несколько запросов в минуту) это приведет к существенному повышению потребления оперативной памяти и к снижению производительности.
5. Нажмите кнопку [Send] для отправки запроса к сервису.
Если контакт, указанный в параметре Name, не найден в системе, то в свойстве "GetContactIdByNameResult" JSON-объекта, возвращенного в HTTP-ответе, будет значение "" (рис. 3, 6). Если контакт существует, то сервис вернет его идентификатор (рис. 6).
Рис. 6. — Результат выполнения запроса
