Протокол открытых данных (OData) — это протокол доступа к данным, основанный на протоколе HTTP, и общепринятых методологиях, таких как REST для Интернета. Для использования сервисов OData можно использовать различные виды библиотек и инструментов.
Публичный API PLAN-R поддерживает протокол OData для получения данных через GET запросы и позволяет выбирать определенные поля данных, фильтровать и сортировать получаемые данные.
Для получения определенных полей в протоколе 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'
Протокол позволяет с помощью оператора 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'
Внимание! Для получения подробной информации об использовании протокола OData обратитесь к официальной документации Basic Tutorial.