Работа с данными через протокол OData

OData (Open Data Protocol) — это открытый веб-протокол для получения, добавления, удаления и обновления данных. OData позволяет выполнять операции с данными с помощью HTTP-запросов и получать ответы в формате JSON (подробнее о веб-протоколе и запросах можно ознакомиться тут https://www.odata.org/getting-started/). Доступ к данным посредством OData можно использовать, например:

• для загрузки и выгрузки данных;
• для интеграции со сторонними информационными системами.

Для включения OData в Bussiness Studio нужно включить опцию у пользователя, от которого будет запущено приложение, обслуживающее работу протокола. Настройка OData задается опцией «Разрешено использование OLE/OData» (Главное меню - Настройки пользователя - вкладка Дополнительно). При включенной опции запущенная БС будет обслуживать запросы OData. Задать номер порта можно используя ключ /port=НомерПорта в командной строке запуска приложения.

Внимание! В запросах используются системные названия справочников и параметров, которые можно посмотреть в Объектной модели в Business Studio или в MetaEdit.

Метод запроса выбирается в зависимости от того, какая операция выполняется.

Для тестирования команд можно использовать Postman (https://www.postman.com/).

Для get запросов можно использовать следующие параметры: $select, $expand, $filter, $orderby, $skip, $top, $apply.
Примеры:

1. Получение списка объектов справочника «Физические лица» (здесь и далее в скобках указывается системное название, в данном случае - AppPlatform.Person):
   http://localhost:9000/API/v1/OData/AppPlatform.Person
2. Получение данных конкретного объекта из справочника «Физические лица» (AppPlatform.Person):
   http://localhost:9000/API/v1/OData/AppPlatform.Person('0x00101400000000000000000000000000000000000000000000000000000001')
3. Выбор нужных не объектных полей Название (Name) и Дата рождения (DateOfBirth) из справочника «Физические лица» (AppPlatform.Person):
   http://localhost:9000/API/v1/OData/AppPlatform.Person?$select=Name,DateOfBirth
4. Выбор нужных объектных полей из справочника «Физические лица» (AppPlatform.Person) Contacts:
   http://localhost:9000/API/v1/OData/AppPlatform.Person?$expand=Contacts
5. Установка фильтра, условие для поля Название (Name) справочника «Физические лица» (AppPlatform.Person):
   http://localhost:9000/API/v1/OData/AppPlatform.Person?$filter=Name eq 'Бабич Ирина Петровна'
6. Комбинация условий, вложенные условия с конкретными значениями в поле Название (Name) (наличие сочетания букв 'евна'):
   http://localhost:9000/API/v1/OData/AppPlatform.Person?$filter=(endswith(Name,'евна') or Name eq 'Бабич Ирина Петровна')and startswith(Name,'М')&$select=Name
7. Фильтр Физических лиц (AppPlatform.Person) по дате рождения, рожденных не ранее 1970 года:
   http://localhost:9000/API/v1/OData/AppPlatform.Person?$filter=DateOfBirth gt%201970-01-01T00:00:00Z&$select=Name,DateOfBirth
8. Фильтр по перечислению контактов с типом Email:
   http://localhost:9000/API/v1/OData/AppPlatform.PersonContact?$filter=ContactType/Category eq ns.AppPlatform.ContactCategories'Email'
9. Сортировка результатов запроса имен по убыванию:
   http://localhost:9000/API/v1/OData/AppPlatform.Person?$orderby=Name desc
   Поддерживается сортировка по числам, текстовым полям, датам.
10. Если требуется пропустить две записи и выдать не более шести записей можно воспользоваться подобным запросом:
    http://localhost:9000/API/v1/OData/AppPlatform.Person?$select=Name&$skip=2&$top=6
11. Агрегация данных.
    Сгруппировать Физические лица (AppPlatform.Person) по именам, вывести число физлиц с именем и сумму по полю Icon: http://localhost:9000/API/v1/OData/AppPlatform.Person?$apply=groupby((FirstName), aggregate($count as FNCount, Icon with sum as TotalIcon))
    Сгруппировать физлица (AppPlatform.Person) по отчествам (Patronymic), оканчивающимся на "ович":
    http://localhost:9000/API/v1/OData/AppPlatform.Person?$apply=filter(endswith(Patronymic,'ович'))/groupby((Patronymic), aggregate($count as FNCount, Icon with sum as TotalIcon))

Пример:

1. Добавление нового объекта «Иванов Иван Иванович» в справочник «Физические лица» (AppPlatform.Person):
   POST http://localhost:9000/API/v1/OData/AppPlatform.Person
   

В теле запроса в JSON указываются поля для заполнения нового объекта:

Рисунок 1. В теле ответа возвращается созданный объект

{"@odata.id":
"http://localhost:9000/API/v1/OData/AppPlatform.Person('0x0010140000000000000000000000000000000000000000000000000000003D')",
"ID": "0x0010140000000000000000000000000000000000000000000000000000003D",
"ID_Parent": "0x00101400000000000000000000000000000000000000000000000000000000",
"LastName": "Иванов",
"Name": "Иванов Иван Иванович",
"OwnerSID": "dwEFAAAAAAAFFQAAAO26+HsXMtOVLBHtYz4GAAA=",
"FirstName": "Иван",
"InternalAuditor": false,
"ACL": null,
"guid": "da3f29c0-1f0c-4eb3-becc-7a8d93a75746",
"Patronymic": "Иванович"
}

Пример:

1. Изменение наименования объекта (Name) на «Иванов Иван Александрович» в справочнике «Физические лица» (AppPlatform.Person) у ранее добавленного «Иванов Иван Иванович»:
   PATCH http://localhost:9000/API/v1/OData/AppPlatform.Person('0x0010140000000000000000000000000000000000000000000000000000003D')
   

В теле запроса в JSON указываются поля, которые нужно изменить в объекте.

Пример:

1. Удаление объекта физлица «Иванов Иван Александрович»:
   DELETE http://localhost:9000/API/v1/OData/AppPlatform.Person('0x0010140000000000000000000000000000000000000000000000000000003D')
   

В результате возвращается серверное сообщение «204 no content» и объект удаляется, либо появляется текст ошибки в теле ответа.