OData: варианты работы и возможности стандартного интерфейса

Рассмотрим в этой статье варианты работы и возможности стандартного интерфейса OData с получением и обработкой данных информационной базы.

Общая информация

OData (Open Data Protocol) — это открытый веб-протокол для получения, изменения и удаления данных. OData позволяет пользователям работать с данными с через протокол HTTP в виде запросов. Данные получаются в виде ответов, в формате XML или JSON.
С помощью механизма пользователь может получить метаданные почти всех основных видов объектов и сами объекты с установленными фильтрами, в частности: документы, справочники, все виды регистров константы и т.п.. Также OData поддерживает возможности по загрузке и выгрузке данных, созданию новых элементов, проведению и отмене проведения документов, запуска бизнес процессов, выполнения задач, получения остатков и оборотов в регистрах и другое.

Настройка доступа

Для примера работы опубликуем информационную базу 1С на веб-сервере Apache HTTP Server с параметром «Публиковать стандартный интерфейс OData».
В нашем случае будет достаточно указать следующие параметры:
Имя – указываем наименование нашей публикации, для дальнейшего доступа по нему;
Веб-сервер – при правильной настройке Apache это поле заполнится само, но лучше проверить текущую версию и выбрать из предложенного списка;
Каталог – заполняем путь до каталога публикации. Заполняется только если веб-сервер установлен в данном ПК;
Публиковать стандартный интерфейс OData – устанавливаем галочку;

Последним шагом по настройке доступа через интерфейс OData следует перейти в обработку «Настройка автоматического REST-сервиса», которая позволяет:

⦁ Определить нового пользователя, который будет являться служебным и под которым будет вызываться интерфейс OData.
⦁ Определить весь состав объектов, которые будут доступны для получения через стандартный интерфейс OData.

Новый пользователь определяется на вкладке «Авторизация», где получает права, необходимые для использования интерфейса OData, а именно роль УдаленныйДоступOData. Основное отличие такого пользователя в том, что он не будет отображаться в привычном списке пользователей.

Настройка списка объектов, которые будут использоваться для доступа через OData, происходит на вкладке «Состав». При выборе конкретных объектов метаданных будет предложено включение других объектов метаданных, которые зависят от выбранного значения, их необходимо добавить в настройку, иначе указать состав будет невозможно.

Вводная информация

Общая структура запроса имеет следующий вид:

http://<имя сервера>:<порт>/<имя публикации>/odata/standard.odata/<имя ресурса><формат полученных данных>

где:
⦁ Имя сервера – расположение базы 1С (веб сервер или ip адрес)
⦁ Порт – порт веб-сервера, по умолчанию 80.
⦁ Имя публикации – имя указанное при публикации (в нашем случае Trade)
⦁ Признак обращения к OData – /odata/standard.odata
⦁ Имя ресурса – обращение к метаданным (пример в пункте 4);
⦁ Формат полученных данных – доступны «?$format=json» для формата json или «?$format=atom» для формата xml

Пример вызова:

localhost/Trade/odata/standard.odata/Catalog_Номенклатура?$format=json

Браузер запросит авторизацию:

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

Admin:ЗдесьМожноУказатьПароль@localhost/Trade/odata/standard.odata/Catalog_Номенклатура?$format=json

Полученные данные будут иметь следующий вид:

При обращении к ресурсу могут использоваться ключевые слова, имеющие специальное назначение:
⦁ $format – указывает формат получаемых данных, по умолчанию xml.
⦁ $format=atom – получение данных в формате xml.
⦁ $format=json – получение данных в формате json.
⦁ $metadata – указывает, что требуется получить описание стандартного интерфейса OData.
⦁ $filter – установка отборов на получаемые даные.
⦁ $select – перечисление через запятую свойств, которые получаются через стандартный интерфейс OData из объекта метаданных.

Также при обращении к ресурсам могут использоваться стандартные HTTP-методы:

⦁ GET – получение данных;
⦁ POST – создание объектов;
⦁ Обновление данных:
⦁ PATCH – для определенных свойств сущности;
⦁ PUT –для всех свойств сущности;
⦁ DELETE – удаление данных.

Правила получения доступа к ресурсам

Перед разбором примеров следует разобраться, как обозначаются объекты метаданных «1С: Предприятие» при написании запроса.

Обозначение в URL	Обозначение в URL
Catalog_имя	Справочники
Document_имя	Документы
DocumentJournal_имя	Журналы документов
Constant_имя	Константы
ExchangePlan_имя	Планы обменов
ChartOfAccounts_имя	Планы счетов
ChartOfCalculationTypes_имя	План видов расчета
ChartOfCharacteristicTypes_имя	План видов характеристик
InformationRegister_имя	Регистр сведений
AccumulationRegister_имя	Регистр накопления
CalculationRegister_имя	Регистр расчета
AccountingRegister_имя	Регистр бухгалтерии
BusinessProcess_имя	Бизнес процесс
Task_имя	Задача

В запросе OData:
⦁ строки указываются в одинарных кавычках (апострофах). Например: ’Конфеты’;
⦁ уникальные идентификаторы указываются как guid’строка’. Например: guid’27b04ad1-302f-45ed-b661-9f300183c9b1’;
⦁ даты указываются как datetime’yyyy-mm-ddThh:mm:ss’. Например: datetime’2024-10-03T12:30:59’.

После указания типа и имени объекта конфигурации может быть указан суффикс, начинающийся с символа подчеркивания:

Суффикс	Что означает
_имя-табличной-части	Обращение к табличной части объекта
_RowType	Обращение к строке табличной части объекта
_RecordType	Обращение к записи регистра

Пример:

⦁ Catalog_Организации(guid’c2c7fe20-dbde-41d1-9753-c74a0f23d4da’) – обращение к записи справочника Организации с указанным guid

⦁ InformationRegister_КурсыВалют(Period=’2024-02-20T00:00:00′,Валюта_Key=guid’7ba35875-8c6b-4d9d-8826-3b6ac165be5a’) – обращение к указанной записи регистра сведений Курсы валют

⦁ Catalog_Организации_КонтактнаяИнформация(LineNumber=3, Ref_Key=guid’7sa35875-8c6b-4d9d-8826-3b6ac165be5a) – обращение к строке 3 табличной части Контактная информация записи справочника Организации с указанным guid

Подробнее про методы, функции, операторы и т.п. можно изучить на официальном сайте ИТС (Здесь)

Примеры работы

В данном разделе мы пойдем от простого к сложному с небольшими комментариями и результатами выполнения запросов.

Получение элемента справочника

http://localhost/Trade/odata/standard.odata/Catalog_ Номенклатура?$format=json&$filter=Артикул eq 'Арт-980000'&$select=Description,Артикул,НаименованиеПолное

В данном примере мы получаем элементы справочника “Номенклатура” с заданным отбором по полю “Артикул” с помощью отбора $filter, а так же передаем в параметры поля, которые нам нужно получить с помощью $select.
Получен следующий результат:

Получим общее количество элементов справочника номенклатура:

http://localhost/Trade/odata/standard.odata/Catalog_ Номенклатура _Номенклатура/$count

Результат:

Получим элементы справочника, наименование которых содержит часть строки.

http://localhost/Trade/odata/standard.odata/Catalog_Номенклатура?$format=json&$filter=like(Descriptionэ,’%хар%')&$select=НаименованиеПолное,Артикул&$top=3

В данном примере мы задали отбор по наименованию с помощью функции like (строка, шаблон), которая возвращает true в случает, если строка содержит передаваемый параметр и работает по аналогии с ПОДОБНО() из языка запросов 1С. Так же мы выводим наименование и артикул в выбранных полях.

Результат запроса:

Также мы можем сортировать полученный список с помощью функции orderby. Для примера добавим в запрос поле код и отсортируем данный список по этому полю.

http://localhost/Trade/odata/standard.odata/ Catalog_Номенклатура?$format=json&$filter=like(Description,'%хар%')&$select=НаименованиеПолное,Артикул,Code&$top=3&$orderby=Code

Результат:

Работа с конкретными объектами

Далее рассмотрим отдельные объекты и работу с ними.

http://localhost/Trade/odata/standard.odata/ Catalog_Номенклатура(guid'f01bb2c2-427a-11dd-ac9e-0015e9b8c48d')?$format=json&$select=Description,Code

В данном запросе мы получаем конкретную номенклатуру по её уникальном идентификатору.
Результат:

Исправление объекта с помощью PATCH

Продемонстрируем работу HTTP-метода PATCH и для примера воспользуемся внешней обработкой 1С, в которой сформируем следующий запрос:

HTTPСоединение = Новый HTTPСоединение("localhost",80,"admin");
HTTPЗапрос = Новый HTTPЗапрос("/Trade/odata/standard.odata/Catalog_Номенклатура(guid'f01bb2c2-427a-11dd-ac9e-0015e9b8c48d')?$format=json");
ТелоИзменяемое=ЭлектроннаяПодписьВМоделиСервиса.СтруктураВJSON(Новый Структура("Code","123"));
HTTPЗапрос.УстановитьТелоИзСтроки(ТелоИзменяемое);
HTTPОтвет = HTTPСоединение.ВызватьHTTPМетод("PATCH",HTTPЗапрос);

В данном примере мы получаем объект, и устанавливаем ему в тело запроса структуру с именем реквизита, который мы хотим изменить. В результате мы получим следующий результат:

Создание объекта с помощью POST

Продемонстрируем работу HTTP-метода POST по созданию новых объектов и для примера так же воспользуемся внешней обработкой 1С, в которой сформируем следующий запрос:

HTTPСоединение = Новый HTTPСоединение("localhost",80,"admin");
HTTPЗапрос = Новый HTTPЗапрос("/Trade/odata/standard.odata/Catalog_Номенклатура?$format=json");
ТелоИзменяемое = ЭлектроннаяПодписьВМоделиСервиса.СтруктураВJSON(Новый Структура("Description,Code","Новая номенклатура","808"));
HTTPЗапрос.УстановитьТелоИзСтроки(ТелоИзменяемое);
HTTPОтвет = HTTPСоединение.ВызватьHTTPМетод("POST",HTTPЗапрос);

В результате работы данного метода будет создана новая номенклатура:

Удаление объектов с помощью DELETE

Продемонстрируем работу HTTP-метода DELETE по удалению объектов и для примера так же воспользуемся внешней

HTTPСоединение = Новый HTTPСоединение("localhost",80,"admin");
HTTPЗапрос = Новый HTTPЗапрос("/Trade/odata/standard.odata/Catalog_Номенклатура(guid'9d0a9713-818b-11ef-982d-080027b9bfa0')");
HTTPОтвет = HTTPСоединение.ВызватьHTTPМетод("DELETE",HTTPЗапрос);

Ответ на запрос будет с HTTP-кодом состояния 204 No content и пустым телом. При желании можно вывести в приложении форму справочника Номенклатура и убедиться, что запись удалена из справочника.

http://localhost/Trade/odata/standard.odata/ Catalog_Номенклатура?$format=json&$filter=Code eq '808'

Отмена проведения документов через POST

Рассмотрим методы POST() и UNPOST(), выполнив данный запрос мы получим документ реализации товаров и услуг, а затем посредством метода UNPOST() произведем отмену проведения:

http://localhost/Trade/odata/standard.odata/Document_РеализацияТоваровУслуг(guid'b45669a6-bad3-11ee-841c-af5642bc9f0d')/Unpost()

Результат:

Применим к данному объекту метод POST():

http://localhost/Trade/odata/standard.odata/Document_РеализацияТоваровУслуг(guid'b45669a6-bad3-11ee-841c-af5642bc9f0d')/Post()

Результат:

Срез последних из подчиненного регистра сведений

Рассмотрим пример чтения подчиненного регистра сведений «ЦеныНоменклатуры» (к имени регистра следует добавить _RecordType), получим срез последних:

http://localhost/Trade/odata/standard.odata/InformationRegister_ЦеныНоменклатуры_RecordType/SliceLast(Period=datetime'2022-09-30T00:00:00',Condition='Валюта/Description eq 'USD')?$format=json&$expand=Валюта,Номенклатура&$select=Номенклатура/Description,Цена,Валюта/Description,Period

В данном запросе мы получаем срез последних из регистра сведений «ЦеныНоменклатуры», с установленным периодом и наименованием валюты «USD», параллельно получая объекты «Валюта» и «Номенлатура», из которых мы так же получаем наименования. В конечном итоге получаем следующую выборку:

Вывод

Наглядно на примерах выяснили, как можно управлять объектами информационных баз 1С:Предприятие, а также рассмотрели методы и функции преобразования данных. Это лишь малая часть возможностей OData, существует множество различных методов, операций и функций для работы с данными.