Работа с 1С через протокол OData

17.12.21

Интеграция - WEB-интеграция

В данной статье мы будем рассматривать работу с данными информационной базы через протокол OData (далее OData).
Для начала рассмотрим, что такое OData. Open Data Protocol или OData - это открытый веб-протокол для запроса и обновления данных. Протокол позволяет выполнять операции с ресурсами, используя в качестве запросов HTTP-команды, и получать ответы в форматах XML или JSON. (информация взята из статьи: https://ru.wikipedia.org/wiki/Open_Data_Protocol).

Доступ к данным 1С 8 через OData был реализован в платформе 1С 8.3.5. Пользователю предоставляется возможность получать структуру метаданных и сами объекты с установленными фильтрами, а именно:

  • планы обмена;
  • константы;
  • справочники;
  • документы;
  • журналы документов;
  • планы видов характеристик;
  • планы счетов;
  • планы видов расчета;
  • регистры сведений;
  • регистры накопления;
  • регистры расчётов;
  • регистры бухгалтерии;
  • бизнес-процессы;
  • задачи.

 

Данные возможности помогут для решения следующих задач:

  • получение данных без внесения изменений в конфигурацию;
  • получение данных в качестве альтернативы COM-connector (например, в ОС Linux);
  • удобство работы с данными базы из сайтов (организация личного кабинета клиента, интернет-магазин и т.п.);
  • загрузка и выгрузка данных;
  • создание новых объектов (элементы справочников, документы, записи регистров и т.п.);
  • выполнение задач и старт бизнес-процессов.

 

Организация доступа

Для начала работы необходимо опубликовать информационную базу 1С на web-сервере (Apache HTTP Server, Internet Information Services и т.п.). Рассмотрим подробнее:

  1. если у вас не установлен web-сервер, тогда устанавливаем или активируем один из серверов:
    1. Apache HTTP Server (подробнее - https://ru.wikipedia.org/wiki/Apache_HTTP_Server);
    2. Internet Information Services (подробнее - https://ru.wikipedia.org/wiki/Internet_Information_Services).

Обычно используется Apache (на данный момент июль 2021 рекомендуют использовать версию 2.4), т.к. данный сервер более надёжен и кросплатформенный (подходит для любой из популярных ОС: Windows, Linux). И ещё одна рекомендация: если web-сервер будет предназначен для внутреннего использования (локальная сеть), то можно использовать Apache HTTP, но если сервер будет опубликовать в Интернете или в общедоступной сети, то используйте безопасный сервер Apache HTTP +SSL;

2. теперь необходимо опубликовать работу с OData в конфигураторе нашей базы (помните, что совместимость базы должна быть выше или равна 8.3.5). Для этого открываем конфигуратор и выполняем «Администрирование – Публикация на веб-сервере…». Система сразу нас предупредит, что для выполнения подобной операции потребуются права администратора операционной системы, но мы можем сгенерировать нужный файл (default.vrd) и передать его пользователю с правами администратора ОС;

3. далее заполним нужные поля в открывшийся форме, а именно:

    1. имя – указываем имя нашей публикации (используем только латиницу без пробелов);
    2. веб-сервер – выбираем одно из значений (Apache 2.2, Internet Information Services);
    3. каталог – указываем путь к каталогу публикации (пример: C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs\). Если веб-сервер установлен не на данном ПК, тогда данное поле не заполняем;
    4. публиковать стандартный интерфейс OData - устанавливаем галочку;

организация доступа

4. теперь у нас есть два варианта публикации:

  1. веб-сервер установлен на данном ПК или каталог публикации доступен как сетевой каталог – нажимаем кнопку «Опубликовать» и далее следуем инструкциям по перезапуску сервера;
  2. веб-сервер не установлен на данном ПК или нет прав на изменения в каталоге публикации – нажимаем кнопку «Сохранить» и выбираем путь для сохранения файла «default.vrd», который потом нужно поместить в каталог на веб-сервер для публикации (так же следует учитывать, что веб-сервер должен иметь доступ к базе 1С);

5. и в завершении необходимо активизировать механизм OData для объектов метаданных базы (в типовых конфигурациях данная активация уже выполнена) для этого мы используем метод «УстановитьСоставСтандартногоИнтерфейсаOData», в который передаём массив объектов метаданных. Образец кода:

// создаём массив метаданных
Массив = Новый Массив;
Массив.Добавить(Метаданные.Справочники.Контрагенты);
Массив.Добавить(Метаданные.Справочники.Номенклатура);
// активируем 
УстановитьСоставСтандартногоИнтерфейсаOData(Массив);

Чтобы получить массив объектов метаданных, которые включены в стандартный OData, используем функцию:

ПолучитьСоставСтандартногоИнтерфейсаOData

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

Для тестирования работы протокола открываем любой доступный браузер и в адресной строке вводим url согласно шаблона:

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

где:

  • имя сервера – имя веб-сервера или его ip адрес, так же если веб-сервер установлен на ПК, где вы открыли браузер можно ввести localhost или 127.0.0.1 (например: http://localhost/ или http://server1c/);
  • порт – порт веб-сервера. Если используется стандартный порт 80, тогда можно не указывать порт (например: http://localhost/smallbusiness/);
  • имя публикации – имя, которое было указано при публикации в конфигураторе 1С 8 (например: smallbusiness);
  • имя ресурса – имя одного из получаемых ресурсов метаданных (справочники, документы, регистры и т.п.) с установленными фильтрами (например: Catalog_Номенклатура);
  • формат полученных данных – указываем «?$format=json» для формата json или «?$format=atom» для формата xml.

Пример:

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

Браузер должен вернуть:

 

Основы работы

Для начала нам необходимо освоить специальную терминологию для дальнейшего освоения работы OData. Будут использованы следующие термины:

  • Сущность – объект, который обладает уникальностью (аналог объектов в системе «1С Предприятие»). Сущность имеет набор свойств, по которым и можно определить её уникальность. Поиск объекта осуществляется по уникальному ключу.
  • Набор сущностей – коллекция сущностей определенного типа.
  • Составной тип – набор свойств, не обладающих идентичностью.
  • Функция - набор некоторых операций, выполняемых на стороне сервера, возвращающий данные (не обязательно сущность или набор сущностей) и не приводящий к наблюдаемым побочным эффектам (изменениям данных). Функция обязательно связана с сущностью или набором сущностей.
  • Действие – функция, которая изменяет данные.

Так же стоит отдельно стоит отдельно рассмотреть свойства сущности. Как уже понятно свойства сущности это реквизиты объектов «1С Предприятия». В некоторых случаях (например, реквизит объекта конфигурации составного типа) реквизит может быть представлен несколькими свойствами, одно из которых будет навигационным. Такое свойство содержит в качестве значения ссылку (URL) на сущность, описывающую объект «1С:Предприятия». Свойство, описывающее тип такого реквизита, называется диспетчеризационным. Название такого свойства завершается суффиксом _Type.

Для подключения к OData используем HTTP-запрос и URL, который будет состоять из следующих частей:

  • Адрес информационной базы;
  • Признак обращения к стандартному интерфейсу OData;
  • Имя ресурса, к которому выполняется обращение;
  • Параметры запроса обращения к ресурсу.

 

Теперь рассмотрим каждую из частей отдельно:

Адрес информационной базы.

Указываем имя, которое было указано во время публикации информационной базы (в примере – smallbusiness).

 

Признак обращения к стандартному интерфейсу OData.

Используем строку:

/odata/standard.odata

Имя ресурса, к которому выполняется обращение.

Указываем ресурс, по которому нужно получить или изменить данные. Так же можно ввести идентификатор ресурса (возможно с параметрами):

$metadata, Catalog_Контрагент(guid'value'

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

В качестве параметров обращения выступают параметры в виде, принятом для HTTP-запросов:

?ключ=значение&ключ2=значение2

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

  • $format – указывает, в каком формате необходимо получить данные. Если ключевое слово не указано, данные получаются в формате atom-xml.
    • $format=atom – возвращает данные в формате atom-xml.
    • $format=json – возвращает данные в формате json. Для указания того, что данные должны возвращаться в формате json, можно указать MIME-тип application/json в заголовке Accept HTTP-запроса на получение данных.
  • $metadata – указывает, что требуется получить описание стандартного интерфейса OData.
  • $filter – описывает отбор, применяемый при получении данных.
  • $select – описывает перечень свойств сущности, которые получаются при обращении к стандартному интерфейсу OData.

 

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

  • Получение данных – метод GET;
  • Создание объекта – метод POST;
  • Обновление данных:
    • метод PATCH – в этом случае можно указывать только те свойств, которые необходимо обновить;
    • метод PUT – в этом случае необходимо указывать все свойства сущности;
  • Удаление данных – метод DELETE.

В результате выполнения запроса клиентское приложение получает ответ сервера, который кроме кода состояния может содержать различные данные, предоставленные сервером, в виде XML-документа.

В примерах URL, которые используются в данном разделе, выражение guid'value' означает выражение OData, которое описывает конкретное значение GUID (тип Edm.Guid).

 

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

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

Объект конфигурации

Префикс имени в URL

Справочник

Catalog

Документ

Document

Журнал документов

DocumentJournal

Константа

Constant

План обмена

ExchangePlan

План счетов

ChartOfAccounts

План видов расчета

ChartOfCalculationTypes

План видов характеристик

ChartOfCharacteristicTypes

Регистр сведений

InformationRegister

Регистр накопления

AccumulationRegister

Регистр расчета

CalculationRegister

Регистр бухгалтерии

AccountingRegister

Бизнес-процесс

BusinessProcess

Задача

Task

 

Важно помнить, что доступ к тем или иным объектам конфигурации ограничивается ролями, которые указаны у пользователя 1С, под которым мы подключились к базе.

 Теперь, когда мы знаем, как обозначаются объекты «1С Предприятие» в URL можем разобрать сам URL.

 

Схема URL

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

, где

Префикс имени ресурса – указываем в соответствии с таблицей сопоставления объектов «1С Предприятия» и их представление в OData. Используется только латиница.

Имя объекта конфигурации – указываем имя объекта, так как оно указано в конфигурации (поле «Имя»). Если имя указано кириллицей, то в URL также указываем в кириллице.

Суффикс имени – указываем дополнительное описание имени объекта. Применяется для обозначения:

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

Например:

  1. доступ к справочнику «Организации» - Catalog_Организации;
  2. доступ к табличной части «Контактная информация» справочника «Физические лица» - Catalog_ФизическиеЛица_КонтактнаяИнформация;
  3. доступ к таблице срез последних регистра сведений «Цены номенклатуры» - InformationRegister_ЦеныНоменклатуры_СрезПоследних.

 

Установка отборов по ресурсам

То без чего не может обойтись не одна выборка данных – это отборы. , поэтому давайте рассмотрим какие отборы, мы можем указать в строке (URL). Можно выделить следующие отборы:

•	$filter;
•	$top;
•	$allowedOnly;
•	$skip;
•	$count;
•	$inlinecount;
•	$orderby.

Теперь рассмотрим каждый из них:

$filter

Для установки фильтров используется специальный язык, при помощи которого мы описываем применяемые фильтры в строке доступа к ресурсу.

Мы будем использовать следующие операции:

  • логические:

    Описание

    Имя

    Пример

    Равно

    eq

    /Catalog_Контрагенты?$filter=Имя eq ‘Иванов

    Не равно

    ne

    /Catalog_Контрагенты?$filter=Имя ne ‘Иванов

    Больше

    gt

    /Catalog_Контрагенты?$filter=Кредит gt 1000

    Больше или равно

    ge

    /Catalog_Контрагенты?$filter=Кредит ge 2300

    Меньше

    lt

    /Catalog_Контрагенты?$filter=Кредит lt 1000

    Меньше или равно

    le

    /Catalog_Контрагенты?$filter=Кредит le 1500

    Логическое «ИЛИ»

    or

    /Catalog_Контрагенты?$filter=Покупатель eq true or Прочее eq true

    Логическое «И»

    end

    /Catalog_Контрагенты?$filter=Покупатель eq true end Кредит gt 100

    Отрицание

    not

    /Catalog_Контрагенты?$filter=not  (Покупатель eq true)

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

    Описание

    Имя

    Пример

    Сложение

    add

    /Catalog_Контрагенты?$filter=Кредит add 100 gt 1000

    Вычитание

    sub

    /Catalog_Контрагенты?$filter=Кредит sub 15 lt 550

    Умножение

    mul

    /Catalog_Контрагенты?$filter=Кредит mul 2 gt 15000

    Деление

    div

    /Catalog_Контрагенты?$filter=Кредит div 5 lt 10

  • групповые:

    Описание

    Имя

    Пример

    Приоритет операции

    ()

    /Catalog_Контрагенты?$filter=(Кредит sub 15) lt 550

 

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

Операция

Описание

()

повышение приоритета операции

/

навигация

-

арифметическое отрицание

not

логическое отрицание

mul

умножение

div

деление

add

сложение

sub

вычетание

gt

больше

ge

больше или равно

lt

меньше

le

меньше или равно

eq

равно

ne

не равно

and

логическое «И»

or

логическое «ИЛИ»

 

Также мы можем применять функции для вычисления промежуточных данных: 

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

    Функция

    Описание

    Пример

    substringof(Str1, Str2)

    Возвращает true в том случае, если Str1 является подстрокой Str2.

    /Catalog_Товары?$filter=substringof('Красный Октябрь', Производитель) eq true

    endswith(Str1, Str2)

    Возвращает true в том случае, если Str1 заканчивается на Str2.

    /Catalog_Товары?$filter=endswith(Производитель, 'ООО') eq true

    startswith(Str1, Str2)

    Возвращает true в том случае, если Str1 начинается на Str2.

    /Catalog_Товары?$filter=startswith(Производитель, 'ООО') eq true

    substring(Str, Int1)

     

    substring(Str, Int1, Int2)

    Возвращает подстроку из Str1. В варианте с двумя параметрами возвращается строка с позиции Int и до конца строки.

     

    В варианте с тремя параметрами возвращается подстрока, начиная с позиции Int1 и длиной Int2.

    /Catalog_Поставщики?$filter=substring(ИНН, 1, 2) eq '77'

    concat(Str1, Str2)

    Возвращает строку, являющуюся результатом конкатенации Str1 и Str2.

    /Catalog_Поставщик?$filter=concat(concat(Город, ', '), Страна) eq 'Москва, Россия'

    like(Str, Template)

    Возвращает true, если значение Str1 удовлетворяет шаблону Template. Синтаксис шаблона аналогичен функции ПОДОБНО() языка запросов.

    /Catalog_Товары?$filter= like(Наименование, ‘[^к]%’)

  • функции для работы с датами:

    Функция

    Описание

    Пример

    year(DateTime)

       

     

    Возвращает год из значения типа Edm.DateTime или Edm.DateTimeOffset.

    /Catalog_Товары?$filter=year(Произведен) eq 2013

    quarter(DateTime)

       

     

    Номер квартала года, в котором находится указанное значение типа Edm.DateTime.

    /Catalog_Товары?$filter=quarter(ДатаПроизводства) eq 1

    month(DateTime)

       

     

    Возвращает месяц из значения типа Edm.DateTime или Edm.DateTimeOffset.

    /Catalog_Товары?$filter=month(Произведен) eq 12

    day(DateTime)

       

     

    Возвращает день из значения типа Edm.DateTime или Edm.DateTimeOffset.

    /Catalog_Товары?$filter=day(Произведен) eq 1

    hour(DateTime)

       

     

    Возвращает значение часов из значения типа Edm.DateTime или Edm.DateTimeOffset.

    /Catalog_Товары?$filter=hour(Произведен) eq 23

    minute(DateTime)

       

     

    Возвращает значение минут из значения типа Edm.DateTime или Edm.DateTimeOffset.

    /Catalog_Товары?$filter=minute(Произведен) eq 59

    second(DateTime)

       

     

    Возвращает значение секунд из значения типа Edm.DateTime или Edm.DateTimeOffset.

    /Catalog_Товары?$filter=second(Произведен) eq 59

    datedifference(DateTime1, DateTime2, Type)

    Возвращает разность дат DateTime2 и DateTime1 в единицах, указанных параметром Type:

    • second – секунды;
    • minute – минуты;
    • hour – часы;
    • day – дни;
    • month – месяцы;
    • quarter – кварталы;
    • year – года.

    /Catalog_Товары?$filter=datedifference(Произведен, ГоденДо, ‘day’) gt 10

    dateadd(DateTime1, Type, Int1)

    Возвращает дату, полученную добавлением к значению DateTime1 значения Int1, выраженное в единицах Type:

    • secondсекунды;
    • minuteминуты;
    • hourчасы;
    • dayдни;
    • monthмесяцы;
    • quarterкварталы;
    • year – года.

    /Catalog_Товары?$filter=dateadd(Произведен, ‘month’, 1) eq ГоденДо

    dayofweek(DateTime)

    Возвращает день недели по значению типа Edm.DateTime.

    /Catalog_Товары?$filter=dayofweek(ДатаПроизводства) eq 7

    dayofyear(DateTime)

    Возвращает день года по значению Edm.DateTime.

    /Catalog_Товары?$filter=dayofyear(ДатаПроизводства) eq 1

  • прочие функции:

    Функция

    Описание

    Пример

    round(Number)

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

    /Catalog_Товары?$filter=round(Вес) gt 31

    isof(expr, type)

    Возвращает true в том случае, когда объект, на который указывает параметр expr, имеет тип, на который ссылается type. В качестве типа значения принимается строка, обозначающая имя данного типа, например: String, Number, Boolean, Date, Catalog_Товары и т. д.

    /Catalog_Товары?$filter=isof(Цена, ‘Number’)

    cast(expr, type)

    Возвращает объект, на который указывает параметр expr, приведенный к типу, указанному параметром type. В качестве типа значения принимается строка, обозначающая имя данного типа, например: String, Number, Boolean, Date, Catalog_Товары и т. д.

    /Catalog_Товары?$filter= cast(РеквизитСоставной, 'Number') le 12

Примечание: Не поддерживаются операции сравнения с реквизитом типа ХранилищеЗначения.

Имеется возможность выполнять отбор сущностей при помощи проверки на равенство поля составного типа и ссылки. Для этого следует использовать функцию cast(). Пример:

$filter=ДокументПрихода eq cast(guid'0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7', 'Document_ПриходнаяНакладная')

В данном примере у используемой сущности имеет реквизит составного типа ДокументПрихода. Запрос будет отбирать все записи сущности, у которой данный реквизит заполнен ссылкой на документ ПриходнаяНакладная с указанным уникальным идентификатором (0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7).

Если требуется выполнить отбор по реквизиту типа УникальныйИдентификатор, то это выполняется с помощью простой операции сравнения. Пример:

$filter=ИмяРеквизита eq guid'0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7'

Для отбора по типу какого-либо реквизита составного типа следует использовать функцию isof(). Пример:

$filter=isof(ДокументыПрихода, 'Document_ПриходнаяНакладная')

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

$filter=ДокументыПрихода eq guid'0d4a79cb-9843-4147-bcd9-80ac3ca2b9c7'

 

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

Система поддерживает использование следующих лямбда-функций:

  • any – применяет логическое выражение к каждому элементу коллекции и возвращает значение true, если хоть один элемент коллекции удовлетворяет этому условию. Лямбда-функция any без аргументов возвращает true, если коллекция не пуста. Пример:

http://host/base/odata/standard.odata/Document_Продажи?$filter=Товары/any(d: d/Цена gt 10000)

В приведенном примере формируется список документов Продажи, у которых есть табличная часть Товары, в которой есть реквизит Цена. При этом Цена должна быть больше, чем 10000. В результирующий список попадут документы, в состав которых входит хотя бы одна строка, удовлетворяющая условию.

  • all – применяет логическое выражение к каждому элементу коллекции и возвращает значение true, если все элементы коллекции ему удовлетворяет. Пример:

http://host/base/odata/standard.odata/Document_Продажи?$filter=Товары/any(d: d/Цена lt 10000)

В приведенном примере формируется список документов Продажи, у которых есть табличная часть Товары, в которой есть реквизит Цена. При этом Цена должна быть меньше, чем 10000. В результирующий список попадут документы, в составе которых все строки удовлетворяют заданному условию.

Не поддерживаются следующие стандартные функции: lenght, indexof, replace, tolower, toupper, trim, years, days, hours, seconds, floor, ceiling.

$top

Имеется возможность ограничить количество записей, возвращаемых при обращении к ресурсу. Для этого используется параметр $top. Пример:

http://host/odata/standard.odata/Catalog_Товары?$filter=Цена lt 1000&$top=10

 

$allowedOnly

Если при выполнении запроса необходимо получить только те объекты данных, которые не попадают под ограничения доступа к данным, то в URL получения данных необходимо добавить параметр $allowedOnly. Пример:

http://host/base/odata/standard.odata/Catalog_Товары?allowedOnly=true

Если параметр не указан или указан со значением false, то во время исполнения запроса к данным может возникнуть ошибка с кодом 401 (если результат выполнения запроса содержит данные, доступ к которым запрещен). Ошибка может не произойти в том случае, если были указаны дополнительные условия, которые ограничили выборку только разрешенными данными.

Например, для справочника Данные настроено ограничение доступа к данным, которое не позволяет получить элементы справочника, у которых реквизит ЗначениеСекретности равно 1, но позволяет получить элементы справочника, у которых реквизит ЗначениеСекретности равно 2. В этом случае следующий запрос не приведет к возникновению ошибки, т. к. явно накладывается условие, которое оставляет в выборе только разрешенные данные. Пример:

http://host/base/odata/standard.odata/Catalog_Данные?allowedOnly=false&$filter=ЗначениеСекретности eq 2

Параметр $allowedOnly можно использовать только для GET-запросов к наборам сущностей.

 

$skip

Позволяет исключить из результата запроса первые несколько записей. Если параметры $top и $skip указываются одновременно, то параметр $skip будет применен раньше, чем параметр $top. Приоритет применения параметров не зависит от порядка их указания в теле запроса. Пример:

http://host/base/odata/standard.odata/Catalog_Товары?$skip=2

 

$count

Данный параметр позволяет получить в качестве результата запроса не выборку, а ее (выборки) размер. При успешном выполнении, тело ответа должно содержать только число элементов коллекции, отформатированное как обычное число. Пример:

// возвращает количество элементов справочника Товары,
// для которых справедливо условие: значение реквизита Цена больше 500
http://host/base/odata/standard.odata/Catalog_Товары/$count?$filter=Цена gt 500

 

$inlinecount

Параметр позволяет указать, что система должна включить результат запроса не только полученные записи, но и количество этих записей. Для этого необходимо указывать значение параметра $inlinecount, равное allpages. Использование параметра $inlinecount со значением none подавляет возвращение количества записей вместе с результатом запроса. Если параметр $inlinecount не указан в теле запроса, то количество записей вместе с результатом запроса не возвращается. Использование параметра $inlinecount приводит к игнорированию параметров $skip и $top. Допускается совместное использование параметров $filter и $inlinecount. Пример:

http://host/base/odata/standard.odata/Catalog_Товары?$inlinecount=allpages

Пример результата запроса, с параметром $inlinecount=allpages:

Формат atom-xml:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns=http://www.w3.org/2005/Atom xmlns:at=http://purl.org/atompub/tombstones/1.0 xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices xmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/metadata xml:base="http://localhost/ODataTests/odata/standard.odata/">
    <entry>
        …
    </entry>
        …
    <entry>
        …
    </entry>
    <m:count>19</m:count>
</feed>

Формат json:

{
    "odata.metadata": "http://localhost/ODataTests/odata/standard.odata/$metadata#Document_ДемоДокумент",
    "odata.count": "19",
    "value": [{...}, ..., {...}]
}

 

$orderby

Данный параметр позволяет задать упорядочивание результата запроса. Значение параметра $orderby содержит список реквизитов, разделенных запятыми. Значение реквизита может включать направление упорядочивания:

  • asc – для упорядочивания по возрастанию;
  • desc – для упорядочивания по убыванию.

Направление упорядочивания должно быть отделено от имени реквизита на 1 и более пробелов. Если asc или desc не указан, то считается, что требуется упорядочивание по возрастанию. Пример:

http://host/base/odata/standard.odata/Catalog_Товары?$orderby=Название asc, Производитель desc

Допускается упорядочивание по свойствам дочерних реквизитов. В этом случае полное имя реквизита, по которому выполняется упорядочивание, формируется с использованием разделителя "/". Пример:

http://host/base/odata/standard.odata/Document_Расход?$orderby=Контрагент/ИНН asc

В этом примере упорядочивание будет произведено по возрастанию (asc) значения реквизита ИНН у сущности, на которую ссылается реквизит Контрагент документа Расход.

 

Получение данных

OData предоставляет запрашиваемые данные в виде JSON или XML документа (смотря, что вы указали в параметре запроса $format).

Давайте рассмотрим таблицу соответствия типов «1С Предприятия» и OData:

Тип «1С Предприятия»

Тип свойства OData

Строка

Edm.String

Дата

Edm.DateTime

Число (целое)

Edm.Int16, Edm.Int32, Edm.Int64

Число (дробное)

Edm.Double

Булево

Edm.Boolean

Ссылка

Edm.Guid

Перечисление

Edm.String

Хранилище значения

Состоит из трех свойств*:

  1. Навигационное свойство;
  2. <Имя свойства>_Base64Data;
  3. <Имя свойства>_Type.

Ссылочный тип

Два свойства:

  1. Собственно значение ссылки на объект типа Edm.Guid;
  2. Навигационное свойство.

Составные типы

Два свойства типа Edm.String:

  1. Значение фактического типа, выраженное в виде строки;
  2. Имя фактического типа.

 

В таблице символ * означает, что:

  • С помощью навигационного свойства можно получить данные, хранящиеся в реквизите:
    • Для типа Картинка – будет получена собственно картинка с соответствующим значением HTTP-заголовка content-type;
    • Для типа ДвоичныеДанные – будет получен байтовый поток;
    • Для остальных типов – XDTO-сериализованное значение хранимых данных.
  • Свойство <Имя свойства>_Base64Data хранит данные, которые могут быть получены с помощью навигационного свойства, только закодированные в Base64. Редактировать данные реквизита типа ХранилищеЗначения можно только с помощью этого свойства.
  • Свойство <Имя свойства>_Type описывает тип данных, хранимых в реквизите. Может принимать одно и трех значений:
    • application/octet-stream – двоичные данные;
    • application/xml+xdto – XDTO-сериализованный объект;
    • значение HTTP-заголовка content-type, соответствующего картинке, хранящейся в реквизите, например, image/jpeg для картинки формата JPEG.

Остальные типы не поддерживаются, и при попытке их чтения будет сгенерирована ошибка c кодом 501.

Имена свойств могут оканчиваться на различные суффиксы, а именно:

  • Key;
  • Type;
  • Base64Data.

Теперь рассмотрим подробнее данные суффиксы:

Key

Данный суффикс содержит значение ключа ссылки (GUID) реквизита объекта или независимого регистра сведений без измерений. Для установки отбора по имени реквизита можно использовать данный суффикс, а именно: для установки отбора по ссылочному полю Номенклатура, условие будет выглядеть следующим образом: Номенклатура _Key=guid'value'. При этом свойство Номенклатура будет содержать представление номенклатуры с указанным значением ссылки.

Type

Данный суффикс используется для описания реквизита составного типа. Так, если в данных есть поле составного типа Номенклатура, то в документе, который возвращает стандартный интерфейс OData, этому полю будет соответствовать два свойства:

  • Номенклатура _Type – будет содержать описание типа значения реквизита в виде строки (тип Edm.String, диспетчеризационное свойство);
  • Номенклатура – будет содержать значение реквизита (соответствующего типа).

Перечень допустимых типов, которые могут быть использованы в поле с таким суффиксом, определяется схемой сервиса, который можно получить при запросе полного описания стандартного интерфейса OData. Таким образом, при необходимости установить тип Документ.РасходнаяНакладная, в элемент с суффиксом _Type должно быть записано значение StandardODATA.Document_ РасходнаяНакладная.

Если значение реквизита составного типа в информационной базе «1С:Предприятия» имеет значение Неопределенно, то диспетчеризационное свойство будет иметь значение StandardODATA.Undefined, а само значение свойства должно игнорироваться.

Пример представления реквизита составного типа:

<d:РеквизитСоставной/>
<d:РеквизитСоставной_Type>StandardODATA.Undefined</d:РеквизитСоставной_Type>

Base64Data

Данный суффикс используется при указании имени свойства, содержащего данные, расположенные в реквизите типа ХранилищеЗначения, в виде строки Base64. Так, если в объекте конфигурации есть реквизит Файл, который имеет тип ХранилищеЗначения, то в документе, который возвращает стандартный интерфейс OData, этому полю будет соответствовать два свойства:

  • Файл_Type – содержит наименование типа данных, хранимых реквизитом;
  • Файл_Base64Data – содержит строку Base64, содержащую сами данные.

 

Коды ошибок

В случае ошибочной ситуации возвращается ответ с HTTP-статусом 4XX или 5XX. Статус 4XX информирует об ошибках на стороне клиентского приложения, статус 5XX информирует об ошибке на стороне сервера.

В случае статуса 4XX сервер пытается уточнить причину ошибки и может передать клиентскому приложению дополнительный внутренний код ошибки и информационное сообщение (в виде xml-документа) в теле ответа. Пример:

<m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
    <m:code>9</m:code>
    <m:message>Экземпляр сущности "НакладнаяОтгрузки" не найден по переданному ключу.</m:message>
</m:error>

Далее перечислены внутренние коды ошибок с описанием причины появления:

Код

Описание

0

Возможность не поддерживается

1

Не удалось разобрать строку

2

Неверный формат запроса

3

Запрошенный тип представления не поддерживается

4

Неверное значение свойства

5

Отсутствует обязательное значение свойства

6

Неверный URL

7

Не хватает элемента ключа сущности

8

Тип сущности не найден

9

Экземпляр сущности не найден

10

Запрошенное свойство не найдено

11

Метод не найден

12

Отсутствует обязательный аргумент метода

13

Создание строк табличных частей напрямую не поддерживается

14

Ошибка разбора опций запроса

15

Сущность с таким ключом уже существует

16

Не удалось присвоить свойство

17

Объект не поддерживает режим загрузки данных

18

Ошибка инициализации интерфейса OData: в объекте есть свойства с одинаковыми именами

19

Использованный HTTP-метод запрещен в данном контексте

20

Ошибка прав доступа. Может возникать:

  • Когда у пользователя нет прав на запрошенное действие над данным объектом;
  • Когда в выборку попадает объект, недоступный в связи с ограничением доступа к данным и параметр allowedOnly не используется.

21

Вызов нереализованной функции.

 

Указание неверного количества аргументов функции.

 

Попытка передачи аргумента неверного типа.

 

Указание нереализованной лямбда-функции.

 

 

 

Используемые материалы и статьи:

  1. 1С: ИТС Стандартный интерфейс OData (https://its.1c.ru/db/v838doc#bookmark:dev:TI000001360);
  2. 42clouds.com: Интерфейс OData: возможности и настройка (https://42clouds.com/ru-ru/techdocs/interfeys-odata-vozmozhnosti-i-nastroyka.html).

протокол OData

См. также

WEB-интеграция Платформа 1С v8.3 1С:ERP Управление предприятием 2 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х 1С:Управление нашей фирмой 3.0 1С:Розница 3.0 Россия Платные (руб)

Функциональное решение для торговли на всех популярных маркетплейсах. Работает со схемами FBO и FBS. Простое в использовании и установке, не вносит изменения в код программы. Существенно упрощает работу с товарным ассортиментом, обработку заказов с площадок, работу с поставками, а также ведение аналитики по продажам и остаткам.

72000 руб.

19.07.2024    1321    52    0    

3

WEB-интеграция Программист Платформа 1С v8.3 Бухгалтерский учет 1С:Бухгалтерия 3.0 Бытовые услуги, сервис Платные (руб)

Внешняя обработка разрабатывалась для загрузки документов из Ветменеджер в 1С: Бухгалтерия 3.0

12000 руб.

02.02.2021    17718    49    50    

29

WEB-интеграция 8.3.8 Конфигурации 1cv8 Автомобили, автосервисы Беларусь Украина Россия Казахстан Управленческий учет Платные (руб)

Расширение предназначено для конфигурации "1С:Предприятие 8. Управление Автотранспортом. ПРОФ". Функционал модуля: 1. Заполнение регистров сведений по подсистеме "Мониторинг", а именно: события по мониторингу, координаты по мониторингу, пробег и расход по мониторингу, текущее местоположение ТС по мониторингу 2. Заполнение путевого листа: пробег по мониторингу, время выезда/заезда, табличная часть ГСМ, места стоянок по геозонам. 3. Отчеты по данным загруженным в регистры сведений. 4. Предусмотрена автоматическая загрузка данных в фоновом режиме (условия работы данной загрузке читайте в описании товара) Модуль работает без включенной константы по настройкам мониторинга. Модуль формы предоставляется с открытым кодом, общий модуль защищен. Любой заинтересованный пользователь, имеет возможность скачать демо-версию расширения.

22656 руб.

25.05.2021    14118    40    8    

16

Обмен с ГосИС Мастера заполнения WEB-интеграция Бухгалтер Пользователь Платформа 1С v8.3 Бухгалтерский учет Оперативный учет Управляемые формы 1С:Управление производственным предприятием 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Россия Платные (руб)

Универсальное расширение конфигурации для автоматической загрузки и заполнения реквизитов контрагентов (партнеров) из ОГРН для 1С:ERP Управление предприятием 2 (1С:ERP Управление предприятием 2, редакция 2.4), 1С:ERP Управление предприятием 2 (1С:ERP Управление предприятием 2, редакция 2.2), 1С:Управление торговлей 8 (Управление торговлей, редакция 11.5), 1С:Управление торговлей 8 (Управление торговлей, редакция 11.4), 1С:Управление торговлей 8 (Управление торговлей, редакция 11.3), 1С:Управление торговлей 8 (Управление торговлей, редакция 11.2), 1С:Комплексная автоматизация 8 (1С:Комплексная автоматизация, редакция 2.4), 1С:Комплексная автоматизация 8 (1С:Комплексная автоматизация, редакция 2.2), 1С:Комплексная автоматизация 8 (1С:Комплексная автоматизация, редакция 2.0) и 1С:Бухгалтерия 8 (Бухгалтерия предприятия, редакция 3.0).

3900 руб.

08.11.2017    62871    403    295    

72

ККМ WEB-интеграция Программист Пользователь Платформа 1С v8.3 Конфигурации 1cv8 Платные (руб)

Универсальный драйвер для фискализации чеков для сервиса Бизнес.РУ. Чеки (https://online-check.business.ru/). Работает с любой кассой, подключенной к сервису, в том числе и без физической кассы (Аренда облачной ККТ в датацентре). Принцип работы аналогичен наличию физической кассы, подключенной к рабочему месту 1С. Фискализация выполняется с любого рабочего места через интернет. Нет ограничений на количество рабочих мест, касс, компьютеров. Поддерживает печать с нескольких рабочих мест на одну кассу. Работает в любой операционной системе (Windows, Linux) и в любом клиенте (Тонкий, Толстый, Web, Мобильный клиент).

6000 руб.

03.06.2021    13813    12    0    

8
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. TyurinArt 97 17.12.21 08:00 Сейчас в теме
(0) Добавьте описание параметра "expand" и получение дескрипшена из реквизита составного типа виртуальной таблицы остатков регистра бухгалтерии. Пример: /AccountingRegister_Хозрасчетный/Balance(AccountCondition='Account_Key eq guid'5ded89b1-bc5a-11e6-a484-50e549b168f5')?$expand=ExtDimension1_Type/Catalog_Номенклатура/Description
2. Sedaiko 587 17.12.21 09:52 Сейчас в теме
Давно плюнул на OData, т.к. сейчас запилить расширение с http-сервисом, возвращающим xml или json, плевое дело.
oData, по моему опыту, юзают "распальцованые" разработчики других систем, которым понты не позволяют у 1С-разработчика заказать нужный API.
До кучи, помощью oData могут повесить всю систему, фактически выполняя множество мелких запросов в цикле.
God_loki; ziercool; alexander-lubich; Sergafan10; mip128; Revachol; triviumfan; bulpi; Yashazz; +9 1 Ответить
3. Aletar 17.12.21 10:10 Сейчас в теме
(2) Это же инструмент, который нужно использовать правильно, по максимуму используя плюсы технологии и нивелируя минусы. Понятно, что для всего подряд OData использовать неправильно. Но, например, я хочу сделать дашборд на специально подготовленном для этого регистре сведений с примитивными типами данных. Почему бы тут не использовать OData? Думаю те кто использует, могут ещё примеры набросать.
24. Zomich 18.01.23 14:14 Сейчас в теме
(2)
Можете дать пару ссылок на информацию о http сервисах? Я просто новичок в этом деле.
26. Khamatnurov 02.02.23 13:07 Сейчас в теме
25. Zomich 18.01.23 14:19 Сейчас в теме
(2)
http-

Можете дать пару ссылок на информацию о http сервисах?
4. Дмитрий74Чел 238 17.12.21 10:18 Сейчас в теме
Мне кажется или это копипаста ИТС? https://its.1c.ru/db/v8320doc#bookmark:dev:TI000001757
SagittariusA; coollerinc; Irwin; Artem-B; a.gorbachev; ats333; Drivingblind; ardn; mip128; dabu-dabu; dmpas; ixijixi; mrChOP93; reset2; Dementor; +15 Ответить
5. Dementor 1033 17.12.21 10:41 Сейчас в теме
(4) согласен. До боли знакомые куски текста )))))
6. reset2 17 17.12.21 10:44 Сейчас в теме
7. Yashazz 4779 17.12.21 14:06 Сейчас в теме
(4) Модераторы же пропустили. Значит типа можно. Теперь на ИС типа всё можно.
8. bulpi 217 17.12.21 14:42 Сейчас в теме
Плюс поставил, но сама технология производит впечатление УГ.
9. aspirator23 339 17.12.21 15:33 Сейчас в теме
Можно в ODATA установить отбор по массиву?
В запросе это когда в условии указано "....Где Справочник.Номенлатура.Ссылка в (&Товары)..." ?
11. Ujine1313 10 17.12.21 16:03 Сейчас в теме
(9)Фильтр устанавливается через логическое OR
?$filter=Номенклатура_Key eq guid'770860f9f-7df8-11e9-80d5-309c23cfab98'or'Номенклатура_Key'eq'guid'9f1e127a-7dfb-11e9-80d5-309c23cfab98'
10. ilnur75 17.12.21 15:49 Сейчас в теме
а можете привести пример как используя оДата написать верную строку запроса с "ПОДОБНО" ?
12. booksfill 17.12.21 17:56 Сейчас в теме
Спасибо за полезную информацию.

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

Чтобы не разводить холивар на тему "а зачем это вам столько записей", давайте ограничимся ошибкой программиста, ну, скажем РHP.

Повиснет процесс, вылетит сеанс, произойдет ошибка на стороне Apache, ничего не случится и будет неспеша работать, забьется сетка, и т.п.?

И еще, я правильно понимаю, что при ошибке каких-то внятных сообщений не будет, например,
"Не задан параметр запроса" - останется скрыт в недрах 1C?
Angealtor; +1 Ответить
13. rusmil 262 17.12.21 18:20 Сейчас в теме
Возникло несколько вопросов, кто знает прошу ответить.

1. Требуется ли как-то авторизоваться и указать логин и пароль перед получением данных из 1С через OData в браузере?

2. При получении данных браузером через OData расходуются лицензии 1С или нет?
14. malikov_pro 1329 19.12.21 23:04 Сейчас в теме
(13)
1. Basic аутентификация
2. Думаю аналогично HTTP сервисам, технически сейчас не расходуются, но в лиц соглашении прописано что для всех пользователей нужны лицензии.
15. Asmody 20.12.21 10:30 Сейчас в теме
Если бы автор адекватно расписал как обращаться к виртуальным таблицам регистров, включая описание всех параметров и их правильную установку, - цены бы не было.
А ИТС мы и без инфостарты почитать могем.
SagittariusA; khvolkova; ats333; Дмитрий74Чел; Dimisi; v_ustyuzhanin; ardn; +7 Ответить
16. Ujine1313 10 20.12.21 22:21 Сейчас в теме
Толи я криворукий то ли что то поменялось в ODATA - развернул УТ 11.5 опубликовал рядом с 11.4
11.4 все ок
11.5
http://localhost/UT/odata/standard.odata/
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xml:base="http://localhost/BP/odata/standard.odata">
<workspace>
<atom:title>Default</atom:title>
</workspace>
</service>


Попробовал то же самое на новой БП - результат то же отрицательный.
17. Ujine1313 10 21.12.21 19:48 Сейчас в теме
(16)Надо было опубликовать данные в базе. Администрированием - ODATA
18. samvani 35 08.01.22 00:07 Сейчас в теме
(16) посмотрите метод УстановитьСоставСтандартногоИнтерфейсаOData. Нужно передать массив с метаданными, которые хотите использовать в odata на стороне УТ
19. ВасяЧ 11.01.22 12:34 Сейчас в теме
На платформе 8.3.17.1851 не работает экранирование апострофа методом повторения

Запрос с фильтром ?$filter=Писатели_Name eq 'О''Генри' отбросит "Генри"
20. user1402638 01.09.22 17:50 Сейчас в теме
Возможно пропустил, но так и не нашел интересующую меня информацию.
Запрашиваю для вывода в json элемент справочника (сущность). Через указание GUID все работает.
Запрос: "/odata/standard.odata/Catalog_Номенклатура(guid'3def3bb1-2952-11ed-b572-002683324b06')?$format=application/json"
Но мне нужно получить не по GUID а по Коду элемента. Известен именно Код.
Запрос: "/odata/standard.odata/Catalog_Номенклатура?$filter=Code eq'000000011'&$format=application/json" выводит справочник с отбором по коду (набор сущностей), а не элемент. Элемент там внутри как составная часть справочника. В файле это выглядит как:
{
"odata.metadata": "http://localhost/start/odata/standard.odata/$metadata#Catalog_Номенклатура",
"value": [{
"Ref_Key": "3def3bb1-2952-11ed-b572-002684524b06",
а мне нужно:

{
"odata.metadata": "http://localhost/start/odata/standard.odata/$metadata#Catalog_Номенклатура/@Element",
"Ref_Key": "3def3bb1-2952-11ed-b572-002684524b06",
21. atolegen 27.09.22 14:53 Сейчас в теме
Мне надо сделать отчет по документу

Можно получит данный про документа через Одата и потом во Вложный запросу сделать отчет ?

за ранее Спс!
22. avbolshakov 21.12.22 11:20 Сейчас в теме
Добрый день! Нужен совет - мне нужно между двумя базами 1С настроить обмен, но не всех документов, а точечно. При проведении самописного документа в одной базе - создавать документ в другой. Стоит ли использовать механизм oData для этого? я не вижу каких-то препон для этого.
НСИ обмен планирую все равно делать через типовой обмен по расписанию. В вот точечно документы создать хотел бы через одату чтобы не править типовой обмен
23. user1009940 16.01.23 15:28 Сейчас в теме
Добрый день!
Обновили конфу, и перестал работать сервис oData. Пишет техническая ошибка. В 1С в ЖР только записи авторизации и все. Может кто сталкивался с таким? Куда копать?
27. lev6975 15.05.23 12:10 Сейчас в теме
По пункту 5 можно поподробнее?
ГДЕ эту функцию прописывать?
В каком модуле?
28. user617822_tahir868 17.07.23 13:22 Сейчас в теме
Всем добрый день.
При обращении (odata) к остаткам регистра бухгалтерии (на дату) не попадает документ, у которого время 23:59:59.
Обычным запросом тоже самое не видит, но если в дату передать границу времени, все проходит хорошо. Как можно передать границу времени в запросе по odata.
29. Неопределено 91 17.05.24 05:17 Сейчас в теме
Логическое "И" — and. End — это "конец".
30. Shurkec 03.06.24 16:51 Сейчас в теме
Для чего придумали этот OData лично мне непонятно. Ну какие-то простые запросы он может и делает. Но вот стоит только попробовать сделать на нем более-менее сложный обмен - ничего не работает. А главное - нет абсолютно никакой информации как нужно делать! Например:
1. Создание документов в базе-приемнике. Они почему-то сразу проводятся (если документ был проведен в базе-источнике). Причем проведены они без движений по регистрам.
2. Ок, пробуем тогда передать данные по регистрам. Например по регистрам, которые подчинены регистратору (т.е. передаваемому документы). И опять облом. И вроде заполняется всё что надо. А может и не всё, но где про это почитать??? Нигде!
Мёртвый и бесполезный функционал.
user785225; +1 Ответить
31. user785225 17 25.06.24 11:18 Сейчас в теме
У кого-нибудь есть реализация получения данных "В иерархии" напр. по элементам справочника,
или даже по записям регистра где измерение "В иерархии"?
32. eufes 24.09.24 20:00 Сейчас в теме
До сего дня тоже думал, что по сути не очень нужная вещь. Однако появилась задача запрашивать некоторые остатки из различных баз корреспондентов, которые являются партнерами и тиражировать на них всех какую-то доработку или какое-то расширение (и поддерживать потом) дело унылое.
А тут вроде как малой кровью можно обойтись. Особливо если интеграция простая
Оставьте свое сообщение