Интеграция с Creatio по протоколу OData 4

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

OData (Open Data Protocol) — это утвержденный ISO/IEC стандарт OASIS, который определяет набор лучших практик для построения и использования REST API. Он позволяет создавать службы на основе REST, которые предоставляют возможность веб-клиентам с помощью простых HTTP-запросов публиковать и редактировать ресурсы, идентифицированные с использованием URL и определенные в модели данных.

Приложение Creatio поддерживает протоколы OData 3 и OData 4. OData 4, пришедший на смену OData 3, значительно расширяет возможности последнего, при этом данные протоколы не совместимы по формату данных, возвращаемых сервером. Детальную информацию про функциональность и отличия можно найти в документации OData.

Реализация протокола OData 4 в Creatio

Для использования протокола OData 4 в блок конфигурационного файла Web.Config, который находится в корневой папке приложения Creatio, необходимо добавить следующую строку:

<add key="Feature-UseODataV4" value="true" />

Доступ к объектам Creatio по протоколу OData 4 предоставляет веб-сервис odata.

Адрес сервиса odata:

http://mycreatio.com/0/odata

Структура запроса по протоколу OData 4

Структурные элементы запроса:

• Строка.
• Заголовки.
• Тело.

Строка запроса

Структура строки запроса:

method my_Creatio_site/0/odata/data_resource?$parameters

// Добавить экземпляр объекта коллекции Contact.
POST http://mycreatio.com/0/odata/Contact

// Получить экземпляры объектов коллекции Employee, в которых значение поля FullJobTitle равно Developer и значение поля Name вложенной коллекции объектов Account содержит другие значения кроме Our company.
GET http://mycreatio.com/0/odata/Employee?$filter=FullJobTitle eq 'Developer' and Account/Name ne 'Our company'

method

Приложение Creatio поддерживает следующие методы запроса:

• GET — получение данных.
• POST — добавление данных.
• PATCH — изменение данных.
• DELETE — удаление данных.

data_resource

Под ресурсом данных необходимо понимать путь к источнику информации, которую необходимо получить в ответе на запрос.

Структура ресурса данных:

objects_collection(object_id)/object_field

Структурные элементы ресурса данных:

objects_collection (required)

Имя таблицы базы данных (имя коллекции объектов).

Получить перечень таблиц базы данных можно выполнив запрос:

для MySQL

SELECT * FROM INFORMATION_SCHEMA.TABLES

для Oracle

SELECT * FROM ALL_TABLES

для PostgreSQL

SELECT table_name FROM information_schema.tables

---

object_id (optional)

Идентификатор строки записи таблицы базы данных (идентификатор экземпляра объекта коллекции).

---

object_field (optional)

Поле записи таблицы базы данных (поле экземпляра объекта коллекции).

---

parameters

Необязательные параметры OData 4, которые разрешены к использованию в строке GET-запроса к Creatio:

$value

Значение поля.

---

$count

$count=true

Количество элементов, которые попали в выборку.

---

$skip

$skip=n

n первых элементов, которые не должны попасть в выборку.

---

$top

$top=n

n первых элементов, которые должны попасть в выборку.

---

$select

$select=field1,field2,...

Набор полей, которые должны попасть в выборку.

---

$orderby

$orderby=field asc

$orderby=field desc

Сортировка значений поля, которые попали в выборку.

---

$expand

$expand=field1,field2,...

Расширение связанных полей.

---

$filter

$filter=field template 'field_value'

Фильтрация полей, которые должны попасть в выборку.

---

При работе с параметрами разрешено использовать следующие операторы:

?

Указание параметров.

---

$

Указание имени параметра.

---

&

Использование 2-х и более параметров.

---

Заголовки запроса

Заголовки, которые разрешены к использованию в запросе к Creatio:

Accept

Accept: application/json

Тип данных, который можно ожидать в ответе от сервера.

---

Content-Type

Content-Type: application/json; charset=utf-8

Кодировка и тип ресурса, который передается в теле запроса.

---

ForceUseSession

ForceUseSession: true

Заголовок ForceUseSession отвечает за принудительное использование уже существующей сессии. Отсутствует необходимость использования в запросе к сервису аутентификации AuthService.svc.

---

BPMCSRF

BPMCSRF: authentication_cookie_value

Аутентификационный cookie.

---

Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO

ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO

Тело запроса

Структура тела запроса:

{
    "field1": "value1",
    "field2": "value2",
    ...
}

Структурные элементы тела запроса:

field1, field2, ... (required)

Имена полей, которые передаются в теле запроса.

---

value1, value2, ... (required)

Значения полей field1, field2, ..., которые передаются в теле запроса.

---

{
    // Добавить в поле Name значение New User.
    "Name": "New User",
    // Добавить в поле JobTitle значение Customer manager.
    "JobTitle": "Customer manager"
}

Структура ответа на запрос

Структурные элементы ответа на запрос:

• Код состояния.
• Тело.

Код состояния

В ответе на запрос сервер возвращает код состояния, который зашифрован в 3-х цифрах. Первая цифра указывает на класс состояния. Вторая и третья цифры — порядковый номер ответа. При интеграции с приложением Creatio по протоколу OData 4, сервер возвращает следующие классы http-кодов:

1. 2xx (успех) — успешное принятие и обработка запроса клиента.
2. 3хх (перенаправление) — для успешного выполнения операции необходимо сделать другой запрос.
3. 4хх (ошибка клиента) — при построении запроса на стороне клиента произошла ошибка. Сервер должен вернуть гипертекстовое объяснение получения кода класса 4хх.
4. 5хх (внутренняя ошибка сервера) — неудачное выполнение запроса по вине сервера.

Получение кода классов 4хх и 5хх является результатом неуспешного выполнения запроса.

При отправке запроса по протоколу OData 4 в ответ от сервера Creatio можно получить следующие коды состояния:

Тело ответа

Структура тела ответа на запрос:

{
    "@odata.context": "http://my_Creatio_site/0/odata$metadata#data_resource",
    "value": [
    {
        "object1 field1": "object1 field_value1",
        "object1 field2": "object1 field_value2",
        ...
    },
    {
        "object2 field1": "object2 field_value1",
        "object2 field2": "object2 field_value2",
        ...
    },
    ...
    ]
}

Структурные элементы тела ответа:

@odata.context

Информация о типе возвращаемых данных. Кроме пути к источнику данных, элемент data_resource может содержать параметр $entity, который показывает что в ответе был возвращен единственный экземпляр объекта коллекции.

---

value

Содержит коллекцию объектов. Отсутствует если в ответе был возвращен один экземпляр объекта коллекции.

---

Квадратные скобки

Коллекция объектов.

---

Вложенные фигурные скобки

Экземпляры объектов коллекции.

---

object1 field1, object1 field2, ..., object2 field1, object2 field2, ...

Имена полей field1, field2, ... экземпляров объектов object1, object2, ... коллекции.

---

object1 field_value1, object1 field_value2, ..., object2 field_value1, object2 field_value2, ...

Значения полей field1, field2, ... экземпляров объектов object1, object2, ... коллекции.

---

Status: 201 Created

{
    "@odata.context": "http://mycreatio.com/0/odata$metadata#Contact$entity",
    "Id": "37dab67d-199d-4275-9eb6-22bea86cb969",
    "Name": "New User",
    "OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "CreatedOn": "2020-03-02T08:31:34.8076517Z",
    "CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "ModifiedOn": "2020-03-02T08:31:34.8076517Z",
    "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "ProcessListeners": 0,
    "Dear": "",
    "SalutationTypeId": "00000000-0000-0000-0000-000000000000",
    "GenderId": "00000000-0000-0000-0000-000000000000",
    "AccountId": "00000000-0000-0000-0000-000000000000",
    "DecisionRoleId": "00000000-0000-0000-0000-000000000000",
    "TypeId": "00000000-0000-0000-0000-000000000000",
    "JobId": "00000000-0000-0000-0000-000000000000",
    "JobTitle": "Customer manager",
    "DepartmentId": "00000000-0000-0000-0000-000000000000",
    "BirthDate": "0001-01-01T00:00:00Z",
    "Phone": "",
    "MobilePhone": "",
    "HomePhone": "",
    "Skype": "",
    "Email": "",
    "AddressTypeId": "00000000-0000-0000-0000-000000000000",
    "Address": "",
    "CityId": "00000000-0000-0000-0000-000000000000",
    "RegionId": "00000000-0000-0000-0000-000000000000",
    "Zip": "",
    "CountryId": "00000000-0000-0000-0000-000000000000",
    "DoNotUseEmail": false,
    "DoNotUseCall": false,
    "DoNotUseFax": false,
    "DoNotUseSms": false,
    "DoNotUseMail": false,
    "Notes": "",
    "Facebook": "",
    "LinkedIn": "",
    "Twitter": "",
    "FacebookId": "",
    "LinkedInId": "",
    "TwitterId": "",
    "TwitterAFDAId": "00000000-0000-0000-0000-000000000000",
    "FacebookAFDAId": "00000000-0000-0000-0000-000000000000",
    "LinkedInAFDAId": "00000000-0000-0000-0000-000000000000",
    "PhotoId": "00000000-0000-0000-0000-000000000000",
    "GPSN": "",
    "GPSE": "",
    "Surname": "User",
    "GivenName": "New",
    "MiddleName": "",
    "Confirmed": true,
    "IsNonActualEmail": false,
    "Completeness": 0,
    "LanguageId": "6ebc31fa-ee6c-48e9-81bf-8003ac03b019",
    "Age": 0

}

Status: 200 OK

{
    "@odata.context": "http://mycreatio.com/0/odata$metadata#Employee",
    "value": [
        {
            "Id": "c31c7862-fe33-4a13-9bbc-0943fa08fd02",
            "CreatedOn": "2017-03-30T14:50:04Z",
            "CreatedById": "76929f8c-7e15-4c64-bdb0-adc62d383727",
            "ModifiedOn": "2020-02-14T06:30:46.234Z",
            "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
            "ProcessListeners": 0,
            "ContactId": "227aab3b-7c0c-4181-abf9-81585563ab23",
            "Name": "William Walker",
            "OrgStructureUnitId": "d436a9ce-9690-4415-9e03-e8061d7cabb5",
            "Notes": "",
            "JobId": "11d68189-ced6-df11-9b2a-001d60e938c6",
            "FullJobTitle": "Developer",
            "OwnerId": "76929f8c-7e15-4c64-bdb0-adc62d383727",
            "CareerStartDate": "2019-09-08T00:00:00Z",
            "CareerDueDate": "0001-01-01T00:00:00Z",
            "ProbationDueDate": "2020-01-09T00:00:00Z",
            "ReasonForDismissalId": "00000000-0000-0000-0000-000000000000",
            "AccountId": "a0bf3e92-f36b-1410-0499-00155d043204",
            "ManagerId": "3e5bd47e-1ebd-41db-a9a6-a3560dcee3cb"
        }
    ]
}

Типы запросов

Получение данных

Основные правила GET-запросов:

• Разрешено использовать параметры.
• Отсутствует тело запроса.
• Присутствует тело ответа.

Структура GET-запроса:

GET my_Creatio_site/0/odata/data_resource?$parameters

Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value

Структура тела ответа на GET-запрос:

{
    "@odata.context": "http://my_Creatio_site/0/odata$metadata#data_resource",
    "value": [
        {
            "object1 field1": "object1 field_value1",
            "object1 field2": "object1 field_value2",
            ...
        },
        {
            "object2 field1": "object2 field_value1",
            "object2 field2": "object2 field_value2",
            ...
        },
        ...
    ]
}

Структурные элементы тела ответа на GET-запрос принимают следующие значения:

@odata.context

Информация о типе возвращаемых данных. Кроме пути к источнику данных, элемент data_resource может содержать параметр $entity, который показывает что в ответе был возвращен единственный экземпляр объекта коллекции.

---

value

Содержит коллекцию объектов. Отсутствует если в ответе был возвращен один экземпляр объекта коллекции.

---

object1 field1, object1 field2, ..., object2 field1, object2 field2, ...

Имена полей field1, field2, ... экземпляров объектов object1, object2, ... коллекции.

---

object1 field_value1, object1 field_value2, ..., object2 field_value1, object2 field_value2, ...

Значения полей field1, field2, ... экземпляров объектов object1, object2, ... коллекции.

---

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

Основные правила POST-запросов:

• Запрещено использовать параметры.
• Присутствует тело запроса.
• Присутствует тело ответа.

Структура POST-запроса:

POST my_Creatio_site/0/odata/objects_collection

Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value

В качестве ресурса данных POST-запроса может выступать только коллекция объектов, в которой необходимо создать новый экземпляр объекта коллекции.

Структурные элементы строки POST-запроса:

objects_collection (required)

Имя коллекции, в которой необходимо создать новый экземпляр объекта коллекции.

---

Структура тела POST-запроса:

{
    "field1": "value1",
    "field2": "value2",
    ...
}

Структурные элементы тела POST-запроса:

field1, field2, ... (required)

Имена полей создаваемого экземпляра объекта коллекции, которые необходимо заполнить.

---

value1, value2, ... (required)

Значения полей field1, field2, ..., создаваемого экземпляра объекта коллекции, которые необходимо заполнить.

---

Структура тела ответа на POST-запрос:

{
    "@odata.context": "http://my_Creatio_site/0/odata$metadata#data_resource$entity",
    "field1": "value1",
    "field2": "value2",
    ...
}

Структурные элементы тела ответа на POST-запрос принимают следующие значения:

@odata.context

Информация о типе возвращаемых данных. Кроме пути к источнику данных, элемент data_resource может содержать параметр $entity, который показывает что в ответе был возвращен единственный экземпляр объекта коллекции.

---

field1, field2, ...

Имена полей созданного экземпляра объекта коллекции.

---

value1, value2, ...

Значения полей field1, field2, ... созданного экземпляра объекта коллекции.

---

Изменение данных

Основные правила PATCH-запросов:

• Запрещено использовать параметры.
• Присутствует тело запроса.
• Отсутствует тело ответа.

В качестве ресурса данных PATCH-запроса может выступать только коллекция объектов, в которой необходимо изменить данные экземпляра объекта.

Структура PATCH-запроса:

PATCH my_Creatio_site/0/odata/objects_collection(object_id)

Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value

Структурные элементы строки PATCH-запроса:

objects_collection (required)

Имя коллекции, экземпляр объекта которой необходимо изменить.

---

object_id (required)

Идентификатор изменяемого экземпляра объекта коллекции.

---

Структура тела PATCH-запроса:

{
    "field1": "value1",
    "field2": "value2",
    ...
}

Структурные элементы тела PATCH-запроса:

field1, field2, ... (required)

Имена полей изменяемого экземпляра объекта коллекции.

---

value1, value2, ... (required)

Новые значения для полей field1, field2, ... изменяемого экземпляра объекта коллекции.

---

Удаление данных

Основные правила DELETE-запросов:

• Запрещено использовать параметры.
• Отсутствует тело запроса.
• Отсутствует тело ответа.

В качестве ресурса данных DELETE-запроса может выступать только коллекция объектов, экземпляр объекта которой необходимо удалить.

Структура DELETE-запроса:

DELETE my_Creatio_site/0/odata/objects_collection(object_id)

Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: authentication_cookie_value

Структурные элементы строки DELETE-запроса:

objects_collection (required)

Имя коллекции, экземпляр объекта которой необходимо удалить.

---

object_id (required)

Идентификатор удаляемого экземпляра объекта коллекции.

---