REST интерфейс OData в 1C

ODataВ технологической платформе версии 8.3.5 была реализована возможность автоматически формировать REST интерфейс OData для всего прикладного решения. Таким образом у нас появилась возможность предоставить полный доступ стороннему приложению к базе 1С буквально за пару кликов.

Данный механизм предназначен для решения нескольких часто встречающихся задач:

  • Выгрузка/загрузка данных в/из прикладного решения;
  • Интеграция с интернет-сайтами (интернет-магазинами);
  • Наращивание функциональности прикладного решения без изменения конфигурации;
  • Интеграция с другими корпоративными системами (иногда и без дополнительного программирования).

REST интерфейс OData можно использовать для обмена данными между базами 1С, но так как для этого уже существуют другие, более удобные, механизмы, то основное предназначение REST интерфейса OData видится в интеграции со сторонними системами.

И это действительно удобно, если учесть, что клиенты OData существуют на всех основных платформах, соответствующие библиотеки можно скачать тут.

В этой статья я попробую подробно рассказать о том, что такое REST интерфейс OData и как его можно использовать.

Публикация REST интерфейса OData

Для использования интерфейса OData его нужно опубликовать, а для этого нам потребуется веб-сервер — Apache 2.2 или IIS (начиная с версии платформы 8.3.8 еще и Apache 2.4). Затем, нужно зайти в меню «Администрирование»->»Публикация на веб-сервере…».

В открывшемся окне заполняем нужные поля и жмем «Опубликовать»:

Публикация интерфейса OData
Публикация интерфейса OData

После этого нужно будет определить состав интерфейса OData, т.е. указать — какие объекты конфигурации в него входят, а какие нет (изначально в составе нет ни одного объекта).

Сделать это можно примерно так:

На Инфостарте есть отличная обработка на эту тему.

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

Все, стандартный интерфейс OData настроен, запущен и ожидает клиентских подключений.

Пример использования

Для различных операций используются различные HTTP-методы:

  • Получение данных — GET;
  • Создание объектов — POST;
  • Обновление данных — PATCH/PUT (в зависимости от того, сколько свойств объекта нужно обновить);
  • Удаление данных — DELETE.

Проверить состав стандартного интерфейса можно, получив описание этого самого интерфейса при помощи браузера:

http://localhost/HTTPTest/odata/standard.odata/$metadata

Результат:

Описание интерфейса OData
Описание интерфейса OData

Для проверки получения данных,  введем вот такой запрос:

http://localhost/HTTPTest/odata/standard.odata/Catalog_Товары?$format=json

где:

  • HTTPTest — имя при публикации;
  • odata/standard.odata/ — обязательная часть, признак обращения к интерфейсу OData;
  • Catalog_Товары — имя ресурса сформированное по правилу (об этом чуть ниже);
  • ?$format=json — необязательный параметр обращения к ресурсу.

Результат выполнения запроса выглядит так:

Результат выполнения запроса
Результат выполнения запроса

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

Имя ресурса формируется по следующему правилу:

ПрефиксИмени_ИмяОбъектаКонфигурации_СуффиксИмени.

С помощью стандартного  интерфейса OData можно получить доступ к следующим объектам (ПрефиксИмени):

  • Справочник — Catalog;
  • Документ — Document;
  • Журнал документов — DocumentJournal;
  • Константа — Constant;
  • План обмена — ExchangePlan;
  • План счетов — ChartOfAccounts
  • План видов расчета — ChartOfCalculationTypes;
  • План видов характеристик — ChartOfCharacteristicTypes;
  • Регистр сведений — InformationRegister;
  • Регистр накопления — AccumulationRegister;
  • Регистр расчета — CalculationRegister;
  • Регистр бухгалтерии — AccountingRegister;
  • Бизнес-процесс — BusinessProcess;
  • Задача — Task.

ИмяОбъектаКонфигурации — свойство «Имя» объекта конфигурации так, как оно задано в конфигураторе.

СуффиксИмени — нужен для уточнения имени ресурса, необязателен, может принимать следующие значения:

  • Имя табличной части объекта;
  • Имя виртуальной таблицы объекта;
  • RowType — строка табличной части объекта;
  • RecordType — отдельная запись регистра.

Параметры обращения к ресурсам

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

  • $format — указывает формат возвращаемых данных, вариантов два:
    • $format=atom — данные в формате atom-xml;
    • $format=json — данные в формате json;
  • $metadata — возвращает описание стандартного интерфейса OData (используется без указания суффикса имени, пример на одном из изображений выше);
  • $filter — отбор при получении данных (более подробно ниже);
  • $select — перечисление свойств сущности, которые попадут в результат запроса;
  • $top — ограничение количества возвращаемых записей (8.3.8.1652);
  • $skip — убирает из результата запроса указанное количество записей (8.3.8.1652);
  • $count — возвращает количество записей в выборке запроса (8.3.8.1652);
  • $inlinecount=allpage(=none) — добавляет в результат запроса информацию о количестве записей (8.3.8.1652);
  • $orderby=<Реквизит1> asc, <Реквизит2> desc — сортировка результата запроса (8.3.8.1652);
  • alloweOnly — только разрешенные (используется без знака «$»).

Арифметические и логические операции

Для задания отбора параметром $filter могут быть использованы следующие операции, логические:

  • eq — Равно; /Catalog_Города?$filter=Наименование eq ‘Главный’;
  • ne — Не равно; /Catalog_Города?$filter=Наименование ne ‘Пермь’;
  • gt — Больше; /Catalog_Товары?$filter=Цена gt 10;
  • ge — Больше или равно; /Catalog_Товары?$filter=Цена ge 10;
  • lt — Меньше; /Catalog_Товары?$filter=Цена lt 10;
  • le — Меньше или равно; /Catalog_Товары?$filter=Цена le 10;
  • or — Логическое ИЛИ; /Catalog_Товары?$filter=Цена lt 10 or Цена gt 100;
  • and — Логическое И; /Catalog_Товары?$filter=Цена gt 10 and Цена lt 100;
  • not — Отрицание; /Catalog_Товары?$filter=not (Цена eq 10);

и арифметические:

  • add — Сложение; /Catalog_Товары?$filter=Цена add 5 gt 10;
  • sub — Вычитание; /Catalog_Товары?$filter=Цена sub 5 gt 10;
  • mul — Умножение; /Catalog_Товары?$filter=Цена mul 5 gt 1000;
  • div — Деление; /Catalog_Товары?$filter=Цена div 4 gt 2;

Кроме этого, для обозначения приоритета операции могут использоваться «скобки».

Формируя условия отбора важно не забывать о том, что логические и арифметические операции имеют разный приоритет, при этом операции с одинаковым приоритетом исполняются слева направо. Ниже приведен список логических и арифметических операций в порядке уменьшения приоритета:

  • ( ) — повышение приоритета операции;
  • / — навигация;
  • «-» — арифметическое отрицание;
  • not — логическое отрицание;
  • mul — умножение;
  • div — деление;
  • add — сложение;
  • sub -вычитание;
  • gt — больше;
  • ge — больше или равно;
  • lt — меньше;
  • le — меньше или равно;
  • eq — равно;
  • ne — не равно;
  • and — логическое «И»;
  • or — логическое «ИЛИ».

Функции

При формировании условий запроса (filter) или формировании реквизита по которому выполняется сортировка (orderby) могут применяться следующие функции. Все функции доступны только начиная с релиза 8.3.8.1652.

Строковые функции:

Строковые функции
Строковые функции

Функции работы с датами:

Функции работы с датами
Функции работы с датами

Прочие функции:

Прочие функции
Прочие функции

Коды ошибок

При возникновении ошибочных ситуаций возвращается ответ с HTTP-статусом 4XX или 5XX. Статус 5XX означает ошибку на стороне сервера (само собой исправлять эту ошибку нужно тоже на сервере), а вот статус 4XX означает ошибку на нашей, клиентской, стороне и в ряде случаев вместе со статусом может быть предан код ошибки и информационное сообщение. Ниже перечислены внутренние коды ошибок и их описание:

Коды ошибок
Коды ошибок

На этом все, обзор основных моментов использования технологии OData в 1С завершен. Надеюсь что данный материал Вам помог.

Оставить комментарий