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

Доступ к данным 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. 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С Предприятие» в строке доступа.

Важно помнить, что доступ к тем или иным объектам конфигурации ограничивается ролями, которые указаны у пользователя 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

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

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

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

  Функция	Описание	Пример
  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:

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

• С помощью навигационного свойства можно получить данные, хранящиеся в реквизите:
  • Для типа Картинка – будет получена собственно картинка с соответствующим значением 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>

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

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

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).