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

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

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

Смотреть на

Настройка API-пользователя для работы с OData

Внимание! Для работы с OData необходимо выделить пользователя Business Studio (далее - API-пользователь), который не используется для работы в веб-интерфейсе, так как после генерации API-ключа авторизация под этим пользователем в веб-интерфейсе будет невозможна.

Для настройки API-пользователя:

Выберите пользователя Business Studio (можно использовать существующего или создать нового), который будет использоваться для работы с OData.
Сгенерируйте для этого пользователя API-ключ.

Генерация API-ключа

Генерация для пользователя API-ключа производится в веб-интерфейсе Business Studio для каждой базы данных, с которой будет работать API-пользователь, для этого:

Откройте веб-интерфейс Business Studio под пользователем, у которого в категории вертикальных прав установлено разрешение на выполнение действия “Скопировать ключ API пользователя в буфер обмена” в классе “Пользователи” (см. Права пользователя).
Откройте справочник “Пользователи”.
Откройте свойства пользователя, который выбран для работы с OData.
В заголовке Области свойств откройте гамбургер-меню и выберите пункт “Скопировать ключ API пользователя в буфер обмена”.

В результате описанных действий:

Выбранный пользователь переводится в API-режим.
В буфер обмена копируется ключ, который необходимо использовать для авторизации при обращении к ODATA.

Авторизация и обращение к ODATA

При обращении к ODATA нужно указывать:

ключ API:
- название ключа - X-API-Key,
- значение - сгенерированный ключ пользователя (см. Генерация API-ключа выше);
название и ветку базы данных в заголовке https:
- названия ключей - dbalias и branch,
- значения - название базы и ветки соответственно.

На примере Postman (https://www.postman.com/) на рисунках 1 и 2 показаны поля ввода этих параметров.

Рисунок 1. Параметры авторизации в Postman.

Рисунок 2. Параметры названия базы и ветки в Postman.

Методы запроса

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

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

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

В URL запроса необходимо указывать адрес сервера (далее в примерах: адрес_сервера) и путь к сервису ODATA.

GET – получение данных

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

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

POST – создание данных

Пример. Добавление нового объекта «Иванов Иван Иванович» в справочник «Физические лица» (AppPlatform.Person):

адрес_сервера/API/v1/OData/AppPlatform.Person

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

Рисунок 3.

В теле ответа возвращается созданный объект:

{"@odata.id":
"адрес_сервера/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": "Иванович"
}

PATCH – обновление данных

Пример. Изменение наименования объекта (Name) на «Иванов Иван Александрович» в справочнике «Физические лица» (AppPlatform.Person) у ранее добавленного «Иванов Иван Иванович»:

адрес_сервера/API/v1/OData/AppPlatform.Person%%('0x0010140000000000000000000000000000000000000000000000000000003D')

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

Рисунок 4.

DELETE – удаление данных

Пример. Удаление объекта физлица «Иванов Иван Александрович»:

адрес_сервера/API/v1/OData/AppPlatform.Person('0x0010140000000000000000000000000000000000000000000000000000003D')

Рисунок 5.

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

¹⁾

FirstName), aggregate($count as FNCount, Icon with sum as TotalIcon

²⁾

Patronymic), aggregate($count as FNCount, Icon with sum as TotalIcon