Общие сведения

Для интеграции с конфигурационными сервисами 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". На демо-сайтах пробных версий 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. — Результат выполнения запроса