ПОДДЕРЖКА ПРОТОКОЛА ODATA

Что такое OData

Протокол открытых данных (OData) — это протокол доступа к данным, основанный на протоколе HTTP, и общепринятых методологиях, таких как REST для Интернета. Для использования сервисов OData можно использовать различные виды библиотек и инструментов.

Публичный API PLAN-R частично поддерживает протокол OData v.4.0 для получения данных через GET запросы и позволяет выбирать определенные поля данных, фильтровать и сортировать получаемые данные.

Поддерживаемые операторы

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

  • filter - Фильтрация получаемых значений. Можно использовать операторы сравнения, логические операторы и комбинировать выражения с помощью скобок:
    • eq (равно) - filter=type eq 'project';
    • ne (не равно) - filter=type ne 'version';
    • gt (больше чем) - filter=createAt gt '2021-01-01';
    • ge (больше чем или равно) - filter=createAt ge '2021-01-01';
    • lt (меньше чем) - filter=updateAt lt '2022-04-04';
    • le (меньше чем или равно) - filter=updateAt le '2022-04-04';
    • and (логическое 'и') - filter=(type eq 'project') and (createAt ge '2021-01-01');
    • or (логическое 'или') - filter=(date ge '2021-01-01') or (isApproval ne null)
    • not (отрицание): filter=versionStatus not isActive
  • select - Получить только указанные поля;
  • orderby - Упорядочить полученные значения по указанному полю. Для указания порядка сортировки используются операторы asc и desc;
    • asc - Упорядочить по возрастанию (используется по умолчанию);
    • desc - Упорядочить по убыванию;
  • apply - Использовать расширение для агрегации получаемых данных:
    • aggregate - Агрегация получаемых данных;
    • groupby - Группировка получаемых данных;
  • skip - Пропускает первые N результатов.
  • top - Возвращает только первые N результатов.

Кастомные функции

В публичном API реализованы собственные функции расширяющие возможности протокола OData:

  • getById - Возвращает строковое значение атрибута по его идентификатору (getById('Коллекция значений', 'Идентификатор атрибута') => строковое значение атрибута). Функция предназначена для получения значений атрибутов ИСР, значений справочников и значений справочников ИСР;
  • number - Преобразовывает строковое значение в число (number('5') => 5);
  • boolean - Преобразовывает строковое значение в логическое (boolean('true') => true);

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

Для получения определенных полей в протоколе OData используется оператор select, позволяющий указать перечень полей, которые пользователь хочет с помощью API.

Пример: Получить список узлов СПП, для узлов получить только идентификатор, имя и тип узла.

curl -X 'GET' \
  'https://your-org.domain/public-api/eps?select=type,name,id' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Пример: Получить список узлов ИСР где значение атрибута с идентификатором равным 624b6a37-f6a0-40a5-a2e1-4f2e6724167b равно Hotel building.

curl -X 'GET' \
  'https://your-org.domain/public-api/wbs?epsId=70d6cb44-00e9-4535-9949-2d5596f0988a&filter=getById(values, '624b6a37-f6a0-40a5-a2e1-4f2e6724167b') eq 'Hotel building'' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 507' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Пример: Получить список узлов ИСР где значение атрибута с идентификатором равным 624b6a37-f6a0-40a5-a2e1-4f2e6724167b больше 10.

curl -X 'GET' \
  'https://your-org.domain/public-api/wbs?epsId=70d6cb44-00e9-4535-9949-2d5596f0988a&filter=number(getById(values, '624b6a37-f6a0-40a5-a2e1-4f2e6724167b')) gt 10' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 507' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Фильтрация данных

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

Пример: Получить список узлов СПП типа project, для узлов получить только идентификатор, имя и тип узла.

curl -X 'GET' \
  ''https://your-org.domain/public-api/eps?select=type,name,id & filter=type eq 'project''' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Сортировка данных

Сортировка данных осуществляется с помощью оператора orderby, возможна сортировка как по возрастанию с использованием модификатора ASC (по умолчанию), так и по убыванию с использованием модификатора DESC.

Пример: Получить список узлов СПП типа project, где имя проекта начинается с "Ст", для узлов получить только идентификатор, имя и тип узла. Упорядочить по полю sortOrder

curl -X 'GET' \
  ''https://your-org.domain/public-api/eps?select=type,name,id & filter=type eq 'project' and startsWith(name, 'Ст') & orderby=sortOrder desc '' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Пагинация данных

При запросе данных сервер отдаёт не более 100 записей, подходящих под условия выборки. Пагинация получаемых данных осуществляется с помощью операторов top и skip. Оператор skip позволяет пропустить указанное количество записей, оператор top позволяет указать количество возвращаемых записей.

Пример: Упорядочить СПП по полю sortOrder и получить два узла, подходящие под условия выборки, пропустив первые четыре.

curl -X 'GET' \
  'https://your-org.domain/public-api/eps?orderby=sortOrder desc & $top=2 & $skip=4' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Пример: Получить количество элементов СПП.

curl -X 'GET' \
  'https://your-org.domain/public-api/eps?apply=aggregate($count as eps_count)' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Пример: Получить количество элементов СПП типа version.

curl -X 'GET' \
  'https://your-org.domain/public-api/eps?apply=filter(Type eq 'version')/aggregate($count as eps_count)' \
  -H 'accept: application/json;odata.metadata=minimal;odata.streaming=true' \
  -H 'x-version: 409' \
  -H 'Authorization: your-api-key' \
  -H 'x-tenant-id: 5db13376-ba5c-4fd5-ba7f-dc56347956ad'

Внимание!

Для получения подробной информации об использовании протокола OData обратитесь к официальной документации Basic Tutorial. Для получения подробной информации об использовании протокола OData для агрегации данных, обратитесь к документации OData Extension for Data Aggregation Version 4.0.

Аутентификация

Ограничения

509.1-59ba7826