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

Для интеграции с bpm'online по протоколу OData необходимо выполнять HTTP-запросы к сервису EntityDataService.svc. Запросы можно формировать с помощью любого языка программирования, например, C#, PHP и т. п. Однако, для понимания принципов формирования запросов удобно использовать инструменты редактирования и отладки HTTP-запросов, такие, как PostMan или Fiddler. В этой статье показаны примеры выполнения запросов к bpm'online с помощью Fiddler.

Подробнее о протоколе OData можно узнать из статьи "Возможности интеграции с bpm'online по протоколу OData".

Предварительные настройки

ВАЖНО Если пользователь, от имени которого будут выполняться запросы к сервису EntityDataService.svc, не входит в группу администраторов, то его нужно добавить в группу [Доступ к OData] ([Access to OData]) в разделе [Права доступа на операции] (Operation permissions) (рис. 1, рис. 2). Также для работы с объектом bpm'online по протоколу OData необходимо этому пользователю разрешить доступ к объекту для внешних сервисов (рис. 3).

Рис. 1. — Группа [Доступ к OData] в разделе [Права доступа на операции]

Рис. 2. — Пользователь в группе [Доступ к OData]

Рис. 3. — Добавление пользователя для доступа внешних сервисов к объекту [Активность]

Аутентификация

Прежде чем выполнять запросы к сервису EntityDataService.svc, необходимо выполнить аутентификацию и получить соответствующие cookies. Для аутентификации в bpm'online предназначен отдельный сервис AuthService.svc. Подробнее об этом сервисе можно узнать из статьи "Сервис аутентификации AuthService.svc".

Для выполнения запроса к сервису AuthService.svc с помощью Fiddler необходимо перейти на вкладку [Composer] и выполнить следующие действия (рис. 4):

1. Выбрать HTTP-метод POST.

2. Указать URL сервиса аутентификации, который формируется по следующей маске:

http(s)://[Адрес приложения bpm'online]/ServiceModel/AuthService.svc/Login

Например:

https://012496-sales-enterprise.bpmonline.com/ServiceModel/AuthService.svc/Login

3. Указать версию 1.1 протокола HTTP.

4. Указать тип содержимого тела запроса:

Content-Type: application/json

5. Добавить тело запроса — JSON-объект, содержащий аутентификационные данные (логин и пароль):

{"UserName": "User01", "UserPassword":"User01"}

Рис. 4. — Формирование запроса аутентификации

Далее необходимо выполнить запрос, нажав на кнопку [Execute]. В результате, в окне сессий Fiddler отобразится ответ от сервиса AuthService.svc (рис. 5). После двойного клика по строке ответа (1) отобразится вкладка [Inspectors], содержащая все свойства ответа.

Рис. 5. — Свойства HTTP-ответа от сервиса AuthService.svc

ВАЖНО Полученные в HTTP-ответе cookie (BPMLOADER, .ASPXAUTH и BPMCSRF) необходимо использовать в дальнейших запросах к сервисам bpm'online, требующих аутентификационных данных (рис. 5, 2).

ВАЖНО Если аутентификация пользователя выполнена успешно, то в теле ответа будет содержаться JSON-объект, у которого будет установлено значение 0 для свойства Code (рис. 5, 3). В случае ошибки в свойствах JSON-объекта будут содержаться соответствующие код и сообщение.

Добавление данных

Например, необходимо добавить новую активность. Для активности нужно заполнить колонки [Заголовок] ([Title]), [Ответственный] ([Owner]) и [Заметки] ([Notes]).

Для формирования запроса на добавление таких данных в Fiddler необходимо перейти на вкладку [Composer] и выполнить следующие действия (рис. 6):

1. Выбрать HTTP-метод POST.

2. Указать URL к сервису EntityDataService.svc, который формируется по следующей маске:

http(s)://[Адрес приложения bpm'online]/0/ServiceModel/EntityDataService.svc/ActivityCollection/

3. Указать версию 1.1 протокола HTTP.

4. В заголовок запроса добавить:

• тип содержимого запроса — application/atom+xml;
• необходимые cookie (BPMLOADER, .ASPXAUTH, BPMSESSIONID и BPMCSRF);
• CSRF-токен BPMCSRF, содержащий значение одноименной cookie (BPMCSRF).

Пример HTTP-заголовка запроса приведен ниже:

Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Cookie: BPMSESSIONID=cxa54p2dsb4wnqbbzvgyxcoo; BPMCSRF=6yCmyILSlIE8/toyQm9Ca.; BPMLOADER=rqqjjeqyfaudfyk4xu404j5f; .ASPXAUTH=697...A292D8164;
BPMCSRF: 6yCmyILSlIE8/toyQm9Ca.

ВАЖНО При включенной защите от CSRF-атак обязательно использование как cookie BPMCSRF, так и токена BPMCSRF. Подробности можно узнать из статьи "Защита от CSRF-атак при интеграции c bpm'online". На демо-сайтах пробных версий bpm'olnline защита от CSRF-атак отключена. Поэтому для таких сайтов использовать cookie и токен BPMCSRF в заголовках запросов не нужно.

ВАЖНО Сессия пользователя будет создана только при первом запросе к сервису EntityDataService.svc, после чего  в HTTP-ответе будет возвращен cookie BPMSESSIONID (рис. 8, 2). Следовательно,  в заголовок самого первого запроса cookie BPMSESSIONID добавлять не нужно (рис. 6, 4). Если в последующие запросы не добавлять cookie BPMSESSIONID, то каждый раз будет создаваться новая пользовательская сессия. При достаточно большом количестве запросов (даже несколько запросов в минуту) это приведет к существенному возрастанию потребляемой оперативной памяти и к снижению производительности.

НА ЗАМЕТКУ Если необходимо отправлять запрос и получать ответ в формате JSON, укажите в заголовке запроса: Content-Type = "application/json" Accept = "application/json;odata=verbose"

5. Добавить в тело HTTP-запроса содержимое в формате XML :

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <content type="application/xml">
        <properties xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
            <Title xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">process the incomming website form request</Title>
            <Notes xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">please, email to client@gmail.com and process the following request: clients request</Notes>
            <OwnerId xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">64844c83-c6c2-4eee-a0e9-e26cef529d2f</OwnerId>
        </properties>
    </content>
</entry>

В этом запросе заполняются все необходимые колонки объекта.

ВАЖНО Если колонка объекта является справочником, то для нее нужно указать не имя справочника, а его идентификатор из базы данных. Также в запросе к названию колонки-справочника нужно добавить суффикс Id. В приведенном примере такой колонкой является колонка [Ответственный] ([Owner]), для которой в запросе указывается идентификатор OwnerId. Значение идентификатора ответственного можно посмотреть в браузере, открыв соответствующую запись для редактирование (рис. 7), или получить по запросу.

Рис. 6. — Формирование запроса на добавление данных

Рис. 7. — Отображение идентификатора контакта в браузере

Далее необходимо выполнить запрос, нажав на кнопку [Execute]. В результате, в окне сессий Fiddler отобразится ответ от сервиса EntityDataService.svc (рис. 8). После двойного клика по строке ответа (1), отобразится вкладка [Inspectors], содержащая все свойства ответа.

Рис. 8. — Свойства HTTP-ответа от сервиса EntityDataService.svc

К СВЕДЕНИЮ Ответ от сервиса EntityDataService.svc может содержать cookie BPMSESSIONID, если запрос был выполнен впервые (рис. 8, 2).

В теле ответа содержится добавленная запись в формате XML (рис. 8, 3). XML-элемент <id> содержит идентификатор добавленной активности, который можно использовать при составлении других запросов, например, на редактирование.

В результате выполнения запроса в раздел [Активности] ([Activities]) будет добавлена новая запись (рис. 9).

Рис. 9. — Результат выполнения запроса на добавление активности

Выборка данных

Запрос на выборку данных не содержит тела. Фильтрация данных выполняется на основании значений параметров URL. Подробнее запросы на выборку с фильтрацией рассмотрены в статье "Примеры запросов на выборку с фильтрацией".

Для формирования запроса на выборку данных в Fiddler необходимо перейти на вкладку [Composer] и выполнить следующие действия (рис. 10):

1. Выбрать HTTP-метод GET.

2. Указать URL к сервису EntityDataService.svc, который формируется по следующей маске:

http(s)://[Адрес приложения bpm'online]/0/ServiceModel/EntityDataService.svc/ActivityStatusCollection?$filter=Code%20eq%20'InProgress'

3. Указать версию 1.1 протокола HTTP.

4. В заголовке запроса указать тип содержимого тела запроса как application/atom+xml. Также в заголовок запроса добавить все необходимые cookie (BPMLOADER, .ASPXAUTH, BPMSESSIONID, BPMCSRF) и токен BPMCSRF:

Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Cookie: BPMSESSIONID=cxa54p2dsb4wnqbbzvgyxcoo; BPMCSRF=6yCmyILSlIE8/toyQm9Ca.; BPMLOADER=rqqjjeqyfaudfyk4xu404j5f; .ASPXAUTH=697...A292D8164;
BPMCSRF: 6yCmyILSlIE8/toyQm9Ca.

НА ЗАМЕТКУ Если необходимо отправлять запрос и получать ответ в формате JSON, укажите в заголовке запроса: Content-Type = "application/json" Accept = "application/json;odata=verbose"

Рис. 10. — Формирование запроса на выборку данных

Далее необходимо выполнить запрос, нажав на кнопку [Execute]. В результате, в окне сессий Fiddler отобразится ответ от сервиса EntityDataService.svc (рис. 11). После двойного клика по строке ответа (1) отобразится вкладка [Inspectors], содержащая все свойства ответа. В теле HTTP-ответа содержится результат выборки (2).

Рис. 11. — Свойства HTTP-ответа от сервиса EntityDataService.svc

Обновление данных

Например, необходимо в добавленной активности изменить значение заголовка.

Для формирования запроса на добавление данных в Fiddler необходимо перейти на вкладку [Composer] и выполнить следующие действия (рис. 12):

1. Указать HTTP-метод MERGE.

ВАЖНО Использование HTTP–методов PUT и DELETE приведет к ошибке "405 Method not allowed", если не отключить HTTP-расширение WebDAV в файле Web.Config приложения.

2. Указать URL к сервису EntityDataService.svc, который формируется по следующей маске:

http(s)://[Адрес приложения bpm'online]/0/ServiceModel/EntityDataService.svc/ActivityCollection(guid'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')

Здесь используется идентификатор добавленной записи (например, 9741fffe-ff81-46ba-8d99-1f488ec5502e), который можно получить в HTTP-ответе на запрос добавления. Также его можно посмотреть в браузере, открыв соответствующую запись на редактирование (рис. 13).

3. Указать версию 1.1 протокола HTTP.

4. В заголовке запроса указать тип содержимого тела запроса как application/atom+xml. Также в заголовок запроса добавить все необходимые cookie (BPMLOADER, .ASPXAUTH, BPMSESSIONID, BPMCSRF) и токен BPMCSRF:

Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Cookie: BPMSESSIONID=cxa54p2dsb4wnqbbzvgyxcoo; BPMCSRF=6yCmyILSlIE8/toyQm9Ca.; BPMLOADER=rqqjjeqyfaudfyk4xu404j5f; .ASPXAUTH=697...A292D8164;
BPMCSRF: 6yCmyILSlIE8/toyQm9Ca.

НА ЗАМЕТКУ Если необходимо отправлять запрос и получать ответ в формате JSON, укажите в заголовке запроса: Content-Type = "application/json" Accept = "application/json;odata=verbose"

5. Добавить содержимое в формате XML в тело запроса:

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <content type="application/xml">
        <properties xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
            <Title xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">process the incomming website form request (Updated)</Title>
        </properties>
    </content>
</entry>

К СВЕДЕНИЮ Рекомендуется указывать только те колонки, которые нужно изменить.

Рис. 12. — Формирование запроса на обновление данных

Рис. 13. — Отображение идентификатора активности в браузере

После этого необходимо выполнить запрос, нажав на кнопку [Execute]. В результате, в окне сессий Fiddler отобразится ответ от сервиса EntityDataService.svc (рис. 14). После двойного клика по строке ответа (1) отобразится вкладка [Inspectors], содержащая все свойства ответа. В теле HTTP-ответа нет содержимого (2).

Рис. 14. — Свойства HTTP-ответа от сервиса EntityDataService.svc

В результате выполнения запроса для добавленной ранее записи будет изменен заголовок (рис. 15).

Рис. 15. — Результат выполнения запроса на изменение активности