Creatio development guide
PDF

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

Glossary Item Box

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

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

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

При планировании интеграции с Creatio по протоколу OData необходимо использовать протокол версии 4.

 

Выполнение запросов к Creatio невозможно без аутентификации.

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

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

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

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

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

https://mycreatio.com/0/odata

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

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

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

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

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

method my_Creatio_site/0/odata/data_resource?$parameters
Пример строки POST-запроса
 
 
// Добавить экземпляр объекта коллекции Contact.
POST https://mycreatio.com/0/odata/Contact
Пример строки GET-запроса
 
 
// Получить экземпляры объектов коллекции Employee, в которых значение поля FullJobTitle равно Developer и значение поля Name вложенной коллекции объектов Account содержит другие значения кроме Our company.
GET https://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.

Заголовки Content-Type и Accept не обязательны к использованию в GET-запросах.

Пример заголовков POST-запроса
 
 
Accept: application/json
Content-Type: application/json; charset=utf-8
ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO
Пример заголовков GET-запроса
 
 
ForceUseSession: true
BPMCSRF: OpK/NuJJ1w/SQxmPvwNvfO

Тело запроса

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

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

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

field1, field2, ... (required)
Имена полей, которые передаются в теле запроса.
value1, value2, ... (required)
Значения полей field1, field2, ..., которые передаются в теле запроса.
Пример тела POST-запроса
 
 
{
    // Добавить в поле 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 можно получить следующие коды состояния:

200 OK Запрос, который не создает ресурс, успешно завершен и значение ресурса не равно нулю. В этом случае, тело ответа должно содержать значение ресурса, указанного в URL-адресе запроса. Информация, возвращаемая с ответом, зависит от метода, используемого в запросе:
GET — запрашиваемый ресурс был найден и передан в теле ответа.
POST — ресурс, описывающий результат действия сервера на запрос, передан в теле ответа.
 
201 Created Запрос, который успешно создает ресурс. Тело ответа должно содержать созданный ресурс. Используется для POST-запросов, которые создают коллекциюсоздают объект мультимедиа (например, фотографию) или вызывают действие через его импорт.  
202 Accepted Запрос на работу с данными принят в обработку, но еще не завершен. Нет гарантий, что запрос успешно выполнится в процессе обработки данных (асинхронная обработка запроса).  
204 No Content Запрос был успешно обработан, но нет необходимости возвращать какие-либо данные. Запрашиваемый ресурс имеет нулевое значение. В ответе были переданы только заголовки, тело ответа должно быть пустым.  
3xx Redirection Перенаправление указывает что клиент должен предпринимать дальнейшие действия для выполнения запроса. Ответ должен включать заголовок Location c URL-адресом, по которому можно получить результат. Также ответ может включать заголовок Retry-After, который отображает время (в секундах). Это время характеризует период, в течение которого клиент может подождать прежде чем повторить запрос к ресурсу, который был возвращен в заголовке Location.  
304 Not Modified Клиент выполняет GET-запрос с заголовком If-None-Match и содержимое не изменилось. Ответ не должен содержать другие заголовки.  
404 Not Found Сервер не может найти ресурс, указанный в URL-адресе. Дополнительная информация может содержаться в теле ответа.  
405 Method Not Allowed Ресурс, указанный в URL-адресе, не поддерживает указанный метод запроса. В ответе должен быть получен заголовок Allow, который должен содержать список доступных методов запроса для ресурса.  
406 Not Acceptable Ресурс, указанный в URL-адресе запроса, не имеет текущего представления, которое было бы приемлемым для клиента в соответствии с AcceptAccept-Charset и Accept-Language заголовками запроса. Служба не желает предоставлять представление по умолчанию.  
410 Gone Запрошенный ресурс больше недоступен. Ресурс раньше был по указанному URL, но был удален и теперь недоступен.  
412 Precondition Failed Клиент указал в заголовке запроса условие, которое ресурс не может выполнить.  
424 Failed Dependency Текущий запрос к ресурсу невозможно выполнить, потому что запрошенное действие зависит от другого действия, выполнить которое не удалось. Запрос не был выполнен через сбой зависимости.  
501 Not Implemented Клиент использует метод запроса, который не реализован протоколом OData 4 и не может быть обработан. Тело ответа должно содержать описание нереализованного функционала.  

Тело ответа

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

{
    "@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, ... коллекции.
Пример ответа на POST-запрос
 
 
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

}
Пример ответа на GET-запрос
 
 
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)
Идентификатор удаляемого экземпляра объекта коллекции.
© Terrasoft 2002-2020.

Был ли данный материал полезен?

Как можно улучшить эту статью?