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

 

В технологической платформе версии 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С завершен. Надеюсь что данный материал Вам помог.

Если Вы нашли ошибку или неточность, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.

Оценка статьи:
УжасноПлохоНеплохоХорошоОтлично (оценок: 16, средняя оценка: 5,00 из 5)
Загрузка...

Понравилась статья? Поделиться с друзьями:
Комментарии: 17
  1. Yaroslav Solntsev

    А мы сделали первую версию Генератора Запросов OData в виде веб-сервиса. Пользуйтесь бесплатно. Публикуйте Базу, загружайте структуру таблиц и в полученном дереве генерите запросы Odata

    1. Алексей

      Где можно посмотреть?

      1. Yaroslav

        Тут.
        http://gen.bi-team.ru/GQ
        Извините, давно не заходил сюда.
        Правда нужна еще обработочка на вашей стороне, которая структуру ваших метаданных поместит в этот сервис и можете работать.

        1. Петр

          по данному адресу открывается 1с в окне браузера, требует ввести имя пользователя и пароль.

  2. Максим

    Очень полезный материал. Спасибо. Добавил страничку в закладки:)

  3. Максим

    А как мне записать что то в 1С с помощью Java никак пример нормальный найти не могу:(

  4. Дмитрий

    Доброго дня! Может кто-нибудь подскажет, почему OData для одинакоывых установок и конфигураций возвращает разный список metadata?

    1. Вячеслав

      Зависит от списка объектов, для которых был разрешен доступ через интерфейс OData. Состав объектов изменяется процедурой УстановитьСоставСтандартногоИнтерфейсаOData()

  5. Александр

    Доброго дня! Читаю вашу статью как хорошее объяснение метода доступа данных к сервисам. Постоянно использую в качестве справочника.
    Сам тоже хочу добавить маленькую фишку сюда тоже: при добавлении «____Presentation» к ссылочным полям можно получить их строковое представление.
    Кстати, а кто знает где найти полную доку по возможеостям OData в сервисах 1С?

    1. Добрый день. Спасибо за участие. Наиболее подробную и полную информацию можно найти на сайте ИТС, например. Там, конечно, требуется подписка, но, если мне не изменяет память, имеется возможность получить бесплатный семидневный доступ.

  6. Олег

    Здравствуйте.
    подскажите пожалуйста кто в курсе — как используя OData добавить цены товара и количество (т.е. добавить его на склад)? если можно пример запроса урл и xml.
    добавлять категории и сами и товары и редактировать их через OData получается без проблем — а вот с ценами беда. пробовал наугад добавлять через /InformationRegister_ЦеныНоменклатуры и /Document_УстановкаЦенНоменклатуры и /Document_УстановкаЦенНоменклатуры_Товары но везде получаю ответ 400 — хотя урл корректный. Нагуглить ничего не удалось по данной проблеме.

  7. гулью

    ;-) ;-) ;-) ;-)

  8. Ccc

    alloweOnly — только разрешенные (используется без знака «$»).

    Опечатка. Должно быть allowedOnly

    1. Ccc

      $inlinecount=allpage(=none)

      Тоже опечатка, должно быть allpages

  9. Ян

    Подскажите, а можно через OData получить версию конфигурации?

  10. Олег

    Для изменения константы надо использовать метод PATH. Строка запроса — http://ИмяСервера/ИмяБазы/odata/standard.odata/Constant_ИспользоватьДатуЗапрета(guid'00000000-0000-0000-0000-000000000000‘)?$format=json Тело запроса — {«Value»:false}

  11. Акром

    Здраствуйте! Можно получить данные одновременно от 2 или 3 объектов?
    Например, ссылки от справочник и цены от регистр сведений…

Добавить комментарий

;-) :| :x :twisted: :smile: :shock: :sad: :roll: :razz: :oops: :o :mrgreen: :lol: :idea: :grin: :evil: :cry: :cool: :arrow: :???: :?: :!:

Сообщить об опечатке

Текст, который будет отправлен нашим редакторам: