Выполнение запросов по протоколу OData с помощью Fiddler
Glossary Item Box
Общие сведения
Для интеграции с Creatio по протоколу OData необходимо выполнять HTTP-запросы. Запросы можно формировать с помощью любого языка программирования, например, C#, PHP и т. п. Однако, для понимания принципов формирования запросов удобно использовать инструменты редактирования и отладки HTTP-запросов, такие, как Postman или Fiddler. В этой статье показаны примеры выполнения запросов к Creatio с помощью Fiddler.
Подробнее о протоколе OData можно узнать из блока статей "Интеграция по протоколу OData".
Аутентификация
Прежде чем выполнять запросы по протоколу OData, необходимо выполнить аутентификацию и получить соответствующие cookies. Для аутентификации в Creatio предназначен сервис AuthService.svc. Подробнее об аутентификации можно узнать из статьи "Аутентификация внешних запросов".
Для выполнения запроса к сервису AuthService.svc с помощью Fiddler необходимо перейти на вкладку [Composer] и выполнить следующие действия (рис. 1):
1. Выбрать HTTP-метод POST.
2. Указать URL сервиса аутентификации:
https://mycreatio.com/ServiceModel/AuthService.svc/Login
3. Указать версию 1.1 протокола HTTP.
4. Указать тип содержимого тела запроса:
Content-Type: application/json
5. Добавить тело запроса — JSON-объект, содержащий аутентификационные данные (логин и пароль):
{
"UserName":"Supervisor",
"UserPassword":"Supervisor"
}
Рис. 1. — Формирование запроса аутентификации
Далее необходимо выполнить запрос, нажав на кнопку [Execute]. В результате, в окне сессий Fiddler отобразится ответ от сервиса AuthService.svc (рис. 2). После двойного клика по строке ответа отобразится вкладка [Inspectors], содержащая все свойства ответа.
Рис. 2. — Свойства HTTP-ответа от сервиса AuthService.svc
Полученные в HTTP-ответе cookie (BPMLOADER, .ASPXAUTH и BPMCSRF) необходимо использовать в дальнейших запросах к сервисам Creatio, требующих аутентификационных данных.
Если аутентификация пользователя выполнена успешно, то в теле ответа будет содержаться JSON-объект, у которого будет установлено значение 0 для свойства Code. В случае ошибки в свойствах JSON-объекта будут содержаться соответствующие код и сообщение.
Запрос к сервису OData
Например, необходимо добавить новую активность. Для активности нужно заполнить колонки [Заголовок] ([Title]), [Ответственный] ([Owner]) и [Заметки] ([Notes]).
Для формирования запроса на добавление таких данных в Fiddler необходимо перейти на вкладку [Composer] и выполнить следующие действия (рис. 3):
1. Выбрать HTTP-метод POST.
2. Указать URL к сервису OData (в примере показано использование протокола OData 3):
http(s)://mycreatio.com/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.
ВАЖНО
Сессия пользователя будет создана только при первом запросе к сервису EntityDataService.svc, после чего в HTTP-ответе будет возвращен cookie BPMSESSIONID (рис. 5, 2). Следовательно, в заголовок самого первого запроса cookie BPMSESSIONID добавлять не нужно (рис. 3, 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.
Значение идентификатора ответственного можно посмотреть в браузере, открыв соответствующую запись для редактирование (рис. 4), или получить по запросу.
Рис. 3. — Формирование запроса на добавление данных
Рис. 4. — Отображение идентификатора контакта в браузере
Далее необходимо выполнить запрос, нажав на кнопку [Execute]. В результате, в окне сессий Fiddler отобразится ответ от сервиса EntityDataService.svc (рис. 5). После двойного клика по строке ответа (1), отобразится вкладка [Inspectors], содержащая все свойства ответа.
Рис. 5. — Свойства HTTP-ответа от сервиса EntityDataService.svc
К СВЕДЕНИЮ
Ответ от сервиса EntityDataService.svc может содержать cookie BPMSESSIONID, если запрос был выполнен впервые (рис. 5, 2).
В теле ответа содержится добавленная запись в формате XML (рис. 5, 3). XML-элемент <id> содержит идентификатор добавленной активности, который можно использовать при составлении других запросов, например, на редактирование.
В результате выполнения запроса в раздел [Активности] ([Activities]) будет добавлена новая запись (рис. 6).
Рис. 6. — Результат выполнения запроса на добавление активности
