Интерфейс OData: возможности и настройка

Для баз данных, размещенных в сервисе Платформа42, включена поддержка автоматического REST-сервиса по протоколу OData версии 3.0.

OData — это открытый веб-протокол для запроса и обновления данных. Он позволяет оперировать данными, используя в качестве запросов HTTP-команды.

• Платформа автоматически генерирует REST интерфейс, не нужно никакого программирования;
• Прозрачная интеграция прикладного решения с интернет-сайтами, мобильными приложениями и прочими системами;
• Реализация сторонними средствами дополнительной функциональности без изменения конфигурации;
• Загрузка данных в прикладное решение и выгрузка данных из него;
• Управление составом объектов метаданных, доступных через стандартный сервис OData API на лету;
• Ограничения прав доступа пользователей также действительны для запросов OData;
• Универсальность и кроссплатформенность.

Настройка OData

Для настройки интерфейса в разделе Администрирование → Синхронизация данных перейдите по ссылке Настройки стандартного интерфейса OData, для того чтобы произвести настройки автоматического REST-сервиса для запроса и обновления данных.

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

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

На вкладке Авторизация включите флажок Создать для использования автоматического REST-сервиса отдельные имя пользователя и пароль (рекомендуется).

Напишите Имя пользователя, Пароль и Подтверждение пароля. Нажмите кнопку Сохранить.

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

На вкладке Состав можно определить, какие данные будут участвовать в работе автоматического REST-сервиса. По умолчанию список пуст.

Нажмите кнопку Загрузить метаданные, для того чтобы отобразить данные программы.

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

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

Общие принципы работы

При работе с протоколом OData используется специальная терминология.

При применении протокола используются следующие термины:

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

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

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

• $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-документа.

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

• Тип УникальныйИдентификатор (тип Edm.Guid) указывается как guid’value’. Например: guid’8d04ce3c-6360-11e9-dd92-fa163e8ba11d’.
• Тип Дата (тип Edm.DateTime) указывается как datetime’yyyy-mm-ddThh:mm:ss’. Например: datetime’1945-05-09T06:00:00’.

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

Данные, возвращаемые стандартным интерфейсом OData, могут быть представлены в виде XML-документа или JSON-документа. Это зависит от того, в каком формате запрашиваются данные.

Для различных типов данных используется следующее соответствие между типом «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;
• ____Presentation.

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

Поля представлений не включаются в результаты запроса с пустым параметром $select и при указании в параметре $select значений * и **. Таким образом, если необходимо получить все реквизиты объекта и представления некоторых реквизитов, необходимо указать значение *, а затем отдельно перечислить поля представлений требуемых реквизитов, разделяя их запятыми: $select=*, РеквизитСсылка____Presentation.

Для получения представлений всех реквизитов объекта, следует в параметре $select указать значение *____Presentation: $select=*____Presentation.

Для получения значений всех полей и представлений для всех полей, следует использовать следующее выражение: $select=*, *____Presentation.

Для получения представления текущей сущности имеется возможность указывать в списке запрашиваемых полей поле Presentation: $select=Ref_Key, Presentation. В этом случае будет получено значение ссылки и представление этой ссылки.

Поля представлений не содержатся в описании метаданных, которое возвращается в описании стандартного интерфейса OData (параметр $metadata). Получение представления не поддерживается для табличных частей и реквизитов типа ХранилищеЗначения. Не поддерживается модификация значений для полей представлений.

Правила формирования имени ресурса

При обращении к какому-либо ресурсу, его идентификатор формируется по следующему принципу:

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

ИмяОбъектаКонфигурации - свойство Имя объекта конфигурации, как оно задано при разработке прикладного решения в конфигураторе.

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

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

Правила формирования условия отбора

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

В данном разделе приводится информация по различным способам формирования отбора получаемых данных, используемых в стандартном интерфейсе OData системы «1С:Предприятие».

Описание возможностей отбора в протоколе OData можно получить в документации по протоколу (на английском языке):

• http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol/ раздел 10.2.3.1;
• http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol/ раздел 5.1.2.

$filter

При получении данных можно фильтровать данные. Для этого предназначен специальный язык, который позволяет описывать условия, каким должны соответствовать данные, которые возвращает стандартный интерфейс OData. Описание отбора начинается с ключевого слова $filter, после которого следует собственно условие. Поддерживаются следующие операции:

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

https:/host/base/zone/odata/standard.odata/Catalog_Товары?$filter=Имя eq 'Молоко' and Цена lt 2500

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

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

ПРИМЕЧАНИЕ. Не поддерживаются операции сравнения с реквизитом типа ХранилищеЗначения.

Имеется возможность выполнять отбор сущностей при помощи проверки на равенство поля составного типа и ссылки. Для этого следует использовать функцию 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, если коллекция не пуста.

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

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

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

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

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

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

Например, имеется документ МаршрутныйЛист, который содержит реквизит составного типа ОснованиеОтгрузки. Данный реквизит может принимать значения типа ДокументСсылка.Накладная и ДокументСсылка.ВнутреннееПеремещение. При этом у документа Накладная существует реквизит МестоОтгрузки, который может принимать значения типа СправочникСсылка.Склад и СправочникСсылка.АдресаОтгрузки.

В том случае, если необходимо отобрать документы МаршрутныйЛист с условием по названию склада, указанного в накладной (т.е. по реквизиту Название объекта типа СправочникСсылка.Склад, записанного в реквизит МестоОтгрузки документа Накладная), то условие должно выглядеть следующим образом:

cast(cast(ОснованиеОтгрузки, 'Document_Накладная')/МестоОтгрузки, 'Catalog_Склад')/Название eq 'Основной в Москве'

Не поддерживаются следующие стандартные функции: 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.

Пример:

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

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

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

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

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

$skip

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

Пример:

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

Параметры запроса

$count

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

Пример:

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

$inlinecount

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

Пример:

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

Пример результата запроса, с параметром $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://host/ODataTests/odata/standard.odata/">
					<entry>
					…
					</entry>
					…
					<entry>
					…
					</entry>
					<m:count>19</m:count>
					</feed>
				

$orderby

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

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

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

Пример:

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

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

Пример:

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

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

$expand

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

Значением параметра выступает список из навигационных ссылок или составных реквизитов (если составные реквизиты могут принимать ссылочное значение), разделенных запятыми. Для расширения реквизитов составных реквизитов, после имени составного реквизита должно идти название типа, на который может хранить ссылку составной реквизит, а уже после этого сам расширяемый реквизит. Тогда, если у сущности составной реквизит имеет ссылку на объект указанного типа, то в нем будет расширен указанный реквизит. Если же значение является ссылкой на объект иного типа или не является ссылкой, то расширение проводиться не будет.

Возможно использование опции для расширения сущностей из результатов функций SliceLast() и SliceFirst().

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Сертификат

Для каждого элемента из справочника Клиенты, в результат запроса должен быть помещен объект, на который ссылается реквизит Сертификат.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/Document_ДоговорНайма/Заявление
				

Для каждого элемента из справочника Клиенты, в результат запроса должен быть добавлен объект, на который ссылается реквизит составного типа Договор (если он содержит какое-либо ссылочное значение). Если реквизит Договор хранит ссылку на объект типа ДокументСсылка.ДоговорНайма, то объект, на который ссылается Договор.Заявление так же должен быть добавлен в результате запроса.

Значение * в конце пути параметра $expand означает необходимость раскрыть все навигационные ссылки внутри сущности. Однако, нельзя раскрывать навигационные поля у составного реквизита без явного указания типа ссылки.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/Document_ДоговорНайма/*
				

В данном примере Договор - это составной реквизит. Данный вариант указания * не поддерживается.

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=*
				

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

Пример:

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/*
				

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

Ограничения параметра $expand:

• Не поддерживается расширение реквизитов табличных частей.
• Не поддерживается расширение при запросе одиночных сущностей (сущность, строки табличной части, запись регистра).
• Расширение ссылочных и составных типов виртуальных таблиц не соответствует протоколу OData версии 3.

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

https://host/base/zone/odata/standard.odata/AccountingRegister_РегистрБухгалтерии/Balance?$expand=Организация
				

В результате исполнения этого запроса будет получен следующий результат:

<d:Организация_Key>УникальныйИдентификатор</d:Организация_Key>
					<d:Организация>
					…ДанныеОбъекта…
					</d:Организация>
				

При расширении составного типа поведение аналогично, за исключением того, что данные объекта будут представлены в элементе с суффиксом _Expanded.

Способы получения описания стандартного интерфейса OData

Для получения упрощенного описания стандартного интерфейса OData (только список сущностей) необходимо выполнить GET-запрос с использованием URL https://host/base/zone/odata/standard.odata.

Для получения описания стандартного интерфейса OData необходимо выполнить GET-запрос с использованием URL https://host/base/zone/odata/standard.odata/$metadata. В результате будет получен полный список доступных сущностей, их атрибутов и функций в виде XML-документа. Подробное описание документа можно получить по адресу http://www.odata.org/documentation/odata-version-3-0/common-schema-definition-language-csdl/ (на английском языке).

В случае получение данных в формате json, не поддерживается запрос получения расширенного описания метаданных вида https://host/base/zone/odata/standard.odata/$metadata. Однако имеется возможность управлять детализацией информации о метаданных, которая возвращается при получении данных (как сущностей, так и списков сущностей). Для этого необходимо особым образом формировать параметр $format при выполнении запроса:

• $format=application/json;odata=minimalmetadata - в этом случае информация о метаданных передается в минимальном объеме. Это значение по умолчанию.
• $format=application/json;odata=nometadata - в этом случае информация о метаданных не передается вовсе.
• $format=application/json;odata=fullmetadata - в этом случае информация о метаданных передается в полном объеме.

Способы получения данных

С помощью стандартного интерфейса OData можно получать как списки сущностей, так и сами сущности. Эти способы получения данных отличаются URL, по которому происходит обращение к данным.

Для получения списка сущностей URL выглядит следующим образом: https://host/base/zone/odata/standard.odata/Catalog_Товары. Это URL набора сущностей. Для получения сущности URL будет выглядеть следующим образом: https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'value'). В общем виде такой адрес будет называться канонический URL экземпляра сущности. Разница заключается в том, что в первом случае получается вся таблица справочника товаров, а вот втором выбирается один объект, который описывается набором ключевых значений (в примере ключевое значение единственное - ссылка на объект). В конкретном случае набор ключевых полей, описывающих сущность, зависит от получаемой сущности. Если ключевых полей более одного, то они должны быть указаны все. Ключевые значения указываются парами Имя=Значение, разделенными запятыми. Если ключевое значение одно - имя ключа можно не указывать. Например, для получения значения курса валюты на конкретную дату необходимо выполнить GET-запрос со следующим URL:

https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют(Period=datetime'2008 02 05T00:00:00', Валюта_Key=guid'9d5c4222 8c4c 11db a9b0 00055d49b45e')

При получении данных существует возможность указать, какие свойства сущности (или набора сущностей) необходимо получить с помощью стандартного интерфейса OData. Для этого существует ключевое слово $select, которое имеет несколько вариантов использования:

• Признак получения всех свойств.

В этом случае следует указать выражение вида $select=* или совсем не указывать выражение $select.

• Перечень конкретных свойств, которые необходимо получить.

В этом случае необходимо указать в выражении оператора $select перечень (через запятую) всех необходимых полей. При этом следует указывать суффиксы свойств, если это необходимо. Например, для получения значения ссылки на справочник и свойств Код и Артикул, для справочника Товары, необходимо использовать следующий URL:

https://host/base/zone/odata/standard.odata/Catalog_Товары?$select=Ref_Key, Код, Артикул

Для получения этих же полей для конкретного экземпляра сущности (с известным идентификатором) будет использоваться следующий URL:

https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'value')?$select=Ref_Key, Код, Артикул

• Признак получения всех свойств, кроме табличных частей.

Для этого в выражении оператора $select необходимо указать значение **. При использовании следующего URL будут получены все документы РасходТовара со всеми реквизитами, кроме табличных частей:

https://host/base/zone/odata/standard.odata/Document_РасходТовара?$select=**

• Указание списка для получения связанных сущностей.

Допускается совместное использование параметров запроса $select и $expand. В этом случае с помощью параметра $expand указываются те свойства получаемой сущности, которые следует поместить в результат запроса. Конкретные значения получаемых (или разворачиваемых) свойств указывается с помощью параметра $select. Описание работа с параметром $expand более подробно см. здесь. В параметре $select, при использовании совместно с параметром $expand, поддерживается использование символов * и **. Указание символа * означает, что необходимо развернуть все реквизиты получаемого объекта. Указание символа ** означает, что необходимо развернуть все реквизиты получаемого объекта, кроме табличных частей.

https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Сертификат&$select=Сертификат/Дата
					https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Договор/Document_ДоговорНайма/Заявление&$select=Договор/Document_ДоговорНайма/Заявление/**
					https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют?$expand=Валюта&$select=Период,Валюта/Код,Курс
					https://host/base/zone/odata/standard.odata/Catalog_Клиенты?$expand=Сертификат&$select=Сертификат/*
				

Имеется возможность получать данные, доступные «через точку». В этом случае к адресу, описывающему конкретную сущность, прибавляются имена свойств, идущие «через точку», но разделенные символом «/». При этом для стандартных реквизитов следует использовать только английские имена реквизитов. Например, для получения свойства Наименование реквизита Валюта документа РасходТовара, необходимо использовать GET-запрос со следующим URL: https://host/base/zone/odata/standard.odata/Document_РасходТовара(guid'value')/Валюта/Description.

Выполнение функций и действий

С некоторыми сущностями и наборами сущностей могут быть связаны функции. Например, через функции выполняется работа с виртуальными таблицами регистров. В этом случае URL ресурса формируется следующим образом:

https://host/base/zone/odata/standard.odata/<ресурс>/<функция>(<параметры>). Подробнее рассмотрим, из чего состоит адрес. Первая часть адреса (http://host/base/odata/standard.odata) представляет собой стандартный префикс адреса при обращении к стандартному интерфейсу OData. <ресурс> - имя ресурса, правила формирования которого см. здесь. Имя функции соответствует англоязычному имени виртуальной таблицы языка запросов (см. здесь). <параметры> у функции задаются парами Ключ=Значение и разделяются запятыми. Если в качестве параметра функции используется отбор, то выражение, описывающее отбор, должно удовлетворять общим правилам описания отборов (см. здесь). Так, получение среза первых для регистра курсов валют (с параметрами), будет выполняться по следующему URL: http:// host/base/odata/standard.odata/InformationRegister_КурсыВалют/SliceFirst(Period=datetime'2008-01-01T00:00:00',Condition='Валюта_Key eq guid'value'').

Ошибочные ситуации

В случае ошибочной ситуации возвращается ответ с 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>
				

Примеры типовых операций

В данном разделе будут приведены примеры выполнения некоторых типовых операций по работе с данными с помощью стандартного интерфейса OData.

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

Чтение данных

Для получения информации о сущности следует использовать канонический URL сущности. Чтение выполняется с помощью GET-запроса.

Пример чтения ссылочного объекта:

https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'value')

Пример чтения набора записей подчиненного регистра сведений:

https://host/base/zone/odata/standard.odata/InformationRegister_ПриходныеЦены(Recorder_Key=guid'value')

В данном примере guid'value' идентифицирует документ, выполнивший движение по регистру сведений.

Пример чтения записи регистра сведений:

https://host/base/zone/odata/standard.odata/InformationRegister_ПриходныеЦены_RecordType(Товар_Key=guid'value', ТипЦены="Приходная")

Пример чтения строки конкретного документа:

https://host/base/zone/odata/standard.odata/Document_РасходТовара_Товары(Ref_Key=guid'value', LineNumber=1)

Чтение виртуальной таблицы СрезПоследних регистра сведений КурсыВалют (с отбором по измерению ОсновнаяВалюта типа СправочникСсылка.Валюты) будет выглядеть следующим образом:

Пример чтения независимого регистра сведений:

https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют/SliceLast?Condition=Валюта/ОсновнаяВалюта_Key eq guid'value'

Пример чтения подчиненного регистра сведений (к имени регистра следует добавить _RecordType):

https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют_RecordType/SliceLast?Condition=Валюта/ОсновнаяВалюта_Key eq guid'value'

В данном примере guid'value' идентифицирует элемент справочника Валюты, по значению которого выполняется отбор.

Пример получения остатков на счете из регистра бухгалтерии с условием по конкретному контрагенту:

https://host/base/zone/odata/standard.odata/AccountingRegister_Хозрасчетный/Balance(AccountCondition='Account_Key eq guid'value1'',Condition='ExtDimension1 eq cast(guid'value2', 'Catalog_Контрагенты')',ExtraDimensions='value3')?$format=json

В данном примере:

• guid'value1' - уникальный идентификатор элемента плана счетов;
• guid'value2' - уникальный идентификатор элемента плана видов характеристик ВидыСубконтоХозрасчетные с типом значения СправочникСсылка.Контрагенты;
• 'value3' - уникальный идентификатор элемента справочника Контрагенты.

Создание объекта

Для создания объекта следует воспользоваться POST-запросом с использованием URL набора сущностей, передав в теле запроса документ (в поддерживаемом формате), который содержит значения полей создаваемого объекта. Если передаваемый документ содержит свойства, отсутствующие у создаваемого объекта, то эти свойства игнорируются.

Далее приводится пример создания элемента справочника Товары и ответ стандартного интерфейса OData после успешного выполнения операции.

Пример POST-запроса (формат atom):

POST https://host/base/zone/odata/standard.odata/Catalog_Товары HTTP/1.1
					User Agent: Fiddler
					Host: host
					Content Length: 981
					<entry>
					<category term="StandardODATA.Catalog_Товары" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
					<title type="text"/>
					<updated>2014 02 14T12:05:55</updated>
					<author/>
					<summary/>
					<content type="application/xml">
					<m:properties xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
					<d:DeletionMark>false</d:DeletionMark>
					<d:Parent_Key>bbb079ae 8c51 11db a9b0 00055d49b45e</d:Parent_Key>
					<d:IsFolder>false</d:IsFolder>
					<d:Code>000000800</d:Code>
					<d:Description>Шлепанцы</d:Description>
					<d:Артикул>SL56X</d:Артикул>
					<d:Поставщик_Key>086715b0 f348 11db a9c5 00055d49b45e</d:Поставщик_Key>
					<d:Вид>Товар</d:Вид>
					<d:Штрихкод/>
					<d:Описание>&lt;html&gt;Шлепанцы пляжные&lt;/html&gt;</d:Описание>
					</m:properties>
					</content>
					</entry>
				

Пример ответа стандартного интерфейса OData:

HTTP/1.1 201 Created
					Content Length: 2705
					Content Type: application/atom+xml;type=entry;charset=utf 8
					Location: https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')
					Server: Microsoft IIS/7.5
					DataServiceVersion: 3.0
					X Powered By: ASP.NET
					Date: Fri, 14 Feb 2014 08:18:36 GMT
					<?xml version="1.0" encoding="UTF 8"?>
					<entry xmlns="http://www.w3.org/2005/Atom"
					xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
					<id>https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')</id>
					<category term="StandardODATA.Catalog_Товары" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
					<title type="text"/>
					<updated>2014 02 14T12:18:36</updated>
					<author/>
					<summary/>
					<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ФайлКартинки"
					href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')/ФайлКартинки"
					type="application/atom+xml;type=entry;charset=utf 8"
					title="ФайлКартинки"/>
					<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Parent"
					href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')/Parent"
					type="application/atom+xml;type=entry;charset=utf 8"
					title="Parent"/>
					<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Поставщик"
					href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')/Поставщик"
					type="application/atom+xml;type=entry;charset=utf 8"
					title="Поставщик"/>
					<link rel="edit"
					href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')"
					title="edit link"/>
					<content type="application/xml">
					<m:properties xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
					<d:Ref_Key>41aa6331 954f 11e3 814b 005056c00008</d:Ref_Key>
					<d:DataVersion m:null="true"/>
					<d:Description>Шлепанцы</d:Description>
					<d:Code>000000800</d:Code>
					<d:Parent_Key>bbb079ae 8c51 11db a9b0 00055d49b45e</d:Parent_Key>
					<d:IsFolder>false</d:IsFolder>
					<d:DeletionMark>false</d:DeletionMark>
					<d:Артикул>SL56X</d:Артикул>
					<d:Поставщик_Key>086715b0 f348 11db a9c5 00055d49b45e</d:Поставщик_Key>
					<d:ФайлКартинки_Key>00000000 0000 0000 0000 000000000000</d:ФайлКартинки_Key>
					<d:Вид>Товар</d:Вид>
					<d:Штрихкод/>
					<d:Описание>&lt;html&gt;Шлепанцы пляжные&lt;/html&gt;</d:Описание>
					<d:ФайлКартинки_Key>00000000 0000 0000 0000 000000000000</d:ФайлКартинки_Key>
					<d:Parent_Key>bbb079ae 8c51 11db a9b0 00055d49b45e</d:Parent_Key>
					<d:Поставщик_Key>086715b0 f348 11db a9c5 00055d49b45e</d:Поставщик_Key>
					</m:properties>
					</content>
					</entry>
				

Пример POST-запроса (формат json):

POST https://host/base/zone/odata/standard.odata/Catalog_Товары HTTP/1.1
					Accept: application/json
					Accept Charset: UTF 8
					User Agent: Fiddler
					Content Type: application/json
					Content Length: 2426
					{
						"DeletionMark":false,
						"Parent_Key":"bbb079ae 8c51 11db a9b0 00055d49b45e",
						"IsFolder":false
						"Code":"000000800",
						"Description":"Шлепанцы",
						"Артикул":"SL56X",
						"Поставщик_Key":"086715b0 f348 11db a9c5 00055d49b45e",
						"Вид":"Товар",
						"Штрихкод":null,
						"Описание:"Шлепанцы пляжные"
						}
					

Обновление объекта

Для обновления объекта необходимо выполнить PUT-/PATCH-запрос с использованием канонического URL сущности (аналогично запросу GET для получения сущности), передав в теле запроса XML-документ (в формате atom) или JSON-документ (в формате json), который содержит значения свойств сущности. Если передаваемый документ содержит свойства, отсутствующие у создаваемого объекта, то эти свойства игнорируются.

В случае PATCH-запроса пропущенные свойства сущности будут проигнорированы, т. е. будут изменены только те свойства, которые переданы в запросе на изменение. Для PUT-запроса необходимо указывать значения всех свойств обновляемой сущности.

При модификации сущности через PUT-запрос, при записи значений ссылочных реквизитов, следует использовать поле ИмяСсылочногоРеквизита@odata.bind куда следует поместить URI-сущности (можно в укороченном варианте - только фрагмент пути после standard.odata).

Например:

PUT http://host /base/odata/standard.odata/Document_Документ(guid'19961ec3 3c5f 11e7 8785 50465da19fe4')?$format=json
						{
							"Date": "2015 01 01T12:01:07",
							"Организация@odata.bind": "Catalog_Организации(guid'298584b5 92e4 11e3 8bc3 0050568b1678')",
							"Склад@odata.bind": http://host /base/odata/standard.odata/Catalog_Склады(guid'081bc346 2abc 13e4 a1bd 0050568b1688')
							…
						}
					

В следующем примере рассматривается изменение реквизита Наименование и состава табличной части ТорговыеЗалы справочника Магазины. Остальные реквизиты справочника не используются в рамках данного примера. В примере используется формат данных json.

Пример PATCH-запроса:

PATCH https://host/base/zone/odata/standard.odata/Catalog_Магазины(guid'value')?$format=json HTTP/1.1
						Host: host
						Connection: keep alive
						Accept: application/json
						Content Length: 638
						{
							"odata.metadata": "https://host/base/zone/odata/standard.odata/$metadata#Catalog_Магазины/@Element",
							"Description": "Новое описание магазина",
							"ТорговыеЗалы@odata.type" : "Collection(StandardODATA.Catalog_Магазины_ТорговыеЗалы_RowType)"
							"ТорговыеЗалы": [
							{
								"LineNumber": "1",
								"Название": "Синий зал",
								"Площадь": 56,
								"ДатаОткрытия": "2015 01 01T00:00:00"
							},
							{
								"LineNumber": "2",
								"Название": "Красный зал",
								"Площадь": 56,
								"ДатаОткрытия": "2015 06 13T11:45:41"
							}
							]
						}
					

В данном примере guid'value' идентифицирует изменяемый элемент справочника Магазины.

Удаление объекта

Для удаления объекта следует воспользоваться DELETE-запросом с использованием канонического URL сущности.

Оптимистическая блокировка данных

Для оптимистической блокировки данных (т.е. для проверки, что данные не изменились с момента считывания) нужно использовать заголовок If-Match HTTP-запроса, связанного с модификацией (PATCH) или удалением (DELETE) данных.

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

Механизм работает следующим образом:

• При запросе экземпляра сущности среди прочих возвращается свойство DataVersion. При запросе набора сущностей с каждой из сущностей набора возвращается свойство DataVersion.
• Клиентское приложение должно сохранить у себя это значение версии объекта и затем использовать его в запросах PATCH и DELETE, передавая его в заголовке If-Match.
• Если значение свойства DataVersion в момент исполнения запроса совпадает со значением заголовка If-Match, то происходит запрошенное действие. В противном случае действие не выполняется, а клиенту возвращается HTTP статус 412.

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

Если при записи объекта необходимо эмулировать запись, выполняемую во время работы механизма обмена данными (свойство ОбменДанными.Загрузка = Истина) следует использовать HTTP-заголовок 1C_OData-DataLoadMode со значением true при выполнении соответствующей операции записи.

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

Для проведения документа необходимо выполнить POST-запрос с использованием канонического URL сущности (аналогично запросу GET для получения сущности), указав особым образом сформированный суффикс URL. Суффикс в этом случае будет состоять из команды Post и параметра, указывающего режим проведения документа: https://host/base/zone/odata/standard.odata/Document_РасходТоваров(guid'value')/Post?PostingModeOperational=false.

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

Работа с коллекцией объектов

Для получения набора сущностей какого-либо вида, следует выполнить GET-запрос с использованием URL следующего вида: https://host/base/zone/odata/standard.odata/ExchangePlan_ОбменДанными.

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

http://host/base/standard.odata/Document_Накладная?$filter=Приоритет eq 1

Обращение к виртуальной таблице регистра выглядит следующим образом (на примере виртуальной таблицы ОстаткиИОбороты регистра накопления ТоварныеЗапасы):

https://host/base/zone/odata/standard.odata/AccumulationRegister_ТоварныеЗапасы/BalanceAndTurnovers(StartPeriod=datetime'2014 01 01', EndPeriod=datetime'2014 02 01', Condition='Товар_Key eq guid'value'')1

Также для ограничения набора сущностей можно использовать параметры $top и $select (см. здесь).

Работа с планами обмена

Формирование сообщения обмена

Для формирования сообщения обмена необходимо выполнить POST-запрос с использованием URL следующего вида: https://host/base/zone/odata/standard.odata/SelectChanges?<params>. Где в качестве параметров необходимо указать следующее:

• Параметр DataExchangePoint - должен содержать канонический URL сущности треуемого элемента плана обмена;
• Параметр MessageNo - должен содержать номер сообщения обмена данными, который будет сформирован в результате данного вызова.

В результате, полный URL для формирования сообщения обмена, будет выглядеть следующим образом: https://host/base/zone/odata/standard.odata/SelectChanges?DataExchangePoint='https://host/base/zone/odata/standard.odata/ExchangePlan_ОбменДанными(guid'value')'&MessageNo=34.

В результате будет получен список изменений, которые необходимо передать в другой узел, в виде потока atom-feed. Каждый элемент будет представлен в формате atom-entry, а удаленные элементы будет представлены в формате atom-deleted-entry (RFC 6721, http://tools.ietf.org/html/rfc6721, на английском языке).

Уведомление о получении изменений

Для уведомления сервера о том, что сообщение обмена успешно получено, необходимо выполнить POST-запрос с использованием URL следующего вида: https://host/base/zone/odata/standard.odata/NotifyChangesReceived?<params>. Где в качестве параметров необходимо указать следующее:

• Параметр DataExchangePoint - должен содержать канонический URL сущности требуемого элемента плана обмена;
• Параметр MessageNo - должен содержать номер сообщения обмена данными, подтверждение получения которого необходимо зафиксировать.

В результате, полный URL для подтверждения получения сообщения обмена, будет выглядеть следующим образом: https://host/base/zone/odata/standard.odata/NotifyChangesReceived?DataExchangePoint='https://host/base/zone/odata/standard.odata/ExchangePlan_ОбменДанными(guid'value')'&MessageNo=34.

Работа с OData из Microsoft Excel

В качестве примера работы с OData из сторонних программ можно привести Excel. Для использования OData нужно в разделе “Данные” в меню “Получить данные” выбрать “Из других источников” → “Из канала OData”.

В открывшемся окне нужно указать ссылку на нужную сущность, например на список контрагентов https://bp.42clouds.com/bp_base1/12345/odata/standard.odata/Catalog_Контрагенты

На форме авторизации нужно выбрать “Базовый”, ввести логин/пароль пользователя (служебного или обычного), в качестве уровня, к которому следует применить эти параметры, указать вашу область данных, нажать “Подключение”.

Excel выведет данные предварительного просмотра, которые можно будет загрузить в таблицу или преобразовать.