Веб-сервис odata (OData 4)

Сложный

PDF

В зависимости от используемого типа запроса протокол OData 4 возвращает различные данные.

/* Строка запроса. */
method Creatio_application_address/0/odata/objects_collection(object_id)/object_field?$parameters

/* Заголовки запроса. */
Accept: application/json
Content-Type: application/json; charset=utf-8; IEEE754Compatible=true
ForceUseSession: true
BPMCSRF: authentication_cookie_value

/* Тело запроса (используется в POST и PATCH запросах). */
{
    "field1": "value1",
    "field2": "value2",
    ...
}

/* Код состояния. */
Status: code

/* Тело ответа (присутствует в GET и POST запросах). */
{
    "@odata.context": "http://Creatio_application_address/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",
        ...
    },
    ...
    ]
}

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

method required

Методы запроса, которые поддерживает приложение Creatio:

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

Creatio_application_address required

Адрес приложения Creatio.

odata required

Адрес веб-сервиса протокола OData 4. Неизменяемая часть запроса.

objects_collection required

Имя таблицы базы данных (имя коллекции объектов). Чтобы получить перечень таблиц базы данных, выполните аутентификацию и один из запросов.

/* Получает результат в формате JSON. */
GET Creatio_application_address/0/odata/

/* Заголовки запроса. */
ForceUseSession: true
BPMCSRF: authentication_cookie_value

/* Получает результат в формате XML. */
GET Creatio_application_address/0/odata/$metadata

/* Заголовки запроса. */
ForceUseSession: true
BPMCSRF: authentication_cookie_value

/* Получает результат из таблицы [SysSchema] базы данных в формате JSON. */
GET Creatio_application_address/0/odata/SysSchema?$filter=ManagerName eq 'EntitySchemaManager'

/* Заголовки запроса. */
ForceUseSession: true
BPMCSRF: authentication_cookie_value

object_id optional

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

object_field optional

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

parameters optional

Необязательные параметры 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'	Фильтрация полей, которые должны попасть в выборку.

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

Accept application/json required

Тип данных, в котором ожидается ответ от сервера. Не обязательный к использованию в GET запросах.

Content-Type application/json; charset=utf-8; IEEE754Compatible=true required

Кодировка и тип ресурса, который передается в теле запроса. Не обязательный к использованию в GET запросах.

ForceUseSession true required

Принудительное использование существующей сессии.

BPMCSRF authentication_cookie_value required

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

Тело запроса

field1, field2, ... required

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

value1, value2, ... required

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

Коды состояний ответа

code

Код состояния ответа на запрос.

Возможные коды состояний

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 и содержимое не изменилось. Ответ не содержит другие заголовки.
403 Forbidden	Cервер понял запрос, но отказывается его авторизировать. Это означает, что клиент не уполномочен совершать операции с запрошенным ресурсом. Причиной может быть некорректная кука BPMCSRF. Может возникать при отсутствии CSRF-токена. Для исправления ошибки добавьте передачу куки BPMCSRF.
404 Not Found	Сервер не может найти ресурс, который указанй в URL-адресе. Дополнительная информация может содержаться в теле ответа.
405 Method Not Allowed	Ресурс, который указан в URL-адресе, не поддерживает указанный метод запроса. В ответе необходимо получить заголовок Allow, который содержит перечень доступных методов запроса для ресурса. Может возникать для PUT и DELETE запросов при включенном расширении WebDav HTTP. Для исправления ошибки отключите в IIS расширение WebDav HTTP.
406 Not Acceptable	Ресурс, который указан в URL-адресе запроса, не имеет текущего представления, которое подходит для клиента в соответствии с Accept, Accept-Charset и Accept-Language заголовками запроса. Служба не желает предоставлять представление по умолчанию.
410 Gone	Запрошенный ресурс больше недоступен. Ресурс раньше был по указанному URL, но теперь удален и недоступен.
412 Prediction Failed	Клиент указал в заголовке запроса условие, которое ресурс не может выполнить.
424 Failed Dependency	Текущий запрос к ресурсу невозможно выполнить, потому что запрошенное действие зависит от другого действия, выполнить которое не удалось. Запрос не выполнен через сбой зависимости.
501 Not Implemented	Клиент использует метод запроса, который не реализован протоколом OData 4 и этот метод невозможно обработать. Тело ответа содержит описание нереализованного функционала.

Тело ответа

@odata.context

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

value

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

[]

Коллекция объектов. Параметр присутствует только для GET запроса.

{}

Экземпляры объектов коллекции. Параметр присутствует только для GET и POST запросов.

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

Имена полей field1, field2, ... экземпляров объектов object1, object2, ... коллекции. Параметр присутствует только для GET и POST запросов.

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

Значения полей field1, field2, ... экземпляров объектов object1, object2, ... коллекции. Параметр присутствует только для GET и POST запросов.

Ресурсы

Creatio API документация

Официальная документация OData 4 (описание заголовков запроса)

Официальная документация OData 4 (описание параметров запроса)