Выполнение запросов по протоколу OData с помощью Fiddler
Glossary Item Box
Общие сведения
Для интеграции с 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. — Результат выполнения запроса на изменение активности
